vortex_vector/
vector.rs

1// SPDX-License-Identifier: Apache-2.0
2// SPDX-FileCopyrightText: Copyright the Vortex contributors
3
4//! Definition of the [`Vector`] type, which represents immutable and fully decompressed (canonical)
5//! array data.
6//!
7//! [`Vector`] can be transformed into the [`VectorMut`] type if it is owned.
8
9use std::fmt::Debug;
10use std::ops::RangeBounds;
11
12use crate::Scalar;
13use crate::VectorMut;
14use crate::VectorOps;
15use crate::binaryview::BinaryVector;
16use crate::binaryview::StringVector;
17use crate::bool::BoolVector;
18use crate::decimal::DecimalVector;
19use crate::fixed_size_list::FixedSizeListVector;
20use crate::listview::ListViewVector;
21use crate::match_each_vector;
22use crate::null::NullVector;
23use crate::primitive::PrimitiveVector;
24use crate::struct_::StructVector;
25use vortex_error::vortex_panic;
26use vortex_mask::Mask;
27
28/// An enum over all kinds of immutable vectors, which represent fully decompressed (canonical)
29/// array data.
30///
31/// Most of the behavior of `Vector` is described by the [`VectorOps`] trait. Note that vectors are
32/// **always** considered as nullable, and it is the responsibility of the user to not add any
33/// nullable data to a vector they want to keep as non-nullable.
34///
35/// The mutable equivalent of this type is [`VectorMut`], which implements the
36/// [`VectorMutOps`](crate::VectorMutOps) trait.
37#[derive(Debug, Clone)]
38pub enum Vector {
39    /// Null vectors.
40    Null(NullVector),
41    /// Boolean vectors.
42    Bool(BoolVector),
43    /// Decimal vectors.
44    ///
45    /// Note that [`DecimalVector`] is an enum over the different possible (generic)
46    /// [`DVector<D>`](crate::decimal::DVector)s.
47    ///
48    /// See the [documentation](crate::decimal) for more information.
49    Decimal(DecimalVector),
50    /// Primitive vectors.
51    ///
52    /// Note that [`PrimitiveVector`] is an enum over the different possible (generic)
53    /// [`PVector<T>`](crate::primitive::PVector)s.
54    ///
55    /// See the [documentation](crate::primitive) for more information.
56    Primitive(PrimitiveVector),
57    /// String vectors
58    String(StringVector),
59    /// Binary vectors
60    Binary(BinaryVector),
61    /// Vectors of Lists with variable sizes.
62    List(ListViewVector),
63    /// Vectors of Lists with fixed sizes.
64    FixedSizeList(FixedSizeListVector),
65    /// Vectors of Struct elements.
66    Struct(StructVector),
67}
68
69impl PartialEq for Vector {
70    fn eq(&self, other: &Self) -> bool {
71        // Validity patterns must match
72        if self.validity() != other.validity() {
73            return false;
74        }
75        // Delegate to the underlying vector type equality
76        match (self, other) {
77            (Vector::Null(a), Vector::Null(b)) => a == b,
78            (Vector::Bool(a), Vector::Bool(b)) => a == b,
79            (Vector::Decimal(a), Vector::Decimal(b)) => a == b,
80            (Vector::Primitive(a), Vector::Primitive(b)) => a == b,
81            (Vector::String(a), Vector::String(b)) => a == b,
82            (Vector::Binary(a), Vector::Binary(b)) => a == b,
83            (Vector::List(a), Vector::List(b)) => a == b,
84            (Vector::FixedSizeList(a), Vector::FixedSizeList(b)) => a == b,
85            (Vector::Struct(a), Vector::Struct(b)) => a == b,
86            _ => false, // Different variants are not equal
87        }
88    }
89}
90
91impl VectorOps for Vector {
92    type Mutable = VectorMut;
93    type Scalar = Scalar;
94
95    fn len(&self) -> usize {
96        match_each_vector!(self, |v| { v.len() })
97    }
98
99    fn validity(&self) -> &Mask {
100        match_each_vector!(self, |v| { v.validity() })
101    }
102
103    fn mask_validity(&mut self, mask: &Mask) {
104        match_each_vector!(self, |v| { v.mask_validity(mask) })
105    }
106
107    fn scalar_at(&self, index: usize) -> Scalar {
108        match_each_vector!(self, |v| { v.scalar_at(index).into() })
109    }
110
111    fn slice(&self, range: impl RangeBounds<usize> + Clone + Debug) -> Self {
112        match_each_vector!(self, |v| { Vector::from(v.slice(range)) })
113    }
114
115    fn clear(&mut self) {
116        match_each_vector!(self, |v| { v.clear() })
117    }
118
119    fn try_into_mut(self) -> Result<VectorMut, Self> {
120        match_each_vector!(self, |v| {
121            v.try_into_mut().map(VectorMut::from).map_err(Vector::from)
122        })
123    }
124
125    fn into_mut(self) -> VectorMut {
126        match_each_vector!(self, |v| { VectorMut::from(v.into_mut()) })
127    }
128}
129
130impl Vector {
131    /// Returns a reference to the inner [`NullVector`] if `self` is of that variant.
132    pub fn as_null(&self) -> &NullVector {
133        if let Vector::Null(v) = self {
134            return v;
135        }
136        vortex_panic!("Expected NullVector, got {self:?}");
137    }
138
139    /// Returns a reference to the inner [`BoolVector`] if `self` is of that variant.
140    pub fn as_bool(&self) -> &BoolVector {
141        if let Vector::Bool(v) = self {
142            return v;
143        }
144        vortex_panic!("Expected BoolVector, got {self:?}");
145    }
146
147    /// Returns a reference to the inner [`PrimitiveVector`] if `self` is of that variant.
148    pub fn as_primitive(&self) -> &PrimitiveVector {
149        if let Vector::Primitive(v) = self {
150            return v;
151        }
152        vortex_panic!("Expected PrimitiveVector, got {self:?}");
153    }
154
155    /// Returns a reference to the inner [`StringVector`] if `self` is of that variant.
156    pub fn as_string(&self) -> &StringVector {
157        if let Vector::String(v) = self {
158            return v;
159        }
160        vortex_panic!("Expected StringVector, got {self:?}");
161    }
162
163    /// Returns a reference to the inner [`BinaryVector`] if `self` is of that variant.
164    pub fn as_binary(&self) -> &BinaryVector {
165        if let Vector::Binary(v) = self {
166            return v;
167        }
168        vortex_panic!("Expected BinaryVector, got {self:?}");
169    }
170
171    /// Returns a reference to the inner [`ListViewVector`] if `self` is of that variant.
172    pub fn as_list(&self) -> &ListViewVector {
173        if let Vector::List(v) = self {
174            return v;
175        }
176        vortex_panic!("Expected ListViewVector, got {self:?}");
177    }
178
179    /// Returns a reference to the inner [`FixedSizeListVector`] if `self` is of that variant.
180    pub fn as_fixed_size_list(&self) -> &FixedSizeListVector {
181        if let Vector::FixedSizeList(v) = self {
182            return v;
183        }
184        vortex_panic!("Expected FixedSizeListVector, got {self:?}");
185    }
186
187    /// Returns a reference to the inner [`StructVector`] if `self` is of that variant.
188    pub fn as_struct(&self) -> &StructVector {
189        if let Vector::Struct(v) = self {
190            return v;
191        }
192        vortex_panic!("Expected StructVector, got {self:?}");
193    }
194}
195
196impl Vector {
197    /// Returns a reference to the inner [`NullVector`] if `self` is of that variant.
198    pub fn as_null_mut(&mut self) -> &mut NullVector {
199        if let Vector::Null(v) = self {
200            return v;
201        }
202        vortex_panic!("Expected NullVector, got {self:?}");
203    }
204
205    /// Returns a reference to the inner [`BoolVector`] if `self` is of that variant.
206    pub fn as_bool_mut(&mut self) -> &mut BoolVector {
207        if let Vector::Bool(v) = self {
208            return v;
209        }
210        vortex_panic!("Expected BoolVector, got {self:?}");
211    }
212
213    /// Returns a reference to the inner [`PrimitiveVector`] if `self` is of that variant.
214    pub fn as_primitive_mut(&mut self) -> &mut PrimitiveVector {
215        if let Vector::Primitive(v) = self {
216            return v;
217        }
218        vortex_panic!("Expected PrimitiveVector, got {self:?}");
219    }
220
221    /// Returns a reference to the inner [`StringVector`] if `self` is of that variant.
222    pub fn as_string_mut(&mut self) -> &mut StringVector {
223        if let Vector::String(v) = self {
224            return v;
225        }
226        vortex_panic!("Expected StringVector, got {self:?}");
227    }
228
229    /// Returns a reference to the inner [`BinaryVector`] if `self` is of that variant.
230    pub fn as_binary_mut(&mut self) -> &mut BinaryVector {
231        if let Vector::Binary(v) = self {
232            return v;
233        }
234        vortex_panic!("Expected BinaryVector, got {self:?}");
235    }
236
237    /// Returns a reference to the inner [`ListViewVector`] if `self` is of that variant.
238    pub fn as_list_mut(&mut self) -> &mut ListViewVector {
239        if let Vector::List(v) = self {
240            return v;
241        }
242        vortex_panic!("Expected ListViewVector, got {self:?}");
243    }
244
245    /// Returns a reference to the inner [`FixedSizeListVector`] if `self` is of that variant.
246    pub fn as_fixed_size_list_mut(&mut self) -> &mut FixedSizeListVector {
247        if let Vector::FixedSizeList(v) = self {
248            return v;
249        }
250        vortex_panic!("Expected FixedSizeListVector, got {self:?}");
251    }
252
253    /// Returns a reference to the inner [`StructVector`] if `self` is of that variant.
254    pub fn as_struct_mut(&mut self) -> &mut StructVector {
255        if let Vector::Struct(v) = self {
256            return v;
257        }
258        vortex_panic!("Expected StructVector, got {self:?}");
259    }
260}
261
262impl Vector {
263    /// Consumes `self` and returns the inner [`NullVector`] if `self` is of that variant.
264    pub fn into_null(self) -> NullVector {
265        if let Vector::Null(v) = self {
266            return v;
267        }
268        vortex_panic!("Expected NullVector, got {self:?}");
269    }
270
271    /// Consumes `self` and returns the inner [`BoolVector`] if `self` is of that variant.
272    pub fn into_bool(self) -> BoolVector {
273        if let Vector::Bool(v) = self {
274            return v;
275        }
276        vortex_panic!("Expected BoolVector, got {self:?}");
277    }
278
279    /// Consumes `self` and returns the inner [`PrimitiveVector`] if `self` is of that variant.
280    pub fn into_primitive(self) -> PrimitiveVector {
281        if let Vector::Primitive(v) = self {
282            return v;
283        }
284        vortex_panic!("Expected PrimitiveVector, got {self:?}");
285    }
286
287    /// Consumes `self` and returns the inner [`DecimalVector`] if `self` is of that variant.
288    pub fn into_decimal(self) -> DecimalVector {
289        if let Vector::Decimal(v) = self {
290            return v;
291        }
292        vortex_panic!("Expected DecimalVector, got {self:?}");
293    }
294
295    /// Consumes `self` and returns the inner [`StringVector`] if `self` is of that variant.
296    #[expect(
297        clippy::same_name_method,
298        reason = "intentionally shadows VarBinTypeDowncast method"
299    )]
300    pub fn into_string(self) -> StringVector {
301        if let Vector::String(v) = self {
302            return v;
303        }
304        vortex_panic!("Expected StringVector, got {self:?}");
305    }
306
307    /// Consumes `self` and returns the inner [`BinaryVector`] if `self` is of that variant.
308    #[expect(
309        clippy::same_name_method,
310        reason = "intentionally shadows VarBinTypeDowncast method"
311    )]
312    pub fn into_binary(self) -> BinaryVector {
313        if let Vector::Binary(v) = self {
314            return v;
315        }
316        vortex_panic!("Expected BinaryVector, got {self:?}");
317    }
318
319    /// Consumes `self` and returns the inner [`ListViewVector`] if `self` is of that variant.
320    pub fn into_list(self) -> ListViewVector {
321        if let Vector::List(v) = self {
322            return v;
323        }
324        vortex_panic!("Expected ListViewVector, got {self:?}");
325    }
326
327    /// Consumes `self` and returns the inner [`FixedSizeListVector`] if `self` is of that
328    /// variant.
329    pub fn into_fixed_size_list(self) -> FixedSizeListVector {
330        if let Vector::FixedSizeList(v) = self {
331            return v;
332        }
333        vortex_panic!("Expected FixedSizeListVector, got {self:?}");
334    }
335
336    /// Consumes `self` and returns the inner [`StructVector`] if `self` is of that variant.
337    pub fn into_struct(self) -> StructVector {
338        if let Vector::Struct(v) = self {
339            return v;
340        }
341        vortex_panic!("Expected StructVector, got {self:?}");
342    }
343}
344
345impl Vector {
346    /// Consumes `self` and returns the inner [`NullVector`] if `self` is of that variant.
347    pub fn into_null_opt(self) -> Option<NullVector> {
348        if let Vector::Null(v) = self {
349            Some(v)
350        } else {
351            None
352        }
353    }
354
355    /// Consumes `self` and returns the inner [`BoolVector`] if `self` is of that variant.
356    pub fn into_bool_opt(self) -> Option<BoolVector> {
357        if let Vector::Bool(v) = self {
358            Some(v)
359        } else {
360            None
361        }
362    }
363
364    /// Consumes `self` and returns the inner [`PrimitiveVector`] if `self` is of that variant.
365    pub fn into_primitive_opt(self) -> Option<PrimitiveVector> {
366        if let Vector::Primitive(v) = self {
367            Some(v)
368        } else {
369            None
370        }
371    }
372
373    /// Consumes `self` and returns the inner [`DecimalVector`] if `self` is of that variant.
374    pub fn into_decimal_opt(self) -> Option<DecimalVector> {
375        if let Vector::Decimal(v) = self {
376            Some(v)
377        } else {
378            None
379        }
380    }
381
382    /// Consumes `self` and returns the inner [`StringVector`] if `self` is of that variant.
383    pub fn into_string_opt(self) -> Option<StringVector> {
384        if let Vector::String(v) = self {
385            Some(v)
386        } else {
387            None
388        }
389    }
390
391    /// Consumes `self` and returns the inner [`BinaryVector`] if `self` is of that variant.
392    pub fn into_binary_opt(self) -> Option<BinaryVector> {
393        if let Vector::Binary(v) = self {
394            Some(v)
395        } else {
396            None
397        }
398    }
399
400    /// Consumes `self` and returns the inner [`ListViewVector`] if `self` is of that variant.
401    pub fn into_list_opt(self) -> Option<ListViewVector> {
402        if let Vector::List(v) = self {
403            Some(v)
404        } else {
405            None
406        }
407    }
408
409    /// Consumes `self` and returns the inner [`FixedSizeListVector`] if `self` is of that variant.
410    pub fn into_fixed_size_list_opt(self) -> Option<FixedSizeListVector> {
411        if let Vector::FixedSizeList(v) = self {
412            Some(v)
413        } else {
414            None
415        }
416    }
417
418    /// Consumes `self` and returns the inner [`StructVector`] if `self` is of that variant.
419    pub fn into_struct_opt(self) -> Option<StructVector> {
420        if let Vector::Struct(v) = self {
421            Some(v)
422        } else {
423            None
424        }
425    }
426}
vortex_vector/vector.rs

vortex_vector/
vector.rs
