list_format

Locale-aware list formatting via the JavaScript Intl.ListFormat. Reusing a built ListFormat across many calls is significantly faster than building one per call.

Types

Builder

opaque </>

The configuration for a ListFormat.

pub opaque type Builder

Kind

</>

The kind of join the formatter produces. Maps the JavaScript type option.

pub type Kind {
  Conjunction
  Disjunction
  Unit
}

Constructors

```
Conjunction
```
“And”-style joining: "apple, banana, and cherry" (the default).
```
Disjunction
```
“Or”-style joining: "apple, banana, or cherry".
```
Unit
```
Unit-style joining for compound measurements: "5 hours, 10 minutes".

ListFormat

</>

A configured list formatter that joins a list of strings using a locale-specific conjunction or separator.

See Intl.ListFormat on MDN.

pub type ListFormat

Part

</>

A single segment of a formatted list, returned by format_to_parts.

pub type Part {
  Part(kind: PartKind, value: String)
}

Constructors

```
Part(kind: PartKind, value: String)
```

PartKind

</>

The kind of a Part — either a literal join word / separator or one of the input elements.

pub type PartKind {
  Literal
  Element
}

Constructors

```
Literal
```
A literal join word or separator (", ", "and ", etc.).
```
Element
```
One of the input list elements, passed through unchanged.

ResolvedOptions

</>

The options the runtime resolved for a ListFormat, including the defaults it filled in. locale is the BCP 47 tag chosen from the requested priority list (e.g., "en-US").

pub type ResolvedOptions {
  ResolvedOptions(
    locale: String,
    kind: Kind,
    style: intl.LabelStyle,
  )
}

Constructors

ResolvedOptions(
  locale: String,
  kind: Kind,
  style: intl.LabelStyle,
)

Values

build

</>

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

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

format

</>

pub fn format(
  formatter: ListFormat,
  list: List(String),
) -> String

Formats list as a locale-aware joined string. An empty list produces ""; a single-element list returns that element unchanged.

format_to_parts

</>

pub fn format_to_parts(
  formatter: ListFormat,
  list: List(String),
) -> List(Part)

Formats list and returns its decomposition into segments — alternating Literal join words / separators and Element entries.

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(formatter: ListFormat) -> ResolvedOptions

The locale, kind, and style the runtime resolved from the builder’s configuration.

supported_locales_of

</>

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

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

with_kind

</>

pub fn with_kind(builder: Builder, kind: Kind) -> Builder

Sets the kind of join the formatter produces.

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_style

</>

pub fn with_style(
  builder: Builder,
  style: intl.LabelStyle,
) -> Builder

Sets the verbosity of the joining words and separators.