gossamer - v10.0.0

gossamer/intl/duration_format

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

Types

Builder

opaque </>

The configuration for a DurationFormat.

pub opaque type Builder

ClockStyle

</>

Rendering style for hours, minutes, and seconds. Maps the JavaScript hours/minutes/seconds options.

pub type ClockStyle {
  ClockLong
  ClockShort
  ClockNarrow
  ClockNumeric
  ClockTwoDigit
}

Constructors 

  • ClockLong

    Full unit name ("2 hours").

  • ClockShort

    Shortened unit name ("2 hr").

  • ClockNarrow

    Narrowest unit form ("2h").

  • ClockNumeric

    Compact numeric form ("2" instead of "02").

  • ClockTwoDigit

    Zero-padded two-digit form ("02" instead of "2").

Display

</>

Whether to display a unit even when its value is zero. Maps the JavaScript per-unit display options (yearsDisplay, hoursDisplay, and so on).

pub type Display {
  Auto
  Always
}

Constructors 

  • Auto

    Show the unit only when its value is non-zero (the default for most units).

  • Always

    Always show the unit, even when its value is zero.

DurationFormat

</>

A configured duration formatter.

See Intl.DurationFormat on MDN.

pub type DurationFormat

DurationParts

</>

The set of fields a duration can carry, mapping the JavaScript Temporal.Duration-like input. Use zero plus record update for sparse values:

DurationParts(..duration_format.zero, hours: 2, minutes: 30)

All fields must share the same sign — mixing positive and negative values causes format to return Error(Nil).

pub type DurationParts {
  DurationParts(
    years: Int,
    months: Int,
    weeks: Int,
    days: Int,
    hours: Int,
    minutes: Int,
    seconds: Int,
    milliseconds: Int,
    microseconds: Int,
    nanoseconds: Int,
  )
}

Constructors 

  • DurationParts(
  years: Int,
  months: Int,
  weeks: Int,
  days: Int,
  hours: Int,
  minutes: Int,
  seconds: Int,
  milliseconds: Int,
  microseconds: Int,
  nanoseconds: Int,
)

FractionalDigits

</>

Number of fractional digits shown on the smallest rendered unit. Maps the JavaScript fractionalDigits option.

pub type FractionalDigits {
  FractionalDigits0
  FractionalDigits1
  FractionalDigits2
  FractionalDigits3
  FractionalDigits4
  FractionalDigits5
  FractionalDigits6
  FractionalDigits7
  FractionalDigits8
  FractionalDigits9
}

Constructors 

  • FractionalDigits0

    No fractional digits ("1:30:45").

  • FractionalDigits1

    One fractional digit ("1:30:45.5").

  • FractionalDigits2

    Two fractional digits ("1:30:45.50").

  • FractionalDigits3

    Three fractional digits — millisecond precision ("1:30:45.500").

  • FractionalDigits4

    Four fractional digits.

  • FractionalDigits5

    Five fractional digits.

  • FractionalDigits6

    Six fractional digits — microsecond precision.

  • FractionalDigits7

    Seven fractional digits.

  • FractionalDigits8

    Eight fractional digits.

  • FractionalDigits9

    Nine fractional digits — nanosecond precision.

Part

</>

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

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

Constructors

PartKind

</>

The kind of a Part.

pub type PartKind {
  Integer
  Decimal
  Fraction
  Group
  Literal
  Unit
}

Constructors 

  • Integer

    The numeric portion of a value (e.g., "2" from "2 hours").

  • Decimal

    The decimal separator ("." or "," per locale), emitted for fractional values.

  • Fraction

    The fractional portion, emitted for sub-second values.

  • Group

    A digit-group separator ("," or " " per locale), emitted for large values.

  • Literal

    A literal separator or spacing (e.g., ", " or " ").

  • Unit

    The unit-name portion of a value (e.g., "hours").

ResolvedOptions

</>

