Struct CollatorBorrowed 

pub struct CollatorBorrowed<'a> { /* private fields */ }

Compares strings according to culturally-relevant ordering, borrowed version.

Implementations

impl CollatorBorrowed<'static>

pub fn try_new( prefs: CollatorPreferences, options: CollatorOptions, ) -> Result<CollatorBorrowed<'static>, DataError>

Creates a collator for the given locale and options from compiled data.

pub const fn static_to_owned(self) -> Collator

Cheaply converts a CollatorBorrowed<'static> into a Collator.

Note: Due to branching and indirection, using Collator might inhibit some compile-time optimizations that are possible with CollatorBorrowed.

impl CollatorBorrowed<'_>

pub fn resolved_options(&self) -> ResolvedCollatorOptions

The resolved options showing how the default options, the requested options, and the options from locale data were combined.

pub fn compare(&self, left: &str, right: &str) -> Ordering

Compare guaranteed well-formed UTF-8 slices.

pub fn compare_utf8(&self, left: &[u8], right: &[u8]) -> Ordering

Compare potentially ill-formed UTF-8 slices. Ill-formed input is compared as if errors had been replaced with REPLACEMENT CHARACTERs according to the WHATWG Encoding Standard.

pub fn compare_utf16(&self, left: &[u16], right: &[u16]) -> Ordering

Compare potentially ill-formed UTF-16 slices. Unpaired surrogates are compared as if each one was a REPLACEMENT CHARACTER.

pub fn write_sort_key_to<S>( &self, s: &str, sink: &mut S, ) -> Result<<S as CollationKeySink>::Output, <S as CollationKeySink>::Error>

where S: CollationKeySink + ?Sized, <S as CollationKeySink>::State: Default,

Given valid UTF-8, write the sort key bytes up to the collator’s strength.

The bytes are written to an implementor of [CollationKeySink], a no-std version of std::io::Write. This trait is currently unstable, but it is implemented by Vec<u8>, VecDeque<u8>, SmallVec<[u8; N]>, and &mut [u8] (returning an error if the slice is too small).

If two sort keys generated at the same strength are compared bytewise, the result is the same as a collation comparison of the original strings at that strength.

For identical strength, the UTF-8 NFD normalization is appended for breaking ties.

No terminating zero byte is written to the output, so the output is not a valid C string, but the caller may append a zero afterward if a C string is desired.

⚠️ Generating a sort key is expensive relative to comparison because to compare, the collator skips identical prefixes before doing more complex comparison. Only use sort keys if you expect to compare them many times so as to amortize the cost of generating them. Measurement of this performance trade-off would be a good idea.

⚠️ Sort keys, if stored durably, should be presumed to be invalidated by a CLDR update, a new version of Unicode, or an update to the ICU4X code. Applications using sort keys must be prepared to recompute them if required and should take the performance of such an operation into account when deciding to use sort keys.

⚠️ If you should store sort keys in a database that is or becomes so large that regenerating sort keys becomes impractical, you should not expect ICU4X to support your using an older, frozen copy of the sort key generation algorithm with a later version of the library.

Example

use icu_collator::{
    options::{CollatorOptions, Strength},
    Collator,
};
use icu_locale::locale;
let locale = locale!("utf").into();
let mut options = CollatorOptions::default();
options.strength = Some(Strength::Primary);
let collator = Collator::try_new(locale, options).unwrap();

let mut k1 = Vec::new();
let Ok(()) = collator.write_sort_key_to("hello", &mut k1);
let mut k2 = Vec::new();
let Ok(()) = collator.write_sort_key_to("Héłłö", &mut k2);
assert_eq!(k1, k2);

pub fn write_sort_key_utf8_to<S>( &self, s: &[u8], sink: &mut S, ) -> Result<<S as CollationKeySink>::Output, <S as CollationKeySink>::Error>

where S: CollationKeySink + ?Sized, <S as CollationKeySink>::State: Default,

Given potentially invalid UTF-8, write the sort key bytes up to the collator’s strength.

For further details, see Self::write_sort_key_to.

pub fn write_sort_key_utf16_to<S>( &self, s: &[u16], sink: &mut S, ) -> Result<<S as CollationKeySink>::Output, <S as CollationKeySink>::Error>

where S: CollationKeySink + ?Sized, <S as CollationKeySink>::State: Default,

Given potentially invalid UTF-16, write the sort key bytes up to the collator’s strength.

For further details, see Self::write_sort_key_to.

Trait Implementations

impl<'a> Debug for CollatorBorrowed<'a>

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

Formats the value using the given formatter.