quack_rs/vector/uuid.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//! Converting between a `UUID`'s textual bits and `DuckDB`'s vector storage.
7//!
8//! A `UUID` column is physically a `HUGEINT`, but the 128 bits in the vector are
9//! **not** the 128 bits you see in the text form. `DuckDB` flips the top bit so
10//! that comparing the signed integers orders UUIDs the same way comparing their
11//! strings does (`BaseUUID::FromUHugeint` in `src/common/types/uuid.cpp`
12//! subtracts `2^63` from the upper half; that is a top-bit flip).
13//!
14//! The consequence is easy to hit and silent when you do:
15//!
16//! ```text
17//! SELECT '11111111-2222-3333-4444-555555555555'::UUID
18//! vector storage : 0x91111111222233334444555555555555 <- read_i128
19//! textual bits : 0x11111111222233334444555555555555 <- Value::as_uuid, uuid crates
20//! ```
21//!
22//! [`VectorReader::read_uuid`][crate::vector::VectorReader::read_uuid] and
23//! [`VectorWriter::write_uuid`][crate::vector::VectorWriter::write_uuid] apply
24//! the flip for you and speak in **textual bits** (`u128`), which is what every
25//! Rust `Uuid` type holds. These functions are for the raw path — when you have
26//! reached for `read_i128` / `write_i128` on a `UUID` column yourself.
27
28/// The bit `DuckDB` flips to make signed `HUGEINT` ordering match `UUID` string
29/// ordering.
30const UUID_SIGN_BIT: u128 = 1 << 127;
31
32/// Converts `DuckDB`'s vector storage for a `UUID` into the UUID's textual
33/// 128 bits.
34///
35/// # Example
36///
37/// ```rust
38/// use quack_rs::vector::uuid::{uuid_from_storage, uuid_to_storage};
39///
40/// let textual = 0x1111_1111_2222_3333_4444_5555_5555_5555_u128;
41/// assert_eq!(uuid_from_storage(uuid_to_storage(textual)), textual);
42/// ```
43#[inline]
44#[must_use]
45#[allow(
46 clippy::cast_sign_loss,
47 reason = "reinterpreting the bit pattern is the entire operation"
48)]
49pub const fn uuid_from_storage(storage: i128) -> u128 {
50 (storage as u128) ^ UUID_SIGN_BIT
51}
52
53/// Converts a UUID's textual 128 bits into `DuckDB`'s vector storage.
54///
55/// # Example
56///
57/// ```rust
58/// use quack_rs::vector::uuid::uuid_to_storage;
59///
60/// // The nil UUID sits at the very bottom of DuckDB's signed ordering.
61/// assert_eq!(uuid_to_storage(0), i128::MIN);
62/// ```
63#[inline]
64#[must_use]
65#[allow(
66 clippy::cast_possible_wrap,
67 reason = "reinterpreting the bit pattern is the entire operation"
68)]
69pub const fn uuid_to_storage(bits: u128) -> i128 {
70 (bits ^ UUID_SIGN_BIT) as i128
71}
72
73#[cfg(test)]
74mod tests {
75 use super::{uuid_from_storage, uuid_to_storage};
76
77 #[test]
78 fn conversions_are_inverses() {
79 for bits in [
80 0,
81 u128::MAX,
82 1,
83 UUID_SIGN_BIT_TEST,
84 0x1111_1111_2222_3333_4444_5555_5555_5555,
85 ] {
86 assert_eq!(
87 uuid_from_storage(uuid_to_storage(bits)),
88 bits,
89 "{bits:#034x}"
90 );
91 }
92 for storage in [i128::MIN, i128::MAX, 0, -1] {
93 assert_eq!(uuid_to_storage(uuid_from_storage(storage)), storage);
94 }
95 }
96
97 const UUID_SIGN_BIT_TEST: u128 = 1 << 127;
98
99 #[test]
100 fn ordering_matches_duckdbs_intent() {
101 // The flip exists so that signed HUGEINT ordering matches UUID string
102 // ordering: the nil UUID must be the smallest storage value.
103 assert_eq!(uuid_to_storage(0), i128::MIN);
104 assert_eq!(uuid_to_storage(u128::MAX), i128::MAX);
105 assert!(uuid_to_storage(1) > uuid_to_storage(0));
106 }
107}