Struct CollatorBorrowed 

pub struct CollatorBorrowed<'a> {
    special_primaries: &'a CollationSpecialPrimariesValidated<'a>,
    root: &'a CollationData<'a>,
    tailoring: &'a CollationData<'a>,
    jamo: &'a CollationJamo<'a>,
    diacritics: &'a CollationDiacritics<'a>,
    options: CollatorOptionsBitField,
    reordering: Option<&'a CollationReordering<'a>>,
    decompositions: &'a DecompositionData<'a>,
    tables: &'a DecompositionTables<'a>,
    lithuanian_dot_above: bool,
}

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

Fields

special_primaries: &'a CollationSpecialPrimariesValidated<'a>

root: &'a CollationData<'a>

tailoring: &'a CollationData<'a>

jamo: &'a CollationJamo<'a>

diacritics: &'a CollationDiacritics<'a>

options: CollatorOptionsBitField

reordering: Option<&'a CollationReordering<'a>>

decompositions: &'a DecompositionData<'a>

tables: &'a DecompositionTables<'a>

lithuanian_dot_above: bool

Implementations

impl CollatorBorrowed<'static>

pub fn try_new( prefs: CollatorPreferences, options: CollatorOptions, ) -> Result<Self, 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<'data> CollatorBorrowed<'data>

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.

fn norm_trie(&self) -> &'data FastCodePointTrie<'data, u32>

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 compare_latin1(&self, left: &[u8], right: &[u8]) -> Ordering

Compare Latin1 slices.

✨ Enabled with the latin1 Cargo feature.

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

Compare Latin1 slice with potentially ill-formed UTF-16 slice.

If you need to compare a potentially ill-formed UTF-16 slice with a Latin1 slice, swap the arguments and call reverse() on the return value.

✨ Enabled with the latin1 Cargo feature.

fn numeric_primary(&self) -> Option<u8>

fn variable_top(&self) -> u32

fn compare_impl<L, R, H, T>( &'data self, left_chars: L, right_chars: R, head_chars: H, variable_top: u32, ) -> Ordering

where L: Iterator<Item = (char, u32)> + WithTrie<'data, T, u32> + 'data, R: Iterator<Item = (char, u32)> + WithTrie<'data, T, u32> + 'data, H: DoubleEndedIterator<Item = (char, u32)> + 'data, T: AbstractCodePointTrie<'data, u32> + 'data,

The implementation of the comparison operation.

head_chars is an iterator backward over the identical prefix and left_chars and right_chars are iterators forward over the parts after the identical prefix.

fn sort_key_levels(&self) -> u8

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

where S: CollationKeySink + ?Sized, S::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::Output, S::Error>

where S: CollationKeySink + ?Sized, S::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::Output, S::Error>

where S: CollationKeySink + ?Sized, S::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.

fn write_sort_key_impl<I, T, S>( &'data self, iter: I, sink: &mut S, ) -> Result<S::Output, S::Error>

where I: Iterator<Item = (char, u32)> + WithTrie<'data, T, u32> + Clone + 'data, T: AbstractCodePointTrie<'data, u32> + 'data, S: CollationKeySink + ?Sized, S::State: Default,

fn write_sort_key_up_to_quaternary<I, S, T>( &'data self, iter: I, sink: &mut S, state: &mut S::State, ) -> Result<(), S::Error>

where I: Iterator<Item = (char, u32)> + WithTrie<'data, T, u32> + Clone + 'data, T: AbstractCodePointTrie<'data, u32> + 'data, S: CollationKeySink + ?Sized,

Write the sort key bytes up to the collator’s strength.

Optionally write the case level. Separate levels with the LEVEL_SEPARATOR_BYTE, but do not write a terminating zero as with a C string.

Trait Implementations

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

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

Formats the value using the given formatter.