Docs / API / Datetimeformat

DateTimeFormat

Bindings to JavaScript's Intl.DateTimeFormat.

t

RESCRIPT
type t

dateStyle

RESCRIPT
type dateStyle = [#full | #long | #medium | #short]

timeStyle

RESCRIPT
type timeStyle = [#full | #long | #medium | #short]

dayPeriod

RESCRIPT
type dayPeriod = [#long | #narrow | #short]

weekday

RESCRIPT
type weekday = [#long | #narrow | #short]

era

RESCRIPT
type era = [#long | #narrow | #short]

year

RESCRIPT
type year = [#"2-digit" | #numeric]

month

RESCRIPT
type month = [ | #"2-digit" | #long | #narrow | #numeric | #short ]

day

RESCRIPT
type day = [#"2-digit" | #numeric]

hour

RESCRIPT
type hour = [#"2-digit" | #numeric]

minute

RESCRIPT
type minute = [#"2-digit" | #numeric]

second

RESCRIPT
type second = [#"2-digit" | #numeric]

timeZoneName

RESCRIPT
type timeZoneName = [ | #long | #longGeneric | #longOffset | #short | #shortGeneric | #shortOffset ]

Firefox also supports IANA time zone names here Node v19+ supports "shortOffset", "shortGeneric", "longOffset", and "longGeneric".

hourCycle

RESCRIPT
type hourCycle = [#h11 | #h12 | #h23 | #h24]

formatMatcher

RESCRIPT
type formatMatcher = [#basic | #"best fit"]

fractionalSecondDigits

RESCRIPT
type fractionalSecondDigits = [#0 | #1 | #2 | #3]

options

RESCRIPT
type options = { dateStyle?: dateStyle, timeStyle?: timeStyle, calendar?: Intl_Common.calendar, dayPeriod?: dayPeriod, numberingSystem?: Intl_Common.numberingSystem, localeMatcher?: Intl_Common.localeMatcher, timeZone?: string, hour12?: bool, hourCycle?: hourCycle, formatMatcher?: formatMatcher, weekday?: weekday, era?: era, year?: year, month?: month, day?: day, hour?: hour, minute?: minute, second?: second, fractionalSecondDigits?: fractionalSecondDigits, timeZoneName?: timeZoneName, }

resolvedOptions

RESCRIPT
type resolvedOptions = { dateStyle?: dateStyle, timeStyle?: timeStyle, weekday?: weekday, era?: era, year?: year, month?: month, day?: day, hour?: hour, minute?: minute, second?: second, fractionalSecondDigits?: fractionalSecondDigits, timeZoneName?: timeZoneName, calendar: Intl_Common.calendar, hour12: bool, hourCycle: hourCycle, locale: string, numberingSystem: Intl_Common.numberingSystem, timeZone: string, }

supportedLocalesOptions

RESCRIPT
type supportedLocalesOptions = { localeMatcher: Intl_Common.localeMatcher, }

dateTimeComponent

RESCRIPT
type dateTimeComponent = [ | #day | #dayPeriod | #era | #fractionalSecond | #hour | #literal | #minute | #month | #relatedYear | #second | #timeZone | #weekday | #year | #yearName ]

dateTimePart

RESCRIPT
type dateTimePart = { \"type": dateTimeComponent, value: string, }

dateTimeRangeSource

RESCRIPT
type dateTimeRangeSource = [ | #endRange | #shared | #startRange ]

dateTimeRangePart

RESCRIPT
type dateTimeRangePart = { \"type": dateTimeComponent, value: string, source: dateTimeRangeSource, }

make

RESCRIPT
let make: (~locales: array<string>=?, ~options: options=?) => t

Creates a new Intl.DateTimeFormat instance for formatting date values.

See Intl.DateTimeFormat on MDN.

Examples

RESCRIPT
let formatter = Intl.DateTimeFormat.make(~locales=["en-US"], ~options={timeStyle: #short})
let sampleDate = Js.Date.makeWithYMD(~year=2024, ~month=0, ~date=1)
formatter->Intl.DateTimeFormat.format(sampleDate)->String.length > 0

supportedLocalesOf

RESCRIPT
let supportedLocalesOf: ( array<string>, ~options: supportedLocalesOptions=?, ) => array<string>

supportedLocalesOf(locales, ~options) filters locales to those supported by the runtime for date/time formatting.

See Intl.DateTimeFormat.supportedLocalesOf on MDN.

Examples

RESCRIPT
Intl.DateTimeFormat.supportedLocalesOf(["en-US", "klingon"]) == ["en-US"]

resolvedOptions

RESCRIPT
let resolvedOptions: t => resolvedOptions

resolvedOptions(formatter) returns the actual locale and formatting options in use.

See Intl.DateTimeFormat.prototype.resolvedOptions on MDN.

Examples

RESCRIPT
let formatter = Intl.DateTimeFormat.make(~locales=["en-US"])
Intl.DateTimeFormat.resolvedOptions(formatter).locale == "en-US"

format

RESCRIPT
let format: (t, Date.t) => string

format(formatter, date) returns the formatted string for date.

Examples

RESCRIPT
let formatter = Intl.DateTimeFormat.make(~locales=["en"])
let date = Js.Date.makeWithYMD(~year=2024, ~month=0, ~date=1)
formatter->Intl.DateTimeFormat.format(date)->String.length > 0

formatToParts

RESCRIPT
let formatToParts: (t, Date.t) => array<dateTimePart>

formatToParts(formatter, date) breaks the formatted output into an array of parts.

See Intl.DateTimeFormat.prototype.formatToParts on MDN.

Examples

RESCRIPT
let formatter = Intl.DateTimeFormat.make(~locales=["en"])
let date = Js.Date.makeWithYMD(~year=2024, ~month=0, ~date=1)
formatter->Intl.DateTimeFormat.formatToParts(date)->Array.length > 0

formatRange

RESCRIPT
let formatRange: (t, ~startDate: Date.t, ~endDate: Date.t) => string

formatRange(formatter, ~startDate, ~endDate) formats the range between startDate and endDate.

See Intl.DateTimeFormat.prototype.formatRange on MDN.

Examples

RESCRIPT
let formatter = Intl.DateTimeFormat.make(~locales=["en-US"], ~options={dateStyle: #short})
let startDate = Js.Date.makeWithYMD(~year=2024, ~month=0, ~date=1)
let endDate = Js.Date.makeWithYMD(~year=2024, ~month=1, ~date=1)
formatter->Intl.DateTimeFormat.formatRange(~startDate=startDate, ~endDate=endDate)->String.length > 0

formatRangeToParts

RESCRIPT
let formatRangeToParts: ( t, ~startDate: Date.t, ~endDate: Date.t, ) => array<dateTimeRangePart>

formatRangeToParts(formatter, ~startDate, ~endDate) returns an array describing how the range would be rendered.

See Intl.DateTimeFormat.prototype.formatRangeToParts on MDN.

Examples

RESCRIPT
let formatter = Intl.DateTimeFormat.make(~locales=["en-US"], ~options={dateStyle: #short})
let startDate = Js.Date.makeWithYMD(~year=2024, ~month=0, ~date=1)
let endDate = Js.Date.makeWithYMD(~year=2024, ~month=1, ~date=1)
formatter->Intl.DateTimeFormat.formatRangeToParts(~startDate=startDate, ~endDate=endDate)->Array.length > 0

ignore

RESCRIPT
let ignore: t => unit

ignore(dateTimeFormat) ignores the provided dateTimeFormat and returns unit.

This helper is useful when you want to discard a value (for example, the result of an operation with side effects) without having to store or process it further.