Skip to main content

quack_rs/vector/
mod.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//! Safe helpers for reading from and writing to `DuckDB` data vectors.
7//!
8//! `DuckDB` represents columnar data as "vectors" — arrays of typed values
9//! with an associated validity bitmap for NULL tracking. This module provides
10//! safe wrappers that eliminate the raw pointer arithmetic and undocumented
11//! struct layouts that trip up extension authors.
12//!
13//! # Pitfalls solved by this module
14//!
15//! - **L4**: `ensure_validity_writable` — [`VectorWriter`] calls this automatically
16//!   before any NULL-setting operation.
17//! - **L5**: Boolean reading — [`VectorReader`] always reads bytes as `u8 != 0`,
18//!   never as `bool`, preventing undefined behaviour.
19//! - **P7**: `duckdb_string_t` format — [`string`] handles both the inline (≤12 bytes)
20//!   and pointer (>12 bytes) cases.
21//! - **Stale child pointers** — [`ListBuilder`] re-fetches the child writer after
22//!   every `reserve`, which reallocates the child vector. See
23//!   [`list_builder`][mod@list_builder].
24
25pub mod complex;
26pub mod list_builder;
27mod nested_null;
28#[cfg(feature = "duckdb-1-5")]
29pub mod ops;
30pub mod reader;
31pub mod string;
32pub mod struct_reader;
33pub mod struct_writer;
34pub mod uuid;
35pub mod validity;
36pub mod writer;
37
38pub use list_builder::{max_child_capacity, ListBuilder, MAX_LIST_CHILD_CAPACITY};
39#[cfg(feature = "duckdb-1-5")]
40pub use ops::OwnedVector;
41pub use reader::VectorReader;
42pub use string::{read_duck_blob, read_duck_string, DuckStringView};
43pub use struct_reader::StructReader;
44pub use struct_writer::StructWriter;
45pub use uuid::{uuid_from_storage, uuid_to_storage};
46pub use validity::ValidityBitmap;
47pub use writer::VectorWriter;
48
49/// Returns the default vector size used by `DuckDB` (typically 2048).
50#[cfg_attr(test, mutants::skip)]
51pub fn vector_size() -> u64 {
52    // SAFETY: this call takes no arguments and reads a compile-time constant.
53    unsafe { libduckdb_sys::duckdb_vector_size() as u64 }
54}
55
56/// Returns the logical type of a vector.
57///
58/// # Safety
59/// `vector` must be a valid `duckdb_vector`.
60pub unsafe fn vector_get_column_type(
61    vector: libduckdb_sys::duckdb_vector,
62) -> crate::types::LogicalType {
63    // SAFETY: `duckdb_vector_get_column_type` returns null for a null handle and
64    // otherwise reads `v->GetType()` (data_chunk-c.cpp); the `# Safety` contract
65    // makes `vector` a valid `duckdb_vector`.
66    let raw = unsafe { libduckdb_sys::duckdb_vector_get_column_type(vector) };
67    // SAFETY: `from_raw` needs a non-null handle that it alone will destroy. For
68    // a valid vector `raw` is `new LogicalType(v->GetType())`
69    // (data_chunk-c.cpp), a fresh allocation that duckdb.h says must be
70    // destroyed with `duckdb_destroy_logical_type`, which `LogicalType`'s `Drop`
71    // does; `raw` is not used again (and `from_raw` asserts it is non-null).
72    unsafe { crate::types::LogicalType::from_raw(raw) }
73}