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

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

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

RangePart(
  kind: PartKind,
  value: String,
  source: intl.RangePartSource,
)

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

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),
)

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.