Skip to main content

Collation

Struct Collation 

Source
pub struct Collation { /* private fields */ }
Expand description

A collation that this crate can compare with, or an explicit refusal.

Construct one of these, then call Collation::compare. Construction fails closed: anything not modelled exactly yields Error.

Serialization round-trips the description (Backend); deserialization re-runs the same validated construction, so a tampered or stale payload cannot produce an unchecked Collation.

Implementations§

Source§

impl Collation

Source

pub const fn binary() -> Self

Bytewise comparison. Always available.

Source

pub const fn postgres_c() -> Self

PostgreSQL C/POSIX, bytewise.

Source

pub fn postgres_icu( locale: impl Into<String>, deterministic: bool, source_version: VersionId, ) -> Result<Self>

Construct a PostgreSQL ICU collation, validating the version at runtime.

Returns Error::VersionMismatch if source_version does not match the ICU data the linked backend would use, and Error::Unsupported for custom rules or non-ICU providers.

Source

pub fn postgres(spec: PostgresCollation) -> Result<Self>

Construct a collation from a fully resolved PostgreSQL description.

Refuses configurations this crate cannot reproduce exactly: libc providers other than C/POSIX, custom ICU rules, and non-UTF-8 sources.

Source

pub fn mysql_0900_ai_ci() -> Self

Available on crate feature mysql-uca only.

Construct the modelled MySQL utf8mb4_0900_ai_ci collation.

Only available with the mysql-uca feature (enabled by default). Use Collation::mysql when the feature set is not known at compile time; it returns Error::FeatureDisabled instead.

Source

pub fn mysql_unicode_ci() -> Self

Available on crate feature mysql-uca only.

Construct the modelled MySQL utf8mb4_unicode_ci collation.

Only available with the mysql-uca feature (enabled by default). Use Collation::mysql when the feature set is not known at compile time; it returns Error::FeatureDisabled instead.

Source

pub fn mysql(spec: MysqlCollation) -> Result<Self>

Construct a collation from a fully resolved MySQL description.

Source

pub fn oracle(spec: OracleCollation) -> Result<Self>

Construct a collation from a fully resolved Oracle description.

Only NLS_SORT=BINARY on AL32UTF8 VARCHAR2 (bytewise) and the UCA0700_DUCET / UCA1210_DUCET collations are reproducible. Every other Oracle collation — monolingual, _M, BINARY_CI/BINARY_AI, *_ROOT, *_ORADUCET, tailored UCA, non-AL32UTF8, blank-padded — is refused with Error::Unsupported.

Source

pub fn from_mysql_name_unspecified_version(name: &str) -> Result<Self>

Resolve a MySQL collation by name without a version, refusing any name whose semantics depend on the server version.

This is intentionally conservative. Prefer Collation::mysql with an explicit MysqlCollation resolved by the caller.

Source

pub const fn backend(&self) -> &Backend

The backend this collation uses.

Source

pub fn compare(&self, a: &str, b: &str) -> Result<Ordering>

Compare two UTF-8 strings exactly as the source database would.

This is the primary operation. Sort keys are intentionally not part of the stable API: the contract is a three-way comparison, and a collation that also defines a bytewise tie-break (PostgreSQL deterministic collations) cannot be reproduced by a single ICU sort key, which encodes only the primary ICU comparison.

Returns Error if the underlying backend fails at runtime. The binary backend never fails; the ICU backend can, and a failed comparison is never silently reported as equality.

Source

pub fn equal(&self, a: &str, b: &str) -> Result<bool>

Whether a and b are equal under this collation.

Returns Error for the same reasons as Collation::compare.

Source

pub fn from_backend(backend: Backend) -> Result<Self>

Build a collation from a resolved Backend description, re-running the same validation as the public constructors.

This is the single construction path used by deserialization, so an arbitrary or stale description cannot bypass the support boundary.

Trait Implementations§

Source§

impl Clone for Collation

Source§

fn clone(&self) -> Self

Returns a duplicate of the value. Read more
1.0.0 (const: unstable) · Source§