The options the runtime resolved for a DurationFormat, including the per-unit styles and display modes it derived from the overall Style. locale is the BCP 47 tag chosen from the requested priority list (e.g., "en-US"); fractional_digits is Some only when a fixed digit count was requested.

pub type ResolvedOptions {
  ResolvedOptions(
    locale: String,
    numbering_system: String,
    style: Style,
    years: intl.LabelStyle,
    months: intl.LabelStyle,
    weeks: intl.LabelStyle,
    days: intl.LabelStyle,
    hours: ClockStyle,
    minutes: ClockStyle,
    seconds: ClockStyle,
    milliseconds: SubSecondStyle,
    microseconds: SubSecondStyle,
    nanoseconds: SubSecondStyle,
    years_display: Display,
    months_display: Display,
    weeks_display: Display,
    days_display: Display,
    hours_display: Display,
    minutes_display: Display,
    seconds_display: Display,
    milliseconds_display: Display,
    microseconds_display: Display,
    nanoseconds_display: Display,
    fractional_digits: option.Option(FractionalDigits),
  )
}

Constructors

Style

</>

The overall rendering style. Maps the JavaScript style option.

pub type Style {
  StyleLong
  StyleShort
  StyleNarrow
  StyleDigital
}

Constructors 

  • StyleLong

    Full unit names: "2 hours, 30 minutes".

  • StyleShort

    Shortened unit names: "2 hr, 30 min".

  • StyleNarrow

    Narrowest forms: "2h 30m".

  • StyleDigital

    Digital-clock style: "2:30:45".

SubSecondStyle

</>

Rendering style for milliseconds, microseconds, and nanoseconds. Maps the JavaScript milliseconds/microseconds/nanoseconds options.

pub type SubSecondStyle {
  SubSecondLong
  SubSecondShort
  SubSecondNarrow
  SubSecondNumeric
}

Constructors 

  • SubSecondLong

    Full unit name ("500 milliseconds").

  • SubSecondShort

    Shortened unit name ("500 ms").

  • SubSecondNarrow

    Narrowest unit form ("500ms").

  • SubSecondNumeric

    Compact numeric form ("500").

Values

build

</> 
pub fn build(builder: Builder) -> Result(DurationFormat, Nil)

Constructs a DurationFormat from the configured builder. Returns Error(Nil) if any locale tag or numbering system tag is structurally invalid.

format

</> 
pub fn format(
  formatter: DurationFormat,
  parts: DurationParts,
) -> Result(String, Nil)

Formats parts as a locale-aware duration string. Returns Error(Nil) if the parts mix positive and negative values.

format_duration

</> 
pub fn format_duration(
  formatter: DurationFormat,
  value: duration.Duration,
) -> String

Formats a gleam/time/duration.Duration as a locale-aware string, decomposing it into hours through nanoseconds via from_duration. Calendar fields stay absent since Duration is elapsed time. Unlike format this cannot error on sign mixing — the decomposition always shares a single sign.

format_duration_to_parts

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

Formats a gleam/time/duration.Duration and returns its decomposition into Parts. Uses the same hours-through- nanoseconds decomposition as format_duration.

format_to_parts

</> 
pub fn format_to_parts(
  formatter: DurationFormat,
  parts: DurationParts,
) -> Result(List(Part), Nil)

Formats parts and returns its decomposition into segments — integer numerals, literal separators, and unit names. Returns Error(Nil) if the parts mix positive and negative values.

from_duration

</> 
pub fn from_duration(value: duration.Duration) -> DurationParts

Decomposes a gleam/time/duration.Duration into a DurationParts, filling in hours through nanoseconds. Calendar fields (years/months/weeks/days) stay zero since Duration represents elapsed time without calendar context. Negative durations decompose into uniformly-negative fields so the result can be passed straight to format.

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

The full configuration the runtime resolved from the builder, including the per-unit styles and display modes derived from the overall style.

supported_locales_of

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

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

with_days

