gossamer - v10.0.0

gossamer/intl/date_time_format

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

Formatting accepts a gleam/time/timestamp.Timestamp; the *_to_parts variants return a typed decomposition and the *_range variants format a start-to-end pair.

Types

Builder

opaque </>

The configuration for a DateTimeFormat.

pub opaque type Builder

DateTimeFormat

</>

A configured formatter that renders a Timestamp as a locale-aware date/time string.

See Intl.DateTimeFormat on MDN.

pub type DateTimeFormat

FractionalSecondDigits

</>

The number of digits in the fractional-seconds component. Maps the JavaScript fractionalSecondDigits option’s 1 | 2 | 3 value set.

pub type FractionalSecondDigits {
  FractionalSeconds1
  FractionalSeconds2
  FractionalSeconds3
}

Constructors 

  • FractionalSeconds1

    Tenths-of-a-second precision ("3" for 0.3s).

  • FractionalSeconds2

    Hundredths-of-a-second precision ("30" for 0.30s).

  • FractionalSeconds3

    Milliseconds precision ("300" for 0.300s).

Month

</>

The format of the month component. Combines the numeric and width-style presentations — months accept either.

pub type Month {
  MonthNumeric
  MonthTwoDigit
  MonthLong
  MonthShort
  MonthNarrow
}

Constructors 

  • MonthNumeric

    Compact numeric form ("3" instead of "03").

  • MonthTwoDigit

    Zero-padded two-digit form ("03" instead of "3").

  • MonthLong

    Full name ("March").

  • MonthShort

    Shortened form ("Mar").

  • MonthNarrow

    The shortest form ("M").

NumericWidth

</>

The presentation of a numeric date/time component. Maps the JavaScript "numeric" | "2-digit" value set, shared by the year, day, hour, minute, and second options.

pub type NumericWidth {
  Numeric
  TwoDigit
}

Constructors 

  • Numeric

    Compact numeric form ("3" instead of "03").

  • TwoDigit

    Zero-padded two-digit form ("03" instead of "3").

Part

</>

A single segment of a formatted date/time, returned by format_to_parts.

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

Constructors

PartKind

</>

The kind of a Part or RangePart. Mirrors the JavaScript Intl.DateTimeFormatPart.type field.

pub type PartKind {
  Literal
  Era
  Year
  RelatedYear
  YearName
  Month
  Day
  Weekday
  Hour
  Minute
  Second
  FractionalSecond
  DayPeriod
  TimeZoneName
}

Constructors 

  • Literal

    A literal segment (separator characters, connecting words).

  • Era

    The era component ("AD", "Anno Domini").

  • Year

    The year component ("2026", "26").

  • RelatedYear

    The Gregorian year that contains the formatted date, emitted alongside YearName for non-Gregorian calendars. On Bun on macOS, year-only Chinese-calendar formats omit this segment where every other runtime/OS pairing emits it before YearName; option sets that include a month or day emit it everywhere.

  • YearName

    The locale-specific year name (e.g., "丙午" for Chinese sexagenary years).

  • Month

    The month component ("March", "03").

  • Day

    The day-of-month component ("15", "05").

  • Weekday

    The day-of-week component ("Friday", "Fri").

  • Hour

    The hour component ("3", "15").

  • Minute

    The minute component ("30").

  • Second

    The second component ("45").

  • FractionalSecond

    The fractional-seconds component ("123").

  • DayPeriod

    The day-period component ("AM", "in the morning").

  • TimeZoneName

    The time-zone label ("PST", "GMT-08:00").

RangePart

</>

A single segment of a formatted date/time range, returned by format_range_to_parts. source is an intl.RangePartSource identifying which side of the range produced the segment.

pub type RangePart {
  RangePart(
    kind: PartKind,
    value: String,
    source: intl.RangePartSource,
  )
}

Constructors

ResolvedOptions

</>

