Skip to main content

quack_rs/testing/mock_vector/
reader.rs

1// SPDX-License-Identifier: MIT
2// Copyright 2026 Tom F. <https://github.com/tomtom215/>
3// My way of giving something small back to the open source community
4// and encouraging more Rust development!
5
6//! `MockVectorReader` — an in-memory mock input vector.
7
8use super::{MockDuckValue, MockVectorReader};
9use crate::interval::DuckInterval;
10
11impl MockVectorReader {
12    /// Creates a reader from an arbitrary sequence of `Option<MockDuckValue>`.
13    ///
14    /// `None` entries represent NULL rows.
15    #[must_use]
16    pub fn new(rows: impl IntoIterator<Item = Option<MockDuckValue>>) -> Self {
17        Self {
18            rows: rows.into_iter().collect(),
19        }
20    }
21
22    /// Creates a reader from a sequence of `Option<i64>` values.
23    ///
24    /// Convenience constructor for `BIGINT` columns.
25    #[must_use]
26    pub fn from_i64s(values: impl IntoIterator<Item = Option<i64>>) -> Self {
27        Self::new(values.into_iter().map(|v| v.map(MockDuckValue::I64)))
28    }
29
30    /// Creates a reader from a sequence of `Option<i32>` values.
31    ///
32    /// Convenience constructor for `INTEGER` columns.
33    #[must_use]
34    pub fn from_i32s(values: impl IntoIterator<Item = Option<i32>>) -> Self {
35        Self::new(values.into_iter().map(|v| v.map(MockDuckValue::I32)))
36    }
37
38    /// Creates a reader from a sequence of `Option<f64>` values.
39    ///
40    /// Convenience constructor for `DOUBLE` columns.
41    #[must_use]
42    pub fn from_f64s(values: impl IntoIterator<Item = Option<f64>>) -> Self {
43        Self::new(values.into_iter().map(|v| v.map(MockDuckValue::F64)))
44    }
45
46    /// Creates a reader from a sequence of `Option<bool>` values.
47    ///
48    /// Convenience constructor for `BOOLEAN` columns.
49    #[must_use]
50    pub fn from_bools(values: impl IntoIterator<Item = Option<bool>>) -> Self {
51        Self::new(values.into_iter().map(|v| v.map(MockDuckValue::Bool)))
52    }
53
54    /// Creates a reader from a sequence of `Option<i8>` values.
55    ///
56    /// Convenience constructor for `TINYINT` columns.
57    #[must_use]
58    pub fn from_i8s(values: impl IntoIterator<Item = Option<i8>>) -> Self {
59        Self::new(values.into_iter().map(|v| v.map(MockDuckValue::I8)))
60    }
61
62    /// Creates a reader from a sequence of `Option<i16>` values.
63    ///
64    /// Convenience constructor for `SMALLINT` columns.
65    #[must_use]
66    pub fn from_i16s(values: impl IntoIterator<Item = Option<i16>>) -> Self {
67        Self::new(values.into_iter().map(|v| v.map(MockDuckValue::I16)))
68    }
69
70    /// Creates a reader from a sequence of `Option<u8>` values.
71    ///
72    /// Convenience constructor for `UTINYINT` columns.
73    #[must_use]
74    pub fn from_u8s(values: impl IntoIterator<Item = Option<u8>>) -> Self {
75        Self::new(values.into_iter().map(|v| v.map(MockDuckValue::U8)))
76    }
77
78    /// Creates a reader from a sequence of `Option<u16>` values.
79    ///
80    /// Convenience constructor for `USMALLINT` columns.
81    #[must_use]
82    pub fn from_u16s(values: impl IntoIterator<Item = Option<u16>>) -> Self {
83        Self::new(values.into_iter().map(|v| v.map(MockDuckValue::U16)))
84    }
85
86    /// Creates a reader from a sequence of `Option<u32>` values.
87    ///
88    /// Convenience constructor for `UINTEGER` columns.
89    #[must_use]
90    pub fn from_u32s(values: impl IntoIterator<Item = Option<u32>>) -> Self {
91        Self::new(values.into_iter().map(|v| v.map(MockDuckValue::U32)))
92    }
93
94    /// Creates a reader from a sequence of `Option<u64>` values.
95    ///
96    /// Convenience constructor for `UBIGINT` columns.
97    #[must_use]
98    pub fn from_u64s(values: impl IntoIterator<Item = Option<u64>>) -> Self {
99        Self::new(values.into_iter().map(|v| v.map(MockDuckValue::U64)))
100    }
101
102    /// Creates a reader from a sequence of `Option<f32>` values.
103    ///
104    /// Convenience constructor for `FLOAT` columns.
105    #[must_use]
106    pub fn from_f32s(values: impl IntoIterator<Item = Option<f32>>) -> Self {
107        Self::new(values.into_iter().map(|v| v.map(MockDuckValue::F32)))
108    }
109
110    /// Creates a reader from a sequence of `Option<i128>` values.
111    ///
112    /// Convenience constructor for `HUGEINT` columns.
113    #[must_use]
114    pub fn from_i128s(values: impl IntoIterator<Item = Option<i128>>) -> Self {
115        Self::new(values.into_iter().map(|v| v.map(MockDuckValue::I128)))
116    }
117
118    /// Creates a reader from a sequence of `Option<DuckInterval>` values.
119    ///
120    /// Convenience constructor for `INTERVAL` columns.
121    #[must_use]
122    pub fn from_intervals(values: impl IntoIterator<Item = Option<DuckInterval>>) -> Self {
123        Self::new(values.into_iter().map(|v| v.map(MockDuckValue::Interval)))
124    }
125
126    /// Creates a reader from a sequence of `Option<&[u8]>` values.
127    ///
128    /// Convenience constructor for `BLOB` columns.
129    #[must_use]
130    pub fn from_blobs<'a>(values: impl IntoIterator<Item = Option<&'a [u8]>>) -> Self {
131        Self::new(
132            values
133                .into_iter()
134                .map(|v| v.map(|b| MockDuckValue::Blob(b.to_vec()))),
135        )
136    }
137
138    /// Creates a reader from a sequence of `Option<&str>` values.
139    ///
140    /// Convenience constructor for `VARCHAR` columns.
141    #[must_use]
142    pub fn from_strs<'a>(values: impl IntoIterator<Item = Option<&'a str>>) -> Self {
143        Self::new(
144            values
145                .into_iter()
146                .map(|v| v.map(|s| MockDuckValue::Varchar(s.to_owned()))),
147        )
148    }
149
150    /// Returns the number of rows in this reader.
151    #[must_use]
152    pub fn row_count(&self) -> usize {
153        self.rows.len()
154    }
155
156    /// Panics unless `idx` is a row of this reader, as a real vector requires.
157    ///
158    /// A real [`VectorReader`][crate::vector::VectorReader] has no bounds
159    /// check: reading past the chunk's row count is undefined behaviour. A mock
160    /// that quietly answered "NULL" there would let an off-by-one row loop
161    /// pass its unit tests and then read out of bounds in production, so the
162    /// mock refuses it — as [`MockVectorWriter`][super::MockVectorWriter] does
163    /// for writes past its capacity.
164    #[track_caller]
165    fn check_bounds(&self, idx: usize) {
166        assert!(
167            idx < self.rows.len(),
168            "row {idx} is out of bounds for a mock reader of {} row(s); a real \
169             DuckDB vector reader has no bounds check and reading past the chunk's \
170             row count is undefined behaviour",
171            self.rows.len()
172        );
173    }
174
175    /// Returns `true` if row `idx` is not NULL.
176    ///
177    /// # Panics
178    ///
179    /// Panics if `idx` is not less than [`row_count`][Self::row_count].
180    #[must_use]
181    #[track_caller]
182    pub fn is_valid(&self, idx: usize) -> bool {
183        self.check_bounds(idx);
184        self.rows[idx].is_some()
185    }
186
187    /// Returns the raw value at row `idx`, or `None` if it is NULL.
188    ///
189    /// # Panics
190    ///
191    /// Panics if `idx` is not less than [`row_count`][Self::row_count].
192    #[must_use]
193    #[track_caller]
194    pub fn get(&self, idx: usize) -> Option<&MockDuckValue> {
195        self.check_bounds(idx);
196        self.rows[idx].as_ref()
197    }
198
199    // ── Typed getters ───────────────────────────────────────────────────────
200
201    /// Returns the `BIGINT` value at row `idx`, or `None` if NULL or wrong type.
202    ///
203    /// # Panics
204    ///
205    /// Panics if `idx` is not less than [`row_count`][Self::row_count].
206    #[must_use]
207    #[track_caller]
208    pub fn try_get_i64(&self, idx: usize) -> Option<i64> {
209        match self.get(idx) {
210            Some(MockDuckValue::I64(v)) => Some(*v),
211            _ => None,
212        }
213    }
214
215    /// Returns the `INTEGER` value at row `idx`, or `None` if NULL or wrong type.
216    ///
217    /// # Panics
218    ///
219    /// Panics if `idx` is not less than [`row_count`][Self::row_count].
220    #[must_use]
221    #[track_caller]
222    pub fn try_get_i32(&self, idx: usize) -> Option<i32> {
223        match self.get(idx) {
224            Some(MockDuckValue::I32(v)) => Some(*v),
225            _ => None,
226        }
227    }
228
229    /// Returns the `DOUBLE` value at row `idx`, or `None` if NULL or wrong type.
230    ///
231    /// # Panics
232    ///
233    /// Panics if `idx` is not less than [`row_count`][Self::row_count].
234    #[must_use]
235    #[track_caller]
236    pub fn try_get_f64(&self, idx: usize) -> Option<f64> {
237        match self.get(idx) {
238            Some(MockDuckValue::F64(v)) => Some(*v),
239            _ => None,
240        }
241    }
242
243    /// Returns the `BOOLEAN` value at row `idx`, or `None` if NULL or wrong type.
244    ///
245    /// # Panics
246    ///
247    /// Panics if `idx` is not less than [`row_count`][Self::row_count].
248    #[must_use]
249    #[track_caller]
250    pub fn try_get_bool(&self, idx: usize) -> Option<bool> {
251        match self.get(idx) {
252            Some(MockDuckValue::Bool(v)) => Some(*v),
253            _ => None,
254        }
255    }
256
257    /// Returns the `VARCHAR` value at row `idx`, or `None` if NULL or wrong type.
258    ///
259    /// # Panics
260    ///
261    /// Panics if `idx` is not less than [`row_count`][Self::row_count].
262    #[must_use]
263    #[track_caller]
264    pub fn try_get_str(&self, idx: usize) -> Option<&str> {
265        match self.get(idx) {
266            Some(MockDuckValue::Varchar(s)) => Some(s.as_str()),
267            _ => None,
268        }
269    }
270
271    /// Returns the `INTERVAL` value at row `idx`, or `None` if NULL or wrong type.
272    ///
273    /// # Panics
274    ///
275    /// Panics if `idx` is not less than [`row_count`][Self::row_count].
276    #[must_use]
277    #[track_caller]
278    pub fn try_get_interval(&self, idx: usize) -> Option<DuckInterval> {
279        match self.get(idx) {
280            Some(MockDuckValue::Interval(v)) => Some(*v),
281            _ => None,
282        }
283    }
284
285    /// Returns the `TINYINT` value at row `idx`, or `None` if NULL or wrong type.
286    ///
287    /// # Panics
288    ///
289    /// Panics if `idx` is not less than [`row_count`][Self::row_count].
290    #[must_use]
291    #[track_caller]
292    pub fn try_get_i8(&self, idx: usize) -> Option<i8> {
293        match self.get(idx) {
294            Some(MockDuckValue::I8(v)) => Some(*v),
295            _ => None,
296        }
297    }
298
299    /// Returns the `SMALLINT` value at row `idx`, or `None` if NULL or wrong type.
300    ///
301    /// # Panics
302    ///
303    /// Panics if `idx` is not less than [`row_count`][Self::row_count].
304    #[must_use]
305    #[track_caller]
306    pub fn try_get_i16(&self, idx: usize) -> Option<i16> {
307        match self.get(idx) {
308            Some(MockDuckValue::I16(v)) => Some(*v),
309            _ => None,
310        }
311    }
312
313    /// Returns the `UTINYINT` value at row `idx`, or `None` if NULL or wrong type.
314    ///
315    /// # Panics
316    ///
317    /// Panics if `idx` is not less than [`row_count`][Self::row_count].
318    #[must_use]
319    #[track_caller]
320    pub fn try_get_u8(&self, idx: usize) -> Option<u8> {
321        match self.get(idx) {
322            Some(MockDuckValue::U8(v)) => Some(*v),
323            _ => None,
324        }
325    }
326
327    /// Returns the `USMALLINT` value at row `idx`, or `None` if NULL or wrong type.
328    ///
329    /// # Panics
330    ///
331    /// Panics if `idx` is not less than [`row_count`][Self::row_count].
332    #[must_use]
333    #[track_caller]
334    pub fn try_get_u16(&self, idx: usize) -> Option<u16> {
335        match self.get(idx) {
336            Some(MockDuckValue::U16(v)) => Some(*v),
337            _ => None,
338        }
339    }
340
341    /// Returns the `UINTEGER` value at row `idx`, or `None` if NULL or wrong type.
342    ///
343    /// # Panics
344    ///
345    /// Panics if `idx` is not less than [`row_count`][Self::row_count].
346    #[must_use]
347    #[track_caller]
348    pub fn try_get_u32(&self, idx: usize) -> Option<u32> {
349        match self.get(idx) {
350            Some(MockDuckValue::U32(v)) => Some(*v),
351            _ => None,
352        }
353    }
354
355    /// Returns the `UBIGINT` value at row `idx`, or `None` if NULL or wrong type.
356    ///
357    /// # Panics
358    ///
359    /// Panics if `idx` is not less than [`row_count`][Self::row_count].
360    #[must_use]
361    #[track_caller]
362    pub fn try_get_u64(&self, idx: usize) -> Option<u64> {
363        match self.get(idx) {
364            Some(MockDuckValue::U64(v)) => Some(*v),
365            _ => None,
366        }
367    }
368
369    /// Returns the `FLOAT` value at row `idx`, or `None` if NULL or wrong type.
370    ///
371    /// # Panics
372    ///
373    /// Panics if `idx` is not less than [`row_count`][Self::row_count].
374    #[must_use]
375    #[track_caller]
376    pub fn try_get_f32(&self, idx: usize) -> Option<f32> {
377        match self.get(idx) {
378            Some(MockDuckValue::F32(v)) => Some(*v),
379            _ => None,
380        }
381    }
382
383    /// Returns the `HUGEINT` value at row `idx`, or `None` if NULL or wrong type.
384    ///
385    /// # Panics
386    ///
387    /// Panics if `idx` is not less than [`row_count`][Self::row_count].
388    #[must_use]
389    #[track_caller]
390    pub fn try_get_i128(&self, idx: usize) -> Option<i128> {
391        match self.get(idx) {
392            Some(MockDuckValue::I128(v)) => Some(*v),
393            _ => None,
394        }
395    }
396
397    /// Returns the `BLOB` value at row `idx`, or `None` if NULL or wrong type.
398    ///
399    /// # Panics
400    ///
401    /// Panics if `idx` is not less than [`row_count`][Self::row_count].
402    #[must_use]
403    #[track_caller]
404    pub fn try_get_blob(&self, idx: usize) -> Option<&[u8]> {
405        match self.get(idx) {
406            Some(MockDuckValue::Blob(v)) => Some(v.as_slice()),
407            _ => None,
408        }
409    }
410
411    /// Returns the `UUID`'s textual 128 bits at row `idx`, or `None` if NULL or
412    /// wrong type.
413    ///
414    /// Undoes `DuckDB`'s top-bit flip exactly as
415    /// [`VectorReader::read_uuid`][crate::vector::VectorReader::read_uuid] does.
416    /// [`try_get_i128`][Self::try_get_i128] returns the raw storage.
417    ///
418    /// # Panics
419    ///
420    /// Panics if `idx` is not less than [`row_count`][Self::row_count].
421    #[must_use]
422    #[track_caller]
423    pub fn try_get_uuid(&self, idx: usize) -> Option<u128> {
424        self.try_get_i128(idx).map(crate::vector::uuid_from_storage)
425    }
426}