Expand description
§db-collation
Offline, exact string comparison under an explicitly identified database collation and version.
This crate exists for one purpose: reproduce the exact ordering semantics
of a source database’s collation locally, without talking to that database.
It is a pure function of a Collation description and the input bytes. It
opens no sockets, holds no drivers, and never issues a query.
§Guarantees and non-guarantees
- Exact or refused. For a supported configuration,
Collation::comparematches the source database’s comparison operator exactly (validated by the differential harness inharness/). For anything not explicitly modelled, construction returnsError::Unsupportedand the caller should fall back to comparing on the source database. A supported configuration can still reject an individual input that exceeds a documented source limit (e.g. Oracle’s 2000-byte UCA sort key); that isError::InputLimit, and the caller falls back for that input only. - No approximation. Selecting the same locale name is not sufficient:
ICU data versions change ordering (e.g.
あvsU+11DB0reversed between ICU 76 and 78), andMySQLcollations differ by UCA version, tailoring and padding. This crate therefore gates on version, not on names alone. - Deterministic tie-break.
PostgreSQLdeterministic collations break ICU equality ties with a bytewise comparison (shorter string first). That is reproduced here; nondeterministic collations intentionally do not.
§Supported configurations
See Collation and the crate README for the current matrix.
§Examples
use db_collation::{Collation, Result};
use std::cmp::Ordering;
fn main() -> Result<()> {
// Bytewise comparison is always available.
assert_eq!(Collation::binary().compare("a", "b")?, Ordering::Less);
// Unsupported configurations fail closed, so the caller can fall back.
assert!(Collation::from_mysql_name_unspecified_version("utf8mb4_general_ci").is_err());
Ok(())
}With the mysql-uca feature (enabled by default):
use db_collation::{Collation, Result};
use std::cmp::Ordering;
fn main() -> Result<()> {
let c = Collation::mysql_0900_ai_ci();
assert_eq!(c.compare("a", "A")?, Ordering::Equal);
Ok(())
}Structs§
- Collation
- A collation that this crate can compare with, or an explicit refusal.
- Mysql
Collation - A resolved
MySQLcollation description. - Oracle
Collation - A resolved
Oraclecollation description. - Postgres
Collation - A resolved
PostgreSQLcollation description. - Version
Id - A provider-specific collation data version token.
Enums§
- Backend
- Which backend a
Collationuses. - Error
- Errors produced when building or using a collation.
- Mysql
UcaVersion MySQLUCA weight-table version.- Oracle
Provider Oraclecollation provider.- Oracle
UcaVersion OracleUCA version for aUCA*_DUCETcollation.- Pad
- Trailing-space comparison semantics.
- Postgres
Provider PostgreSQLcollation provider.
Functions§
- collation_
version postgres-icu - The collation data version this build would use for
locale, formatted exactly asPostgreSQLreports it inpg_collation_actual_version(oid). - icu_
library_ version postgres-icu - The local ICU’s own library version (e.g.
76.1), for diagnostics.