The options the runtime resolved for a DateTimeFormat, including the defaults it filled in. locale is the BCP 47 tag chosen from the requested priority list (e.g., "en-US"). The component fields (weekday through day_period) are Some only when that component is shown; a formatter built with date_style/time_style resolves those two instead and leaves the components None.

pub type ResolvedOptions {
  ResolvedOptions(
    locale: String,
    calendar: String,
    numbering_system: String,
    time_zone: String,
    hour_cycle: option.Option(intl.HourCycle),
    hour12: option.Option(Bool),
    weekday: option.Option(intl.LabelStyle),
    era: option.Option(intl.LabelStyle),
    year: option.Option(NumericWidth),
    month: option.Option(Month),
    day: option.Option(NumericWidth),
    hour: option.Option(NumericWidth),
    minute: option.Option(NumericWidth),
    second: option.Option(NumericWidth),
    fractional_second_digits: option.Option(
      FractionalSecondDigits,
    ),
    time_zone_name: option.Option(TimeZoneName),
    day_period: option.Option(intl.LabelStyle),
    date_style: option.Option(Style),
    time_style: option.Option(Style),
  )
}

Constructors

Style

</>

A verbosity preset for date or time formatting. Used by with_date_style and with_time_style.

pub type Style {
  StyleFull
  StyleLong
  StyleMedium
  StyleShort
}

Constructors 

  • StyleFull

    Most verbose ("Friday, May 15, 2026").

  • StyleLong

    Verbose ("May 15, 2026").

  • StyleMedium

    Standard ("May 15, 2026" for date; "3:30:00 PM" for time).

  • StyleShort

    Compact ("5/15/26" for date; "3:30 PM" for time).

TimeZoneName

</>

The presentation of the time-zone label. Maps the JavaScript timeZoneName option.

pub type TimeZoneName {
  TimeZoneShort
  TimeZoneLong
  TimeZoneShortOffset
  TimeZoneLongOffset
  TimeZoneShortGeneric
  TimeZoneLongGeneric
}

Constructors 

  • TimeZoneShort

    Short locale-specific name ("PST").

  • TimeZoneLong

    Long locale-specific name ("Pacific Standard Time").

  • TimeZoneShortOffset

    Short localized GMT-offset ("GMT-8").

  • TimeZoneLongOffset

    Long localized GMT-offset ("GMT-08:00").

  • TimeZoneShortGeneric

    Short generic non-location name ("PT").

  • TimeZoneLongGeneric

    Long generic non-location name ("Pacific Time").

Values

build

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

Constructs a DateTimeFormat from the configured builder. Returns Error(Nil) if any locale tag, calendar, numbering-system, or time-zone identifier is malformed, or if with_date_style or with_time_style was combined with any component-level setter.

format

</> 
pub fn format(
  formatter: DateTimeFormat,
  timestamp: timestamp.Timestamp,
) -> Result(String, Nil)

Formats timestamp as a locale-aware date/time string. Returns an error when the timestamp is outside the range JavaScript dates support (about plus or minus 273,790 years).

format_range

</> 
pub fn format_range(
  formatter: DateTimeFormat,
  from start: timestamp.Timestamp,
  to end: timestamp.Timestamp,
) -> Result(String, Nil)

Formats start-end as a locale-aware date/time range. Passing end earlier than start is well-defined and produces output — the resulting string may not be meaningful but does not error. Returns an error when either timestamp is outside the range JavaScript dates support (about plus or minus 273,790 years). On Bun the spaces around the en dash are regular spaces where Node and Deno use thin (U+2009) spaces; compare output across runtimes by substring rather than strict equality.

format_range_to_parts

</> 
pub fn format_range_to_parts(
  formatter: DateTimeFormat,
  from start: timestamp.Timestamp,
  to end: timestamp.Timestamp,
) -> Result(List(RangePart), Nil)

