Skip to main content

uqa_sql/expr/
collation.rs

1//
2// Unified Query Algebra
3//
4// Copyright (c) 2023-2026 Cognica, Inc.
5//
6
7//! Deterministic built-in Unicode comparison owns decomposition and admitted scratch in SQL.
8
9mod combining;
10mod data;
11mod elements;
12mod mapping;
13mod stream;
14
15use crate::{
16    catalog::collations::{builtin_collation_order, BuiltinCollationOrder},
17    SQLError,
18};
19use elements::{
20    CollationElement, CE_BUFFER_SIZE, NO_CE_PRIMARY, NO_CE_SECONDARY, NO_CE_TERTIARY, TERTIARY_MASK,
21};
22use icu_collator::provider::{Baked, CollationDiacriticsV1};
23use icu_provider::{DataProvider, DataRequest};
24use std::cmp::Ordering;
25use stream::CollationElements;
26use uqa_core::{
27    compare_bytes_with_control,
28    memory::{ProductionControl, ProductionSmallVec},
29};
30
31/// Select the deterministic string-comparison provider. Callers preserve strict NULL handling before reaching this selection, as `PostgreSQL`'s `check_collation_set` does.
32pub(in crate::expr) fn string_comparison_order(
33    collation: u32,
34) -> Result<BuiltinCollationOrder, SQLError> {
35    if collation == 0 {
36        return Err(SQLError::Diagnostic {
37            sqlstate: "42P22".into(),
38            message: "could not determine which collation to use for string comparison".into(),
39            detail: None,
40            hint: Some("Use the COLLATE clause to set the collation explicitly.".into()),
41        });
42    }
43    builtin_collation_order(collation)
44        .ok_or_else(|| SQLError::Internal(format!("cache lookup failed for collation {collation}")))
45}
46
47/// Compare the deterministic `PostgreSQL` `unicode` built-in (root ICU, tertiary strength, normalization checking off). Byte-distinct strings retain distinct equality classes even when their Unicode weights match.
48pub fn compare_unicode_with_control(
49    left: &str,
50    right: &str,
51    control: &ProductionControl<'_>,
52) -> Result<Ordering, SQLError> {
53    let byte_order = compare_bytes_with_control(left.as_bytes(), right.as_bytes(), control)?;
54    if byte_order.is_eq() {
55        return Ok(byte_order);
56    }
57    let diacritics =
58        <Baked as DataProvider<CollationDiacriticsV1>>::load(&Baked, DataRequest::default())
59            .map_err(|error| {
60                SQLError::Internal(format!("built-in Unicode collation data: {error}"))
61            })?
62            .payload;
63    let root = Baked::SINGLETON_COLLATION_ROOT_V1;
64    let jamo = Baked::SINGLETON_COLLATION_JAMO_V1
65        .ce32s
66        .as_ule_slice()
67        .try_into()
68        .map_err(|_| SQLError::Internal("built-in Unicode Jamo width".into()))?;
69    let decompositions = icu_normalizer::provider::Baked::SINGLETON_NORMALIZER_NFD_DATA_V1;
70    let tables = icu_normalizer::provider::Baked::SINGLETON_NORMALIZER_NFD_TABLES_V1;
71    let mut left = CollationElements::new(
72        left.chars(),
73        *control,
74        root,
75        jamo,
76        &diacritics.get().secondaries,
77        decompositions,
78        tables,
79    );
80    let mut right = CollationElements::new(
81        right.chars(),
82        *control,
83        root,
84        jamo,
85        &diacritics.get().secondaries,
86        decompositions,
87        tables,
88    );
89    left.init()?;
90    right.init()?;
91    let mut left_ces = ProductionSmallVec::<[CollationElement; CE_BUFFER_SIZE]>::new(*control);
92    let mut right_ces = ProductionSmallVec::<[CollationElement; CE_BUFFER_SIZE]>::new(*control);
93    loop {
94        control.check()?;
95        let left_primary = loop {
96            let ce = left.next()?;
97            left_ces.push(ce)?;
98            if ce.primary() != 0 {
99                break ce.primary();
100            }
101        };
102        let right_primary = loop {
103            let ce = right.next()?;
104            right_ces.push(ce)?;
105            if ce.primary() != 0 {
106                break ce.primary();
107            }
108        };
109        let order = left_primary.cmp(&right_primary);
110        if !order.is_eq() {
111            return Ok(order);
112        }
113        if left_primary == NO_CE_PRIMARY {
114            break;
115        }
116    }
117    let order = compare_secondary_and_tertiary(&left_ces, &right_ces, control)?;
118    control.check()?;
119    Ok(order.then(byte_order))
120}
121
122fn compare_secondary_and_tertiary(
123    left_ces: &[CollationElement],
124    right_ces: &[CollationElement],
125    control: &ProductionControl<'_>,
126) -> Result<Ordering, SQLError> {
127    for (weight, sentinel) in [
128        (
129            CollationElement::secondary as fn(CollationElement) -> u16,
130            NO_CE_SECONDARY,
131        ),
132        (tertiary, NO_CE_TERTIARY),
133    ] {
134        let mut left = left_ces.iter();
135        let mut right = right_ces.iter();
136        loop {
137            control.check()?;
138            let l = loop {
139                control.check()?;
140                let value = weight(*left.next().unwrap_or_default());
141                if value != 0 {
142                    break value;
143                }
144            };
145            let r = loop {
146                control.check()?;
147                let value = weight(*right.next().unwrap_or_default());
148                if value != 0 {
149                    break value;
150                }
151            };
152            let order = l.cmp(&r);
153            if !order.is_eq() {
154                return Ok(order);
155            }
156            if l == sentinel {
157                break;
158            }
159        }
160    }
161    control.check()?;
162    Ok(Ordering::Equal)
163}
164
165fn tertiary(ce: CollationElement) -> u16 {
166    ce.non_primary().tertiary_case_quarternary(TERTIARY_MASK)
167}
168
169#[cfg(test)]
170mod tests;