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}