Formats start-end and returns its decomposition into segments tagged by which side of the range produced each one. Returns an error when either timestamp is outside the range JavaScript dates support (about plus or minus 273,790 years).

format_to_parts

</> 
pub fn format_to_parts(
  formatter: DateTimeFormat,
  timestamp: timestamp.Timestamp,
) -> Result(List(Part), Nil)

Formats timestamp and returns its decomposition into segments. Returns an error when the timestamp is outside the range JavaScript dates support (about plus or minus 273,790 years).

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

The full configuration the runtime resolved from the builder, including the calendar, time zone, and component widths it derived.

supported_locales_of

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

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

with_calendar

</> 
pub fn with_calendar(
  builder: Builder,
  calendar: String,
) -> Builder

Sets the calendar identifier (e.g., "gregory", "chinese", "hebrew").

with_date_style

</> 
pub fn with_date_style(
  builder: Builder,
  date_style: Style,
) -> Builder

Sets a date verbosity preset. Cannot be combined with the component-level setters (with_year, with_month, etc.); doing so causes build to return Error(Nil).

with_day

</> 
pub fn with_day(builder: Builder, day: NumericWidth) -> Builder

Sets the format of the day-of-month component.

with_day_period

</> 
pub fn with_day_period(
  builder: Builder,
  day_period: intl.LabelStyle,
) -> Builder

Sets the format of the day-period component (e.g., "AM" / "in the morning").

with_era

</> 
pub fn with_era(
  builder: Builder,
  era: intl.LabelStyle,
) -> Builder

Sets the format of the era component.

with_fractional_second_digits

</> 
pub fn with_fractional_second_digits(
  builder: Builder,
  fractional_second_digits: FractionalSecondDigits,
) -> Builder

Sets the number of digits in the fractional-seconds component.

with_hour

</> 
pub fn with_hour(builder: Builder, hour: NumericWidth) -> Builder

Sets the format of the hour component.

with_hour12

</> 
pub fn with_hour12(builder: Builder, hour12: Bool) -> Builder

Sets whether time is rendered with a 12-hour clock (when True) or a 24-hour clock (when False). The runtime picks a specific intl.HourCycle compatible with the locale. Takes precedence over with_hour_cycle when both are set; use with_hour_cycle alone to pick a specific cycle.

with_hour_cycle

</> 
pub fn with_hour_cycle(
  builder: Builder,
  hour_cycle: intl.HourCycle,
) -> Builder

Sets the clock format directly. Ignored when with_hour12 is also set.

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_minute

</> 
pub fn with_minute(
  builder: Builder,
  minute: NumericWidth,
) -> Builder

Sets the format of the minute component.

with_month

</> 
pub fn with_month(builder: Builder, month: Month) -> Builder

Sets the format of the month component.

with_numbering_system

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

Sets the numbering-system identifier (e.g., "latn", "arab", "hans").

with_second

</> 
pub fn with_second(
  builder: Builder,
  second: NumericWidth,
) -> Builder

Sets the format of the second component.

with_time_style

</> 
pub fn with_time_style(
  builder: Builder,
  time_style: Style,
) -> Builder

Sets a time verbosity preset. Cannot be combined with the component-level setters (with_hour, with_minute, etc.); doing so causes build to return Error(Nil).

with_time_zone

</> 
pub fn with_time_zone(
  builder: Builder,
  time_zone: String,
) -> Builder

Sets the time-zone identifier (e.g., "UTC", "America/Los_Angeles").

with_time_zone_name

</> 
pub fn with_time_zone_name(
  builder: Builder,
  time_zone_name: TimeZoneName,
) -> Builder

Sets the format of the time-zone label.

with_weekday

</> 
pub fn with_weekday(
  builder: Builder,
  weekday: intl.LabelStyle,
) -> Builder

Sets the format of the day-of-week component.

with_year

</> 
pub fn with_year(builder: Builder, year: NumericWidth) -> Builder

Sets the format of the year component.

✨ Search Document