relative_time_format

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

Types

Builder

opaque </>

The configuration for a RelativeTimeFormat.

pub opaque type Builder

Numeric

</>

Whether the formatter renders numeric values verbatim or substitutes locale-specific wording. Maps the JavaScript numeric option.

pub type Numeric {
  Always
  Auto
}

Constructors

```
Always
```
Always render the numeric value ("in 1 day", the default).
```
Auto
```
Substitute locale-specific wording for special values ("tomorrow" instead of "in 1 day").

A single segment of a formatted relative-time string, returned by the format_*_to_parts family. The unit field is Some for segments that quantify a time unit (the integer portion of "in 1 day") and None for literal connective text.

pub type Part {
  Part(kind: PartKind, value: String, unit: option.Option(Unit))
}

Constructors

Part(kind: PartKind, value: String, unit: option.Option(Unit))

PartKind

</>

The kind of a Part. Mirrors the relevant subset of JavaScript Intl.RelativeTimeFormatPart.type.

pub type PartKind {
  Literal
  Integer
  Decimal
  Fraction
  Group
  MinusSign
  PlusSign
  Infinity
  Nan
}

Constructors

```
Literal
```
A literal connective text ("in ", " ago").
```
Integer
```
An integer digit run.
```
Decimal
```
The decimal separator ("." or "," per locale).
```
Fraction
```
The fractional portion of a number.
```
Group
```
A digit-group separator ("," or " " per locale).
```
MinusSign
```
A minus sign for negative durations.
```
PlusSign
```
A plus sign.
```
Infinity
```
The literal infinity symbol ("∞").
```
Nan
```
The literal NaN representation.

RelativeTimeFormat

</>

A configured formatter that renders relative time spans ("in 2 hours", "yesterday", etc.) in a locale-specific way.

See Intl.RelativeTimeFormat on MDN.

pub type RelativeTimeFormat

ResolvedOptions

</>

The options the runtime resolved for a RelativeTimeFormat, 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,
    style: intl.LabelStyle,
    numeric: Numeric,
    numbering_system: String,
  )
}

Constructors

ResolvedOptions(
  locale: String,
  style: intl.LabelStyle,
  numeric: Numeric,
  numbering_system: String,
)

Unit

</>

A time unit accepted by the format operations. Maps the JavaScript unit argument string.

pub type Unit {
  Year
  Quarter
  Month
  Week
  Day
  Hour
  Minute
  Second
}

Constructors

```
Year
```
```
Quarter
```
```
Month
```
```
Week
```
```
Day
```
```
Hour
```
```
Minute
```
```
Second
```

Values

build

</>

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

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

format_duration

</>

pub fn format_duration(
  formatter: RelativeTimeFormat,
  value: duration.Duration,
) -> String

Formats a gleam/time/duration.Duration as relative time, decomposing into the largest applicable unit (duration.hours(-2) → "2 hours ago"). Sub-second durations clamp to zero seconds because Intl.RelativeTimeFormat doesn’t accept sub-second units; the rendered phrasing then depends on the formatter’s Numeric setting.

format_duration_to_parts

</>

pub fn format_duration_to_parts(
  formatter: RelativeTimeFormat,
  value: duration.Duration,
) -> List(Part)

Formats a gleam/time/duration.Duration and returns its decomposition into Parts. Uses the same unit decomposition as format_duration.

format_float

</>

pub fn format_float(
  formatter: RelativeTimeFormat,
  value: Float,
  in unit: Unit,
) -> String

Formats a Float value as a relative time in the given unit (format_float(rtf, -1.0, in: Day) → "1 day ago").

format_float_to_parts

</>

pub fn format_float_to_parts(
  formatter: RelativeTimeFormat,
  value: Float,
  in unit: Unit,
) -> List(Part)

Formats a Float value and returns its decomposition into segments.

format_int

</>

pub fn format_int(
  formatter: RelativeTimeFormat,
  value: Int,
  in unit: Unit,
) -> String

Formats an Int value as a relative time in the given unit.

format_int_to_parts

</>

pub fn format_int_to_parts(
  formatter: RelativeTimeFormat,
  value: Int,
  in unit: Unit,
) -> List(Part)

Formats an Int value as a list of Parts.

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: RelativeTimeFormat,
) -> ResolvedOptions

The locale, style, numeric mode, and numbering system 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 relative-time formatting, preserving the input order. Returns Error(Nil) if any locale tag is structurally malformed.

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: Numeric,
) -> Builder

Sets whether the formatter renders numeric values verbatim or substitutes locale-specific wording for special values.

with_style

</>

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

Sets the verbosity of the unit labels.