collator

Locale-aware string comparison via the JavaScript Intl.Collator. Reusing a built Collator across many comparisons is significantly faster than building one per call.

Types

Builder

opaque </>

The configuration for a Collator.

pub opaque type Builder

Collator

</>

A configured comparator that orders strings using a locale- specific collation.

See Intl.Collator on MDN.

pub type Collator

The options the runtime resolved for a Collator, including the defaults it filled in. locale is the BCP 47 tag chosen from the requested priority list (e.g., "en-US"); collation is the resolved collation identifier ("default" when none was requested).

pub type ResolvedOptions {
  ResolvedOptions(
    locale: String,
    usage: Usage,
    sensitivity: Sensitivity,
    ignore_punctuation: Bool,
    collation: String,
    numeric: Bool,
    case_first: intl.CaseFirst,
  )
}

Constructors

ResolvedOptions(
  locale: String,
  usage: Usage,
  sensitivity: Sensitivity,
  ignore_punctuation: Bool,
  collation: String,
  numeric: Bool,
  case_first: intl.CaseFirst,
)

Sensitivity

</>

Which differences between strings produce a non-zero comparison result. Maps the JavaScript sensitivity option.

pub type Sensitivity {
  Base
  Accent
  Case
  Variant
}

Constructors

```
Base
```
Only base letters differ. a equals á; a differs from b.
```
Accent
```
Base letters and accents differ. a differs from á.
```
Case
```
Base letters and case differ. a differs from A.
```
Variant
```
Base letters, accents, and case all differ.

Usage

</>

Whether the comparator is tuned for sorting or for searching. Maps the JavaScript usage option.

pub type Usage {
  Sort
  Search
}

Constructors

```
Sort
```
Sort comparisons. Differences contribute to the result per the configured sensitivity.
```
Search
```
Substring or equality search. May ignore locale-specific differences for more lenient matching.

Values

build

</>

pub fn build(builder: Builder) -> Result(Collator, Nil)

Constructs a Collator from the configured builder. Returns Error(Nil) if any locale tag is structurally malformed.

compare

</>

pub fn compare(
  collator: Collator,
  a: String,
  b: String,
) -> order.Order

Compares two strings under the configured locale’s collation.

new

</>

pub fn new(locales: List(String)) -> Builder

Creates a Builder for the given locale priority list. The runtime picks the first locale it supports; pass an empty list to use the runtime’s default locale.

resolved_options

</>

pub fn resolved_options(collator: Collator) -> ResolvedOptions

The full configuration the runtime resolved from the builder, including the sensitivity and case ordering it derived from the usage and locale.

supported_locales_of

</>

pub fn supported_locales_of(
  locales: List(String),
) -> Result(List(String), Nil)

Filters locales to those the runtime supports for collation, preserving the input order. Returns Error(Nil) if any locale tag is structurally malformed.

with_case_first

</>

pub fn with_case_first(
  builder: Builder,
  case_first: intl.CaseFirst,
) -> Builder

Sets how case influences sort order. When unset, derived from the locale.

with_collation

</>

pub fn with_collation(
  builder: Builder,
  collation: String,
) -> Builder

Sets a specific collation variant (e.g., "pinyin" for Chinese, "phonebk" for German). When unset, the locale’s default collation is used. Values not supported by the locale are silently ignored.

with_ignore_punctuation

</>

pub fn with_ignore_punctuation(
  builder: Builder,
  ignore_punctuation: Bool,
) -> Builder

Sets whether punctuation is skipped during comparison.

with_locale_matcher

</>

pub fn with_locale_matcher(
  builder: Builder,
  locale_matcher: intl.LocaleMatcher,
) -> Builder

Sets the locale-matching algorithm used to pick a locale from the priority list.

with_numeric

</>

pub fn with_numeric(builder: Builder, numeric: Bool) -> Builder

Sets whether numeric substrings (e.g. "foo10" vs "foo2") are compared as numbers rather than character by character.

with_sensitivity

</>

pub fn with_sensitivity(
  builder: Builder,
  sensitivity: Sensitivity,
) -> Builder

Sets which differences between strings produce a non-zero comparison result. When unset, derived from the configured Usage and locale.

with_usage

</>

pub fn with_usage(builder: Builder, usage: Usage) -> Builder

Sets whether the comparator is tuned for sorting or searching.