Skip to main content

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}