Skip to main content

quack_rs/testing/mock_vector/
writer.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//! `MockVectorWriter` — an in-memory mock output vector.
7
8use super::{MockDuckValue, MockVectorWriter};
9use crate::interval::DuckInterval;
10
11impl MockVectorWriter {
12    /// Creates a writer with room for `capacity` rows, all valid and unwritten.
13    #[must_use]
14    pub fn new(capacity: usize) -> Self {
15        Self {
16            rows: vec![None; capacity],
17            valid: vec![true; capacity],
18        }
19    }
20
21    /// Panics unless `idx` is within the capacity, as a real vector requires.
22    #[track_caller]
23    fn check_bounds(&self, idx: usize) {
24        assert!(
25            idx < self.rows.len(),
26            "row {idx} is out of bounds for a mock vector of capacity {}; a real \
27             DuckDB vector has a fixed capacity and writing past it corrupts memory",
28            self.rows.len()
29        );
30    }
31
32    /// Marks row `idx` as NULL. A later `write_*` does not undo this; see
33    /// [`set_valid`][Self::set_valid].
34    ///
35    /// # Panics
36    ///
37    /// Panics if `idx` is not less than the capacity.
38    #[track_caller]
39    pub fn set_null(&mut self, idx: usize) {
40        self.check_bounds(idx);
41        self.valid[idx] = false;
42    }
43
44    /// Marks row `idx` as valid again, mirroring
45    /// [`VectorWriter::set_valid`][crate::vector::VectorWriter::set_valid].
46    ///
47    /// # Panics
48    ///
49    /// Panics if `idx` is not less than the capacity.
50    #[track_caller]
51    pub fn set_valid(&mut self, idx: usize) {
52        self.check_bounds(idx);
53        self.valid[idx] = true;
54    }
55
56    /// Returns `true` if row `idx` has been marked NULL.
57    ///
58    /// A row that was never written is **not** NULL — see the type-level docs.
59    ///
60    /// # Panics
61    ///
62    /// Panics if `idx` is not less than the capacity.
63    #[must_use]
64    #[track_caller]
65    pub fn is_null(&self, idx: usize) -> bool {
66        self.check_bounds(idx);
67        !self.valid[idx]
68    }
69
70    /// Returns `true` if a value has been written at row `idx`, whether or not
71    /// the row is also marked NULL.
72    ///
73    /// # Panics
74    ///
75    /// Panics if `idx` is not less than the capacity.
76    #[must_use]
77    #[track_caller]
78    pub fn is_written(&self, idx: usize) -> bool {
79        self.check_bounds(idx);
80        self.rows[idx].is_some()
81    }
82
83    /// Returns the capacity: the number of rows this mock holds.
84    #[must_use]
85    pub fn len(&self) -> usize {
86        self.rows.len()
87    }
88
89    /// Returns `true` if the capacity is zero.
90    #[must_use]
91    pub fn is_empty(&self) -> bool {
92        self.rows.is_empty()
93    }
94
95    /// Returns the value at row `idx` as `DuckDB` would read it.
96    ///
97    /// Returns `None` if the row is NULL, has never been written, or is out of
98    /// bounds. Use [`is_null`][Self::is_null] and
99    /// [`is_written`][Self::is_written] to tell those apart.
100    #[must_use]
101    pub fn get(&self, idx: usize) -> Option<&MockDuckValue> {
102        if self.valid.get(idx).copied() != Some(true) {
103            return None;
104        }
105        self.rows.get(idx).and_then(Option::as_ref)
106    }
107
108    // ── Numeric writes ──────────────────────────────────────────────────────
109
110    /// Writes a `TINYINT` value at row `idx`.
111    pub fn write_i8(&mut self, idx: usize, value: i8) {
112        self.check_bounds(idx);
113        self.rows[idx] = Some(MockDuckValue::I8(value));
114    }
115
116    /// Writes a `SMALLINT` value at row `idx`.
117    pub fn write_i16(&mut self, idx: usize, value: i16) {
118        self.check_bounds(idx);
119        self.rows[idx] = Some(MockDuckValue::I16(value));
120    }
121
122    /// Writes an `INTEGER` value at row `idx`.
123    pub fn write_i32(&mut self, idx: usize, value: i32) {
124        self.check_bounds(idx);
125        self.rows[idx] = Some(MockDuckValue::I32(value));
126    }
127
128    /// Writes a `BIGINT` value at row `idx`.
129    pub fn write_i64(&mut self, idx: usize, value: i64) {
130        self.check_bounds(idx);
131        self.rows[idx] = Some(MockDuckValue::I64(value));
132    }
133
134    /// Writes a `UTINYINT` value at row `idx`.
135    pub fn write_u8(&mut self, idx: usize, value: u8) {
136        self.check_bounds(idx);
137        self.rows[idx] = Some(MockDuckValue::U8(value));
138    }
139
140    /// Writes a `USMALLINT` value at row `idx`.
141    pub fn write_u16(&mut self, idx: usize, value: u16) {
142        self.check_bounds(idx);
143        self.rows[idx] = Some(MockDuckValue::U16(value));
144    }
145
146    /// Writes a `UINTEGER` value at row `idx`.
147    pub fn write_u32(&mut self, idx: usize, value: u32) {
148        self.check_bounds(idx);
149        self.rows[idx] = Some(MockDuckValue::U32(value));
150    }
151
152    /// Writes a `UBIGINT` value at row `idx`.
153    pub fn write_u64(&mut self, idx: usize, value: u64) {
154        self.check_bounds(idx);
155        self.rows[idx] = Some(MockDuckValue::U64(value));
156    }
157
158    /// Writes a `FLOAT` value at row `idx`.
159    pub fn write_f32(&mut self, idx: usize, value: f32) {
160        self.check_bounds(idx);
161        self.rows[idx] = Some(MockDuckValue::F32(value));
162    }
163
164    /// Writes a `DOUBLE` value at row `idx`.
165    pub fn write_f64(&mut self, idx: usize, value: f64) {
166        self.check_bounds(idx);
167        self.rows[idx] = Some(MockDuckValue::F64(value));
168    }
169
170    /// Writes a `BOOLEAN` value at row `idx`.
171    pub fn write_bool(&mut self, idx: usize, value: bool) {
172        self.check_bounds(idx);
173        self.rows[idx] = Some(MockDuckValue::Bool(value));
174    }
175
176    /// Writes a `HUGEINT` value at row `idx`.
177    pub fn write_i128(&mut self, idx: usize, value: i128) {
178        self.check_bounds(idx);
179        self.rows[idx] = Some(MockDuckValue::I128(value));
180    }
181
182    /// Writes a `VARCHAR` value at row `idx`.
183    ///
184    /// # Panics
185    ///
186    /// Panics if `idx` is out of bounds or `value` is longer than
187    /// [`MAX_STRING_LEN`][crate::vector::string::MAX_STRING_LEN].
188    #[track_caller]
189    pub fn write_varchar(&mut self, idx: usize, value: &str) {
190        self.check_bounds(idx);
191        if let Err(e) = crate::vector::string::check_string_len(value.len()) {
192            panic!("write_varchar: {e}");
193        }
194        self.rows[idx] = Some(MockDuckValue::Varchar(value.to_owned()));
195    }
196
197    /// Writes a `VARCHAR` value at row `idx`.
198    ///
199    /// Alias for [`write_varchar`][MockVectorWriter::write_varchar].
200    pub fn write_str(&mut self, idx: usize, value: &str) {
201        self.write_varchar(idx, value);
202    }
203
204    /// Writes an `INTERVAL` value at row `idx`.
205    pub fn write_interval(&mut self, idx: usize, value: DuckInterval) {
206        self.check_bounds(idx);
207        self.rows[idx] = Some(MockDuckValue::Interval(value));
208    }
209
210    /// Writes a `BLOB` value at row `idx`.
211    ///
212    /// # Panics
213    ///
214    /// Panics if `idx` is out of bounds or `value` is longer than
215    /// [`MAX_STRING_LEN`][crate::vector::string::MAX_STRING_LEN].
216    #[track_caller]
217    pub fn write_blob(&mut self, idx: usize, value: &[u8]) {
218        self.check_bounds(idx);
219        if let Err(e) = crate::vector::string::check_string_len(value.len()) {
220            panic!("write_blob: {e}");
221        }
222        self.rows[idx] = Some(MockDuckValue::Blob(value.to_vec()));
223    }
224
225    /// Writes a `DATE` value (days since epoch) at row `idx`.
226    ///
227    /// Semantic alias for [`write_i32`][Self::write_i32].
228    pub fn write_date(&mut self, idx: usize, days_since_epoch: i32) {
229        self.write_i32(idx, days_since_epoch);
230    }
231
232    /// Writes a `TIMESTAMP` value (microseconds since epoch) at row `idx`.
233    ///
234    /// Semantic alias for [`write_i64`][Self::write_i64].
235    pub fn write_timestamp(&mut self, idx: usize, micros_since_epoch: i64) {
236        self.write_i64(idx, micros_since_epoch);
237    }
238
239    /// Writes a `TIME` value (microseconds since midnight) at row `idx`.
240    ///
241    /// Semantic alias for [`write_i64`][Self::write_i64].
242    pub fn write_time(&mut self, idx: usize, micros_since_midnight: i64) {
243        self.write_i64(idx, micros_since_midnight);
244    }
245
246    /// Writes a `UUID`'s textual 128 bits at row `idx`.
247    ///
248    /// Applies `DuckDB`'s top-bit flip exactly as
249    /// [`VectorWriter::write_uuid`][crate::vector::VectorWriter::write_uuid]
250    /// does, so a callback tested against this mock behaves the same against a
251    /// real vector. [`write_i128`][Self::write_i128] writes the raw storage.
252    pub fn write_uuid(&mut self, idx: usize, bits: u128) {
253        self.write_i128(idx, crate::vector::uuid_to_storage(bits));
254    }
255
256    // ── Typed getters ───────────────────────────────────────────────────────
257
258    /// Returns the `BIGINT` value at row `idx`, or `None` if NULL or wrong type.
259    #[must_use]
260    pub fn try_get_i64(&self, idx: usize) -> Option<i64> {
261        match self.get(idx) {
262            Some(MockDuckValue::I64(v)) => Some(*v),
263            _ => None,
264        }
265    }
266
267    /// Returns the `INTEGER` value at row `idx`, or `None` if NULL or wrong type.
268    #[must_use]
269    pub fn try_get_i32(&self, idx: usize) -> Option<i32> {
270        match self.get(idx) {
271            Some(MockDuckValue::I32(v)) => Some(*v),
272            _ => None,
273        }
274    }
275
276    /// Returns the `DOUBLE` value at row `idx`, or `None` if NULL or wrong type.
277    #[must_use]
278    pub fn try_get_f64(&self, idx: usize) -> Option<f64> {
279        match self.get(idx) {
280            Some(MockDuckValue::F64(v)) => Some(*v),
281            _ => None,
282        }
283    }
284
285    /// Returns the `BOOLEAN` value at row `idx`, or `None` if NULL or wrong type.
286    #[must_use]
287    pub fn try_get_bool(&self, idx: usize) -> Option<bool> {
288        match self.get(idx) {
289            Some(MockDuckValue::Bool(v)) => Some(*v),
290            _ => None,
291        }
292    }
293
294    /// Returns the `VARCHAR` value at row `idx`, or `None` if NULL or wrong type.
295    #[must_use]
296    pub fn try_get_str(&self, idx: usize) -> Option<&str> {
297        match self.get(idx) {
298            Some(MockDuckValue::Varchar(s)) => Some(s.as_str()),
299            _ => None,
300        }
301    }
302
303    /// Returns the `INTERVAL` value at row `idx`, or `None` if NULL or wrong type.
304    #[must_use]
305    pub fn try_get_interval(&self, idx: usize) -> Option<DuckInterval> {
306        match self.get(idx) {
307            Some(MockDuckValue::Interval(v)) => Some(*v),
308            _ => None,
309        }
310    }
311
312    /// Returns the `TINYINT` value at row `idx`, or `None` if NULL or wrong type.
313    #[must_use]
314    pub fn try_get_i8(&self, idx: usize) -> Option<i8> {
315        match self.get(idx) {
316            Some(MockDuckValue::I8(v)) => Some(*v),
317            _ => None,
318        }
319    }
320
321    /// Returns the `SMALLINT` value at row `idx`, or `None` if NULL or wrong type.
322    #[must_use]
323    pub fn try_get_i16(&self, idx: usize) -> Option<i16> {
324        match self.get(idx) {
325            Some(MockDuckValue::I16(v)) => Some(*v),
326            _ => None,
327        }
328    }
329
330    /// Returns the `UTINYINT` value at row `idx`, or `None` if NULL or wrong type.
331    #[must_use]
332    pub fn try_get_u8(&self, idx: usize) -> Option<u8> {
333        match self.get(idx) {
334            Some(MockDuckValue::U8(v)) => Some(*v),
335            _ => None,
336        }
337    }
338
339    /// Returns the `USMALLINT` value at row `idx`, or `None` if NULL or wrong type.
340    #[must_use]
341    pub fn try_get_u16(&self, idx: usize) -> Option<u16> {
342        match self.get(idx) {
343            Some(MockDuckValue::U16(v)) => Some(*v),
344            _ => None,
345        }
346    }
347
348    /// Returns the `UINTEGER` value at row `idx`, or `None` if NULL or wrong type.
349    #[must_use]
350    pub fn try_get_u32(&self, idx: usize) -> Option<u32> {
351        match self.get(idx) {
352            Some(MockDuckValue::U32(v)) => Some(*v),
353            _ => None,
354        }
355    }
356
357    /// Returns the `UBIGINT` value at row `idx`, or `None` if NULL or wrong type.
358    #[must_use]
359    pub fn try_get_u64(&self, idx: usize) -> Option<u64> {
360        match self.get(idx) {
361            Some(MockDuckValue::U64(v)) => Some(*v),
362            _ => None,
363        }
364    }
365
366    /// Returns the `FLOAT` value at row `idx`, or `None` if NULL or wrong type.
367    #[must_use]
368    pub fn try_get_f32(&self, idx: usize) -> Option<f32> {
369        match self.get(idx) {
370            Some(MockDuckValue::F32(v)) => Some(*v),
371            _ => None,
372        }
373    }
374
375    /// Returns the `HUGEINT` value at row `idx`, or `None` if NULL or wrong type.
376    #[must_use]
377    pub fn try_get_i128(&self, idx: usize) -> Option<i128> {
378        match self.get(idx) {
379            Some(MockDuckValue::I128(v)) => Some(*v),
380            _ => None,
381        }
382    }
383
384    /// Returns the `BLOB` value at row `idx`, or `None` if NULL or wrong type.
385    #[must_use]
386    pub fn try_get_blob(&self, idx: usize) -> Option<&[u8]> {
387        match self.get(idx) {
388            Some(MockDuckValue::Blob(v)) => Some(v.as_slice()),
389            _ => None,
390        }
391    }
392
393    /// Returns the `UUID`'s textual 128 bits at row `idx`, or `None` if NULL or
394    /// wrong type.
395    ///
396    /// Undoes `DuckDB`'s top-bit flip exactly as
397    /// [`VectorReader::read_uuid`][crate::vector::VectorReader::read_uuid] does.
398    /// [`try_get_i128`][Self::try_get_i128] returns the raw storage.
399    #[must_use]
400    pub fn try_get_uuid(&self, idx: usize) -> Option<u128> {
401        self.try_get_i128(idx).map(crate::vector::uuid_from_storage)
402    }
403}