</> 
pub fn with_days(
  builder: Builder,
  days: intl.LabelStyle,
) -> Builder

Sets the rendering style for days.

with_days_display

</> 
pub fn with_days_display(
  builder: Builder,
  days_display: Display,
) -> Builder

Sets whether zero days should be shown.

with_fractional_digits

</> 
pub fn with_fractional_digits(
  builder: Builder,
  fractional_digits: FractionalDigits,
) -> Builder

Sets the number of fractional digits shown on the smallest rendered unit. Most visible in StyleDigital style.

with_hours

</> 
pub fn with_hours(builder: Builder, hours: ClockStyle) -> Builder

Sets the rendering style for hours.

with_hours_display

</> 
pub fn with_hours_display(
  builder: Builder,
  hours_display: Display,
) -> Builder

Sets whether zero hours should be shown.

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_microseconds

</> 
pub fn with_microseconds(
  builder: Builder,
  microseconds: SubSecondStyle,
) -> Builder

Sets the rendering style for microseconds.

with_microseconds_display

</> 
pub fn with_microseconds_display(
  builder: Builder,
  microseconds_display: Display,
) -> Builder

Sets whether zero microseconds should be shown.

with_milliseconds

</> 
pub fn with_milliseconds(
  builder: Builder,
  milliseconds: SubSecondStyle,
) -> Builder

Sets the rendering style for milliseconds.

with_milliseconds_display

</> 
pub fn with_milliseconds_display(
  builder: Builder,
  milliseconds_display: Display,
) -> Builder

Sets whether zero milliseconds should be shown.

with_minutes

</> 
pub fn with_minutes(
  builder: Builder,
  minutes: ClockStyle,
) -> Builder

Sets the rendering style for minutes.

with_minutes_display

</> 
pub fn with_minutes_display(
  builder: Builder,
  minutes_display: Display,
) -> Builder

Sets whether zero minutes should be shown.

with_months

</> 
pub fn with_months(
  builder: Builder,
  months: intl.LabelStyle,
) -> Builder

Sets the rendering style for months.

with_months_display

</> 
pub fn with_months_display(
  builder: Builder,
  months_display: Display,
) -> Builder

Sets whether zero months should be shown.

with_nanoseconds

</> 
pub fn with_nanoseconds(
  builder: Builder,
  nanoseconds: SubSecondStyle,
) -> Builder

Sets the rendering style for nanoseconds.

with_nanoseconds_display

</> 
pub fn with_nanoseconds_display(
  builder: Builder,
  nanoseconds_display: Display,
) -> Builder

Sets whether zero nanoseconds should be shown.

with_numbering_system

</> 
pub fn with_numbering_system(
  builder: Builder,
  numbering_system: String,
) -> Builder

Sets the numbering system used for digits (e.g., "latn", "arab").

with_seconds

</> 
pub fn with_seconds(
  builder: Builder,
  seconds: ClockStyle,
) -> Builder

Sets the rendering style for seconds.

with_seconds_display

</> 
pub fn with_seconds_display(
  builder: Builder,
  seconds_display: Display,
) -> Builder

Sets whether zero seconds should be shown.

with_style

</> 
pub fn with_style(builder: Builder, style: Style) -> Builder

Sets the overall rendering style.

with_weeks

</> 
pub fn with_weeks(
  builder: Builder,
  weeks: intl.LabelStyle,
) -> Builder

Sets the rendering style for weeks.

with_weeks_display

</> 
pub fn with_weeks_display(
  builder: Builder,
  weeks_display: Display,
) -> Builder

Sets whether zero weeks should be shown.

with_years

</> 
pub fn with_years(
  builder: Builder,
  years: intl.LabelStyle,
) -> Builder

Sets the rendering style for years.

with_years_display

</> 
pub fn with_years_display(
  builder: Builder,
  years_display: Display,
) -> Builder

Sets whether zero years should be shown.

zero

</> 
pub const zero: DurationParts

A DurationParts where every field is zero.

✨ Search Document