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 VectorOps for Vector {
70    type Mutable = VectorMut;
71    type Scalar = Scalar;
72
73    fn len(&self) -> usize {
74        match_each_vector!(self, |v| { v.len() })
75    }
76
77    fn validity(&self) -> &Mask {
78        match_each_vector!(self, |v| { v.validity() })
79    }
80
81    fn mask_validity(&mut self, mask: &Mask) {
82        match_each_vector!(self, |v| { v.mask_validity(mask) })
83    }
84
85    fn scalar_at(&self, index: usize) -> Scalar {
86        match_each_vector!(self, |v| { v.scalar_at(index).into() })
87    }
88
89    fn slice(&self, range: impl RangeBounds<usize> + Clone + Debug) -> Self {
90        match_each_vector!(self, |v| { Vector::from(v.slice(range)) })
91    }
92
93    fn clear(&mut self) {
94        match_each_vector!(self, |v| { v.clear() })
95    }
96
97    fn try_into_mut(self) -> Result<VectorMut, Self> {
98        match_each_vector!(self, |v| {
99            v.try_into_mut().map(VectorMut::from).map_err(Vector::from)
100        })
101    }
102
103    fn into_mut(self) -> VectorMut {
104        match_each_vector!(self, |v| { VectorMut::from(v.into_mut()) })
105    }
106}
107
108impl Vector {
109    /// Returns a reference to the inner [`NullVector`] if `self` is of that variant.
110    pub fn as_null(&self) -> &NullVector {
111        if let Vector::Null(v) = self {
112            return v;
113        }
114        vortex_panic!("Expected NullVector, got {self:?}");
115    }
116
117    /// Returns a reference to the inner [`BoolVector`] if `self` is of that variant.
118    pub fn as_bool(&self) -> &BoolVector {
119        if let Vector::Bool(v) = self {
120            return v;
121        }
122        vortex_panic!("Expected BoolVector, got {self:?}");
123    }
124
125    /// Returns a reference to the inner [`PrimitiveVector`] if `self` is of that variant.
126    pub fn as_primitive(&self) -> &PrimitiveVector {
127        if let Vector::Primitive(v) = self {
128            return v;
129        }
130        vortex_panic!("Expected PrimitiveVector, got {self:?}");
131    }
132
133    /// Returns a reference to the inner [`StringVector`] if `self` is of that variant.
134    pub fn as_string(&self) -> &StringVector {
135        if let Vector::String(v) = self {
136            return v;
137        }
138        vortex_panic!("Expected StringVector, got {self:?}");
139    }
140
141    /// Returns a reference to the inner [`BinaryVector`] if `self` is of that variant.
142    pub fn as_binary(&self) -> &BinaryVector {
143        if let Vector::Binary(v) = self {
144            return v;
145        }
146        vortex_panic!("Expected BinaryVector, got {self:?}");
147    }
148
149    /// Returns a reference to the inner [`ListViewVector`] if `self` is of that variant.
150    pub fn as_list(&self) -> &ListViewVector {
151        if let Vector::List(v) = self {
152            return v;
153        }
154        vortex_panic!("Expected ListViewVector, got {self:?}");
155    }
156
157    /// Returns a reference to the inner [`FixedSizeListVector`] if `self` is of that variant.
158    pub fn as_fixed_size_list(&self) -> &FixedSizeListVector {
159        if let Vector::FixedSizeList(v) = self {
160            return v;
161        }
162        vortex_panic!("Expected FixedSizeListVector, got {self:?}");
163    }
164
165    /// Returns a reference to the inner [`StructVector`] if `self` is of that variant.
166    pub fn as_struct(&self) -> &StructVector {
167        if let Vector::Struct(v) = self {
168            return v;
169        }
170        vortex_panic!("Expected StructVector, got {self:?}");
171    }
172}
173
174impl Vector {
175    /// Returns a reference to the inner [`NullVector`] if `self` is of that variant.
176    pub fn as_null_mut(&mut self) -> &mut NullVector {
177        if let Vector::Null(v) = self {
178            return v;
179        }
180        vortex_panic!("Expected NullVector, got {self:?}");
181    }
182
183    /// Returns a reference to the inner [`BoolVector`] if `self` is of that variant.
184    pub fn as_bool_mut(&mut self) -> &mut BoolVector {
185        if let Vector::Bool(v) = self {
186            return v;
187        }
188        vortex_panic!("Expected BoolVector, got {self:?}");
189    }
190
191    /// Returns a reference to the inner [`PrimitiveVector`] if `self` is of that variant.
192    pub fn as_primitive_mut(&mut self) -> &mut PrimitiveVector {
193        if let Vector::Primitive(v) = self {
194            return v;
195        }
196        vortex_panic!("Expected PrimitiveVector, got {self:?}");
197    }
198
199    /// Returns a reference to the inner [`StringVector`] if `self` is of that variant.
200    pub fn as_string_mut(&mut self) -> &mut StringVector {
201        if let Vector::String(v) = self {
202            return v;
203        }
204        vortex_panic!("Expected StringVector, got {self:?}");
205    }
206
207    /// Returns a reference to the inner [`BinaryVector`] if `self` is of that variant.
208    pub fn as_binary_mut(&mut self) -> &mut BinaryVector {
209        if let Vector::Binary(v) = self {
210            return v;
211        }
212        vortex_panic!("Expected BinaryVector, got {self:?}");
213    }
214
215    /// Returns a reference to the inner [`ListViewVector`] if `self` is of that variant.
216    pub fn as_list_mut(&mut self) -> &mut ListViewVector {
217        if let Vector::List(v) = self {
218            return v;
219        }
220        vortex_panic!("Expected ListViewVector, got {self:?}");
221    }
222
223    /// Returns a reference to the inner [`FixedSizeListVector`] if `self` is of that variant.
224    pub fn as_fixed_size_list_mut(&mut self) -> &mut FixedSizeListVector {
225        if let Vector::FixedSizeList(v) = self {
226            return v;
227        }
228        vortex_panic!("Expected FixedSizeListVector, got {self:?}");
229    }
230
231    /// Returns a reference to the inner [`StructVector`] if `self` is of that variant.
232    pub fn as_struct_mut(&mut self) -> &mut StructVector {
233        if let Vector::Struct(v) = self {
234            return v;
235        }
236        vortex_panic!("Expected StructVector, got {self:?}");
237    }
238}
239
240impl Vector {
241    /// Consumes `self` and returns the inner [`NullVector`] if `self` is of that variant.
242    pub fn into_null(self) -> NullVector {
243        if let Vector::Null(v) = self {
244            return v;
245        }
246        vortex_panic!("Expected NullVector, got {self:?}");
247    }
248
249    /// Consumes `self` and returns the inner [`BoolVector`] if `self` is of that variant.
250    pub fn into_bool(self) -> BoolVector {
251        if let Vector::Bool(v) = self {
252            return v;
253        }
254        vortex_panic!("Expected BoolVector, got {self:?}");
255    }
256
257    /// Consumes `self` and returns the inner [`PrimitiveVector`] if `self` is of that variant.
258    pub fn into_primitive(self) -> PrimitiveVector {
259        if let Vector::Primitive(v) = self {
260            return v;
261        }
262        vortex_panic!("Expected PrimitiveVector, got {self:?}");
263    }
264
265    /// Consumes `self` and returns the inner [`DecimalVector`] if `self` is of that variant.
266    pub fn into_decimal(self) -> DecimalVector {
267        if let Vector::Decimal(v) = self {
268            return v;
269        }
270        vortex_panic!("Expected DecimalVector, got {self:?}");
271    }
272
273    /// Consumes `self` and returns the inner [`StringVector`] if `self` is of that variant.
274    #[expect(
275        clippy::same_name_method,
276        reason = "intentionally shadows VarBinTypeDowncast method"
277    )]
278    pub fn into_string(self) -> StringVector {
279        if let Vector::String(v) = self {
280            return v;
281        }
282        vortex_panic!("Expected StringVector, got {self:?}");
283    }
284
285    /// Consumes `self` and returns the inner [`BinaryVector`] if `self` is of that variant.
286    #[expect(
287        clippy::same_name_method,
288        reason = "intentionally shadows VarBinTypeDowncast method"
289    )]
290    pub fn into_binary(self) -> BinaryVector {
291        if let Vector::Binary(v) = self {
292            return v;
293        }
294        vortex_panic!("Expected BinaryVector, got {self:?}");
295    }
296
297    /// Consumes `self` and returns the inner [`ListViewVector`] if `self` is of that variant.
298    pub fn into_list(self) -> ListViewVector {
299        if let Vector::List(v) = self {
300            return v;
301        }
302        vortex_panic!("Expected ListViewVector, got {self:?}");
303    }
304
305    /// Consumes `self` and returns the inner [`FixedSizeListVector`] if `self` is of that
306    /// variant.
307    pub fn into_fixed_size_list(self) -> FixedSizeListVector {
308        if let Vector::FixedSizeList(v) = self {
309            return v;
310        }
311        vortex_panic!("Expected FixedSizeListVector, got {self:?}");
312    }
313
314    /// Consumes `self` and returns the inner [`StructVector`] if `self` is of that variant.
315    pub fn into_struct(self) -> StructVector {
316        if let Vector::Struct(v) = self {
317            return v;
318        }
319        vortex_panic!("Expected StructVector, got {self:?}");
320    }
321}
vortex_vector/vector.rs

vortex_vector/
vector.rs
