Enum icu::collator::Strength

#[non_exhaustive]
#[repr(u8)]
pub enum Strength {
    Primary = 0,
    Secondary = 1,
    Tertiary = 2,
    Quaternary = 3,
    Identical = 7,
}

The collation strength that indicates how many levels to compare.

If an earlier level isn’t equal, the earlier level is decisive. If the result is equal on a level, but the strength is higher, the comparison proceeds to the next level.

Note: The bit layout of CollatorOptions requires Strength to fit in 3 bits.

Variants (Non-exhaustive)

Non-exhaustive enums could have additional variants added in future. Therefore, when matching against variants of non-exhaustive enums, an extra wildcard arm must be added to account for any future variants.

Primary = 0

Compare only on the level of base letters. This level corresponds to the ECMA-402 sensitivity “base” with CaseLevel::Off (the default for CaseLevel) and to ECMA-402 sensitivity “case” with CaseLevel::On.

use icu::collator::*;

let mut options = CollatorOptions::default();
options.strength = Some(Strength::Primary);
let collator = Collator::try_new(Default::default(), options).unwrap();
assert_eq!(collator.compare("E", "é"), core::cmp::Ordering::Equal);

Secondary = 1

Compare also on the secondary level, which corresponds to diacritics in scripts that use them. This level corresponds to the ECMA-402 sensitivity “accent”.

use icu::collator::*;

let mut options = CollatorOptions::default();
options.strength = Some(Strength::Secondary);
let collator = Collator::try_new(Default::default(), options).unwrap();
assert_eq!(collator.compare("E", "e"), core::cmp::Ordering::Equal);
assert_eq!(collator.compare("e", "é"), core::cmp::Ordering::Less);
assert_eq!(collator.compare("あ", "ア"), core::cmp::Ordering::Equal);
assert_eq!(collator.compare("ァ", "ア"), core::cmp::Ordering::Equal);
assert_eq!(collator.compare("ア", "ｱ"), core::cmp::Ordering::Equal);

Tertiary = 2

Compare also on the tertiary level. By default, if the separate case level is disabled, this corresponds to case for bicameral scripts. This level distinguishes Hiragana and Katakana. This also captures other minor differences, such as half-width vs. full-width when the Japanese tailoring isn’t in use.

This is the default comparison level and appropriate for most scripts. This level corresponds to the ECMA-402 sensitivity “variant”.

use icu::collator::*;
use icu::locale::locale;

let mut options = CollatorOptions::default();
options.strength = Some(Strength::Tertiary);
let collator =
  Collator::try_new(Default::default(),
                    options).unwrap();
assert_eq!(collator.compare("E", "e"),
           core::cmp::Ordering::Greater);
assert_eq!(collator.compare("e", "é"),
           core::cmp::Ordering::Less);
assert_eq!(collator.compare("あ", "ア"),
           core::cmp::Ordering::Less);
assert_eq!(collator.compare("ァ", "ア"),
           core::cmp::Ordering::Less);
assert_eq!(collator.compare("ア", "ｱ"),
           core::cmp::Ordering::Less);
assert_eq!(collator.compare("e", "ｅ"), // Full-width e
           core::cmp::Ordering::Less);

let ja_collator =
  Collator::try_new(locale!("ja").into(), options).unwrap();
assert_eq!(ja_collator.compare("E", "e"),
           core::cmp::Ordering::Greater);
assert_eq!(ja_collator.compare("e", "é"),
           core::cmp::Ordering::Less);
assert_eq!(ja_collator.compare("あ", "ア"),
           core::cmp::Ordering::Equal); // Unlike root!
assert_eq!(ja_collator.compare("ァ", "ア"),
           core::cmp::Ordering::Less);
assert_eq!(ja_collator.compare("ア", "ｱ"),
           core::cmp::Ordering::Equal); // Unlike root!
assert_eq!(ja_collator.compare("e", "ｅ"), // Full-width e
           core::cmp::Ordering::Equal); // Unlike root!

Quaternary = 3

Compare also on the quaternary level. For Japanese, Higana and Katakana are distinguished at the quaternary level. Also, if AlternateHandling::Shifted is used, the collation elements whose level gets shifted are shifted to this level.

use icu::collator::*;
use icu::locale::locale;

let mut options = CollatorOptions::default();
options.strength = Some(Strength::Quaternary);

let ja_collator =
  Collator::try_new(locale!("ja").into(), options).unwrap();
assert_eq!(ja_collator.compare("あ", "ア"),
           core::cmp::Ordering::Less);
assert_eq!(ja_collator.compare("ア", "ｱ"),
           core::cmp::Ordering::Equal);
assert_eq!(ja_collator.compare("e", "ｅ"), // Full-width e
           core::cmp::Ordering::Equal);

// Even this level doesn't distinguish everything,
// e.g. Hebrew cantillation marks are still ignored.
let collator =
  Collator::try_new(Default::default(),
                    options).unwrap();
assert_eq!(collator.compare("דחי", "דחי֭"),
           core::cmp::Ordering::Equal);

TODO: Thai example.

Identical = 7

Compare the NFD form by code point order as the quinary level. This level makes the comparison slower and should not be used in the general case. However, it can be used to distinguish full-width and half-width forms when the Japanese tailoring is in use and to distinguish e.g. Hebrew cantillation markse. Use this level if you need JIS X 4061-1996 compliance for Japanese on the level of distinguishing full-width and half-width forms.

use icu::collator::*;
use icu::locale::locale;

let mut options = CollatorOptions::default();
options.strength = Some(Strength::Identical);

let ja_collator =
  Collator::try_new(locale!("ja").into(), options).unwrap();
assert_eq!(ja_collator.compare("ア", "ｱ"),
           core::cmp::Ordering::Less);
assert_eq!(ja_collator.compare("e", "ｅ"), // Full-width e
           core::cmp::Ordering::Less);

let collator =
  Collator::try_new(Default::default(),
                    options).unwrap();
assert_eq!(collator.compare("דחי", "דחי֭"),
           core::cmp::Ordering::Less);

Trait Implementations

impl Clone for Strength

fn clone(&self) -> Strength

Returns a copy of the value.

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

Performs copy-assignment from source.

impl Debug for Strength

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

Formats the value using the given formatter.

impl Ord for Strength

fn cmp(&self, other: &Strength) -> Ordering

This method returns an Ordering between self and other.

fn max(self, other: Self) -> Self

where Self: Sized,

Compares and returns the maximum of two values.

fn min(self, other: Self) -> Self

where Self: Sized,

Compares and returns the minimum of two values.

fn clamp(self, min: Self, max: Self) -> Self

where Self: Sized + PartialOrd,

Restrict a value to a certain interval.

impl PartialEq for Strength

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

Tests for self and other values to be equal, and is used by ==.

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

Tests for !=. The default implementation is almost always sufficient, and should not be overridden without very good reason.

impl PartialOrd for Strength

fn partial_cmp(&self, other: &Strength) -> Option<Ordering>

This method returns an ordering between self and other values if one exists.

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

Tests less than (for self and other) and is used by the < operator.

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

Tests less than or equal to (for self and other) and is used by the <= operator.

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

Tests greater than (for self and other) and is used by the > operator.

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

Tests greater than or equal to (for self and other) and is used by the >= operator.

impl Copy for Strength

impl Eq for Strength

impl StructuralPartialEq for Strength