fn clone_from(&mut self, source: &Self)

Performs copy-assignment from source. Read more
Source§

impl Debug for Collation

Source§

fn fmt(&self, f: &mut Formatter<'_>) -> Result

Formats the value using the given formatter. Read more
Source§

impl<'de> Deserialize<'de> for Collation

Available on crate feature serde only.
Source§

fn deserialize<__D>(__deserializer: __D) -> Result<Self, __D::Error>
where __D: Deserializer<'de>,

Deserialize this value from the given Serde deserializer. Read more
Source§

impl Eq for Collation

Source§

impl From<Collation> for Backend

Available on crate feature serde only.
Source§

fn from(collation: Collation) -> Self

Converts to this type from the input type.
Source§

impl Hash for Collation

Source§

fn hash<__H: Hasher>(&self, state: &mut __H)

Feeds this value into the given Hasher. Read more
1.3.0 · Source§

fn hash_slice<H>(data: &[Self], state: &mut H)
where H: Hasher, Self: Sized,

Feeds a slice of this type into the given Hasher. Read more
Source§

impl PartialEq for Collation

Source§

fn eq(&self, other: &Self) -> bool

Equality operator ==. Read more
1.0.0 (const: unstable) · Source§

fn ne(&self, other: &Rhs) -> bool

Inequality operator !=. Read more
Source§

impl Serialize for Collation

Available on crate feature serde only.
Source§

fn serialize<__S>(&self, __serializer: __S) -> Result<__S::Ok, __S::Error>
where __S: Serializer,

Serialize this value into the given Serde serializer. Read more
Source§

impl StructuralPartialEq for Collation

Source§

impl TryFrom<Backend> for Collation

Available on crate feature serde only.
Source§

type Error = Error

The type returned in the event of a conversion error.
Source§

fn try_from(backend: Backend) -> Result<Self>

Performs the conversion.

Auto Trait Implementations§

Blanket Implementations§

Source§

impl<T> Any for T
where T: 'static + ?Sized,

Source§

fn type_id(&self) -> TypeId

Gets the TypeId of self. Read more
Source§

impl<T> Borrow<T> for T
where T: ?Sized,

Source§

fn borrow(&self) -> &T

Immutably borrows from an owned value. Read more
Source§

impl<T> BorrowMut<T> for T
where T: ?Sized,

Source§

fn borrow_mut(&mut self) -> &mut T

Mutably borrows from an owned value. Read more
Source§

impl<T> CloneToUninit for T
where T: Clone,

Source§

unsafe fn clone_to_uninit(&self, dest: *mut u8)

🔬This is a nightly-only experimental API. (clone_to_uninit)
Performs copy-assignment from self to dest. Read more
Source§

impl<T> DeserializeOwned for T
where T: for<'de> Deserialize<'de>,

Source§

impl<T> From<T> for T

Source§

fn from(t: T) -> T

Returns the argument unchanged.

Source§

impl<T, U> Into<U> for T
where U: From<T>,

Source§

fn into(self) -> U

Calls U::from(self).

That is, this conversion is whatever the implementation of From<T> for U chooses to do.

Source§

impl<T> ToOwned for T
where T: Clone,

Source§

type Owned = T

The resulting type after obtaining ownership.
Source§

fn to_owned(&self) -> T

Creates owned data from borrowed data, usually by cloning. Read more
Source§

fn clone_into(&self, target: &mut T)

Uses borrowed data to replace owned data, usually by cloning. Read more
Source§

impl<T, U> TryFrom<U> for T
where U: Into<T>,

Source§

type Error = !

The type returned in the event of a conversion error.
Source§

fn try_from(value: U) -> Result<T, !>

Performs the conversion.
Source§

impl<T, U> TryInto<U> for T
where U: TryFrom<T>,

Source§

type Error = <U as TryFrom<T>>::Error

The type returned in the event of a conversion error.
Source§

fn try_into(self) -> Result<U, <U as TryFrom<T>>::Error>

Performs the conversion.