Skip to content

std::calendar

Calendar dates, times, civil periods, machine-time projections, and IANA-zone-aware date-time arithmetic. A date or time reads as a reader of a locale writes it with format, at a style’s length (Date.format(d, locale, style: .Long)) or with the fields a skeleton names (Date.format_fields(d, locale, DateFields"yMMMd")), and is read back from what a reader typed with parse_in. A fixed numeric pattern, the same in every locale, is for file names and protocols: Date.to_string_with(d, DatePattern"yyyyMMdd") and parse_with. TimeUnit.format_relative writes “in 3 days” or “yesterday”. The calendar is the Gregorian one; the words and patterns come from CLDR, from the data the program carries.

std::calendar covers civil dates and times: wall-clock readings, zoned moments, the conversions between them, and DST-aware arithmetic. std::instant has the clock and the absolute Instant, and std::duration has exact elapsed time, Duration.

Import with import std::calendar.

Five civil types, in increasing specificity:

  • Date: a calendar day. Year, month and day; no time of day.
  • Time: a time of day. Hour, minute, second and nanosecond; no calendar.
  • NaiveDateTime: a wall-clock reading. A date and a time of day, no zone. It names no moment.
  • OffsetDateTime: anchored at a fixed UTC offset. A real moment; no DST.
  • DateTime: anchored in an IANA zone (America/New_York, Asia/Tokyo, …), following its daylight-saving rules. The type to use for a moment.

Two adjacent types live in sibling modules:

  • Instant (std::instant): nanoseconds since the Unix epoch, in UTC. It has no calendar and no zone. Instant + Duration and Instant - Duration are Instants; a - b on two Instants is the Duration from b to a (Instant.between(b, a)).
  • Duration (std::duration): exact elapsed time, a count of nanoseconds. Build one with a unit function such as Duration.seconds(5), or with a literal as Display writes it, Duration"1h30m". Hours, minutes and seconds are units there; months and years are not, since their lengths vary.

The five types mirror java.time (LocalDate, LocalTime, LocalDateTime, OffsetDateTime, ZonedDateTime) under other names. The bare name DateTime is the zoned type, the one to use for a moment. The reading with no zone has the longer name, NaiveDateTime, so code that uses it says that the value names no moment.

Each of the five types has a typed literal, the usual way to write a value:

Date"YYYY-MM-DD"
Time"HH:MM:SS[.fff…]"
NaiveDateTime"YYYY-MM-DDTHH:MM:SS[.fff…]"
OffsetDateTime"YYYY-MM-DDTHH:MM:SS[.fff…]±HH:MM"  // or trailing Z
DateTime"YYYY-MM-DDTHH:MM:SS[.fff…]±HH:MM[Zone/Name]"

A literal without slots (Date"2026-05-04") is parsed when the program compiles: it is a Date, and a malformed one is a compile error. A literal with a slot (Date"2026-${month}-04") is parsed at run time, and its parse failure returns Err(calendar.Error); unwrap it with ? at the call site. Date.parse reads text the program gets while it runs. The spec’s typed literals give the mechanism.

DateTime’s literal uses RFC 9557 bracket notation, and the IANA zone bracket is required. A bare offset (no bracket) parses as OffsetDateTime"…" instead: the bracket tells “anchored in a zone” from “anchored at a fixed offset”.

The programmatic constructors are Date.new, Time.new and NaiveDateTime.new (validated, each a Result), DateTime.in_zone (a wall reading projected through a zone, below), OffsetDateTime.with_offset, OffsetDateTime.from_instant (each a Result), DateTime.from_instant_in (a Result: UnknownZone), DateTime.now_in (the system clock projected into a zone) and NaiveDateTime.utc_now (the system clock as a UTC wall reading).

The calendar is the proleptic Gregorian one in both directions, with no first or last year: a year is an Int of any size, and no construction, conversion or arithmetic fails or faults for how far it goes. A year from 0000 to 9999 is written with four digits, and any other with a sign and at least six, ISO 8601’s expanded form as RFC 9557 writes it: Date"+010000-01-01", Date"-000044-03-15" (45 BC, since year 0 is 1 BC). Every parse reads that form back, and also a year of more than four digits without a sign (10000-01-01) and a sign with four (-0044-03-15).

Date"2026-05-04" + Years(300_000_000_000) // → +300000002026-05-04

Arithmetic has two intents, and they differ because + Hours(24) is not always + Duration.hours(24) around a DST transition.

  • value + Duration and value - Duration are exact elapsed time. Adding 24 real hours shifts the instant by 24 hours of physical time, wherever the wall clock lands. Each time-bearing type implements Add and Subtract with Duration as the right-hand operand and itself as the result (impl Add<Duration, DateTime> for DateTime).
  • value + Years(...) and Months, Weeks, Days, Hours, Minutes, Seconds, Milliseconds, Microseconds and Nanoseconds (and - of each) are civil period arithmetic. They adjust the wall reading and, for a zoned DateTime, resolve it through the zone again. Months and years clamp to the end of the month (Date"2026-01-31" + Months(1) is Date"2026-02-28"). A Date takes years, months, weeks and days; the date-time types take all ten; a Time takes only a Duration, and wraps at midnight.

Across a spring-forward transition the two differ:

start = DateTime"2026-03-07T12:00:00-05:00[America/New_York]"

start + Hours(24) // → noon Mar 8 EDT (23h physical)

start + Duration.hours(24) // → 1pm  Mar 8 EDT (24h physical)

The wall reading “tomorrow at noon” stays at noon after the jump, and only 23 hours of real time pass. “Add 24 real hours” advances through the transition and lands at 1pm. Both are correct; the split lets the caller say which intent applies.

Projecting a wall reading into an IANA zone (DateTime.in_zone) can hit one of two anomalies:

  • A spring-forward gap: the wall reading never exists. 2026-03-08T02:30 in New York is in the gap: 02:00 EST jumps straight to 03:00 EDT, and the half hour between is unreachable.
  • A fall-back fold: the wall reading exists twice. 2026-11-01T01:30 in New York happens twice: 02:00 EDT rolls back to 01:00 EST, so 01:30 occurs once before the rollback and once after.

The Disambiguation enum says how in_zone resolves them:

ModeIn a foldIn a gap
Compatible (default)Earlier instant (pre-transition)Post-transition instant
EarlierEarlier instantPre-transition instant
LaterLater instantPost-transition instant
RejectErr(Ambiguous ...)Err(Nonexistent ...)

Compatible is total and deterministic. Reject is the strict mode for a wall reading that came from user input (a form, an API payload), where the right answer is to hand the ambiguity back to the user. Civil shifts (+ Years(...), + Months(...), + Hours(...), …) always use Compatible internally, so they are total; only DateTime.in_zone(..., Disambiguation.Reject) reports a gap or a fold.

                                Date  ──────┐
                                            │
                                Time  ──────┤  of / at_midnight
                                            ▼
Instant  ◄─────────────►  OffsetDateTime ◄────►  NaiveDateTime
   │                            ▲                    │
   │                            │ to_offset          │ in_zone
   │                            │ (lossy)            │ (with mode)
   ▼                            │                    ▼
Duration                        └──────  DateTime  ◄─┘
                                            │
                                            └─ with_zone
                                               (same instant,
                                                different zone)

A wall reading is not a moment, so a NaiveDateTime becomes one only where the code says whose clock showed it: a zone, with DateTime.in_zone(naive, zone, mode), or a fixed offset, with OffsetDateTime.with_offset(naive, offset) or NaiveDateTime.to_instant(naive, offset). NaiveDateTime.to_instant with no offset reads the value as a UTC reading, which is what NaiveDateTime.utc_now returns.

Two conversions are missing on purpose:

  1. OffsetDateTime to DateTime. A fixed offset does not determine an IANA zone: offset -05:00 is in effect in many zones at various points in history. The caller names the zone: OffsetDateTime.to_instant, then DateTime.from_instant_in(instant, zone).
  2. Date or Time to Instant. A calendar day or a time of day is not a moment. NaiveDateTime.of(date, time) makes a NaiveDateTime, and in_zone carries it the rest of the way.

OffsetDateTime and DateTime compare and order by their instant only. Two values with the same underlying nanoseconds and different offsets or zones are equal:

ny = DateTime"2026-06-15T12:00:00-04:00[America/New_York]"

paris = DateTime"2026-06-15T18:00:00+02:00[Europe/Paris]"

ny == paris // → True (same instant)

The offset or zone decides how a value displays and takes no part in ==. To ask for the same instant in the same zone, compare the displayed forms too, since a DateTime displays with its zone bracket:

a == b and Display.to_string(a) == Display.to_string(b)

== reaches these types’ Equatable impls by the spec’s rule for operators on a type with a hand-written Equatable (Type relations). Date, Time and NaiveDateTime use structural equality (every field equal) and order chronologically by field order.

The calendar types write themselves for a reader in three ways, Gregorian only: by a style (format), by a skeleton (format_fields), and by a fixed numeric pattern (to_string_with, read back with parse_with). parse_in reads what a reader typed. Date, Time, NaiveDateTime and DateTime implement Localize with format’s defaults; Display stays ISO 8601.

Styles. DateStyle and TimeStyle are Full, Long, Medium and Short, and the locale decides the rest. A date and a time join as the locale’s date-time pattern for the date’s style joins them. A Long time of a DateTime ends with its offset in the locale’s short GMT format (GMT+2, UTC+2 in fr) and a Full one in its long format (GMT+02:00); std has no zone names. A Time and a NaiveDateTime have no zone, so their Full and Long times write what Medium does.

Skeletons. DateFields, TimeFields and DateTimeFields name the fields a value shows and their widths as a CLDR skeleton: y the year, M or L the month (M its number, MMM its short name, MMMM its name), d the day, E the weekday, G the era, j the hour as the locale writes it (h a 12-hour clock’s, H a 24-hour one’s), m, s and S. Each locale’s data gives the order, the punctuation and the words: DateFields"MMMMd" is October 20 in en, 20 października in pl and 10月20日 in ja. This is ICU’s date-time pattern generator over the locale’s available formats (UTS #35, Matching Skeletons): the available skeleton with the same fields and the nearest widths, widened to the widths asked for, except a field the locale writes in another form (ja writes a month as a number where a skeleton names it); a skeleton with date and time fields that no one format covers is the two joined. The literal is checked when the program is checked: a letter that is no field, a field the type does not hold (an hour in a DateFields), a field named twice or one too wide is a compile error at the literal. When every skeleton a built program uses is a literal, the build resolves each one for each listed locale, and the image carries those patterns instead of the locales’ available formats.

Fixed patterns. DatePattern, TimePattern and DateTimePattern are numeric LDML patterns that write the same text in every locale, for file names, logs and protocols: y (yy two digits), M, d, D, H, m, s (each doubled for two digits), S (one per fraction digit), and quoted or non-letter text. A month or weekday name, AM or PM, an era and a zone are words or need them, so a pattern holds none: typed literal DatePattern"dd MMM yyyy" is invalid: invalid format: `MMM` writes the month's name, which is a word of a language: a fixed pattern writes numbers, the same in every locale; write it for a reader with a skeleton and a locale, as Date.format_fields(date, locale, DateFields"yMMMd"). parse_with reads what to_string_with writes, a one-digit field standing for a two-digit one. DatePattern.parse and its kin check a pattern made while the program runs.

Parsing. parse_in reads text by the locale’s pattern at a style, strictly by default: a two-digit field may be written with one digit, any space stands for a space the locale writes, and ASCII digits for the locale’s. Lenient parsing also reads names in any width or case, with or without their final period, any spaces and punctuation between fields, a four-digit year where the locale writes two, and spaces around the text. A two-digit year is 2000 plus its digits. Text that does not read is Error.InvalidFormat, naming what was expected where, and a value that is no date is Error.InvalidValue (month 2 of 2026 has no day 31).

std::calendar carries the IANA time zone database, so zone lookups (America/New_York, Asia/Tokyo, …) work on every host without system-provided tzdata. Programs ship with their own zone database, and behavior is the same on every operating system and in minimal Docker images.

enum Error
    InvalidFormat String
    InvalidValue String
    UnknownZone String
    Nonexistent String
    Ambiguous String
end

What went wrong building, parsing or converting a calendar value. Each variant holds the reason as text, and Display writes the kind and then the reason.

Every type’s constructors and parsers return InvalidFormat, for text that does not read, and InvalidValue, for a value that is no date or time (day 30 not valid for 2026-02). The other three come from DateTime alone. UnknownZone is a zone name the embedded zone database lacks. Nonexistent is a wall reading in a spring-forward gap and Ambiguous one in a fall-back fold, which DateTime.in_zone returns only with Disambiguation.Reject; the other modes resolve both.

assert Date.new(2026, 2, 30) == Err(Error.InvalidValue("day 30 not valid for 2026-02"))

assert Display.to_string(Error.InvalidValue("month out of range: 13"))
    == "invalid value: month out of range: 13"

impl Display for Error

fn to_string(e: Error) -> String

impl Display.to_string

impl Debug for Error

fn inspect(value: Error) -> String

impl Debug.inspect

impl Equatable for Error

fn equal(a: Error, b: Error) -> Bool

impl Equatable.equal

type Years Int

Whole calendar years for civil calendar arithmetic on date-bearing values. Adding years to February 29 gives February 28 in a year that is not a leap year.

assert Date"2024-02-29" + Years(1) == Date"2025-02-28"
assert Date"2024-02-29" + Years(4) == Date"2028-02-29"

impl Debug for Years

fn inspect(value: Years) -> String

impl Debug.inspect

impl Equatable for Years

fn equal(a: Years, b: Years) -> Bool

impl Equatable.equal

impl Hashable for Years

fn hash(value: Years) -> Int

impl Hashable.hash

impl Comparable for Years

fn compare(a: Years, b: Years) -> Ordering

impl Comparable.compare

impl Display for Years

fn to_string(value: Years) -> String

impl Display.to_string

type Months Int

Whole calendar months for civil calendar arithmetic on date-bearing values. Adding months clamps to the end of the month.

assert Date"2026-01-31" + Months(1) == Date"2026-02-28"

impl Debug for Months

fn inspect(value: Months) -> String

impl Debug.inspect

impl Equatable for Months

fn equal(a: Months, b: Months) -> Bool

impl Equatable.equal

impl Hashable for Months

fn hash(value: Months) -> Int

impl Hashable.hash

impl Comparable for Months

fn compare(a: Months, b: Months) -> Ordering

impl Comparable.compare

impl Display for Months

fn to_string(value: Months) -> String

impl Display.to_string

type Weeks Int

Whole calendar weeks for civil calendar arithmetic on date-bearing values.

assert Date"2026-05-04" + Weeks(2) == Date"2026-05-18"

impl Debug for Weeks

fn inspect(value: Weeks) -> String

impl Debug.inspect

impl Equatable for Weeks

fn equal(a: Weeks, b: Weeks) -> Bool

impl Equatable.equal

impl Hashable for Weeks

fn hash(value: Weeks) -> Int

impl Hashable.hash

impl Comparable for Weeks

fn compare(a: Weeks, b: Weeks) -> Ordering

impl Comparable.compare

impl Display for Weeks

fn to_string(value: Weeks) -> String

impl Display.to_string

type Days Int

Whole calendar days for civil calendar arithmetic on date-bearing values. In a zone, a day keeps the time of day across a daylight-saving change.

assert Date"2026-05-04" - Days(4) == Date"2026-04-30"

assert DateTime"2026-03-07T12:00:00-05:00[America/New_York]" + Days(1)
    == DateTime"2026-03-08T12:00:00-04:00[America/New_York]"

impl Debug for Days

fn inspect(value: Days) -> String

impl Debug.inspect

impl Equatable for Days

fn equal(a: Days, b: Days) -> Bool

impl Equatable.equal

impl Hashable for Days

fn hash(value: Days) -> Int

impl Hashable.hash

impl Comparable for Days

fn compare(a: Days, b: Days) -> Ordering

impl Comparable.compare

impl Display for Days

fn to_string(value: Days) -> String

impl Display.to_string

type Hours Int

Whole civil hours for date-time wall-clock arithmetic. They move the wall reading, so across a spring-forward transition + Hours(24) keeps the time of day where + Duration.hours(24) moves it.

start = DateTime"2026-03-07T12:00:00-05:00[America/New_York]"
assert start + Hours(24) == DateTime"2026-03-08T12:00:00-04:00[America/New_York]"
assert start + Duration.hours(24) == DateTime"2026-03-08T13:00:00-04:00[America/New_York]"

impl Debug for Hours

fn inspect(value: Hours) -> String

impl Debug.inspect

impl Equatable for Hours

fn equal(a: Hours, b: Hours) -> Bool

impl Equatable.equal

impl Hashable for Hours

fn hash(value: Hours) -> Int

impl Hashable.hash

impl Comparable for Hours

fn compare(a: Hours, b: Hours) -> Ordering

impl Comparable.compare

impl Display for Hours

fn to_string(value: Hours) -> String

impl Display.to_string

type Minutes Int

Whole civil minutes for date-time wall-clock arithmetic.

impl Debug for Minutes

fn inspect(value: Minutes) -> String

impl Debug.inspect

impl Equatable for Minutes

fn equal(a: Minutes, b: Minutes) -> Bool

impl Equatable.equal

impl Hashable for Minutes

fn hash(value: Minutes) -> Int

impl Hashable.hash

impl Comparable for Minutes

fn compare(a: Minutes, b: Minutes) -> Ordering

impl Comparable.compare

impl Display for Minutes

fn to_string(value: Minutes) -> String

impl Display.to_string

type Seconds Int

Whole civil seconds for date-time wall-clock arithmetic.

impl Debug for Seconds

fn inspect(value: Seconds) -> String

impl Debug.inspect

impl Equatable for Seconds

fn equal(a: Seconds, b: Seconds) -> Bool

impl Equatable.equal

impl Hashable for Seconds

fn hash(value: Seconds) -> Int

impl Hashable.hash

impl Comparable for Seconds

fn compare(a: Seconds, b: Seconds) -> Ordering

impl Comparable.compare

impl Display for Seconds

fn to_string(value: Seconds) -> String

impl Display.to_string

type Milliseconds Int

Whole civil milliseconds for date-time wall-clock arithmetic.

impl Debug for Milliseconds

fn inspect(value: Milliseconds) -> String

impl Debug.inspect

impl Equatable for Milliseconds

fn equal(a: Milliseconds, b: Milliseconds) -> Bool

impl Equatable.equal

impl Hashable for Milliseconds

fn hash(value: Milliseconds) -> Int

impl Hashable.hash

impl Comparable for Milliseconds

fn compare(a: Milliseconds, b: Milliseconds) -> Ordering

impl Comparable.compare

impl Display for Milliseconds

fn to_string(value: Milliseconds) -> String

impl Display.to_string

type Microseconds Int

Whole civil microseconds for date-time wall-clock arithmetic.

impl Debug for Microseconds

fn inspect(value: Microseconds) -> String

impl Debug.inspect

impl Equatable for Microseconds

fn equal(a: Microseconds, b: Microseconds) -> Bool

impl Equatable.equal

impl Hashable for Microseconds

fn hash(value: Microseconds) -> Int

impl Hashable.hash

impl Comparable for Microseconds

fn compare(a: Microseconds, b: Microseconds) -> Ordering

impl Comparable.compare

impl Display for Microseconds

fn to_string(value: Microseconds) -> String

impl Display.to_string

type Nanoseconds Int

Whole civil nanoseconds for date-time wall-clock arithmetic.

impl Debug for Nanoseconds

fn inspect(value: Nanoseconds) -> String

impl Debug.inspect

impl Equatable for Nanoseconds

fn equal(a: Nanoseconds, b: Nanoseconds) -> Bool

impl Equatable.equal

impl Hashable for Nanoseconds

fn hash(value: Nanoseconds) -> Int

impl Hashable.hash

impl Comparable for Nanoseconds

fn compare(a: Nanoseconds, b: Nanoseconds) -> Ordering

impl Comparable.compare

impl Display for Nanoseconds

fn to_string(value: Nanoseconds) -> String

impl Display.to_string

interface DateParts
    fn year(value: self) -> Int
    fn month(value: self) -> Int
    fn day(value: self) -> Int
end

The year, the month (1 to 12) and the day of the month of a value that has a date. Date, NaiveDateTime, OffsetDateTime and DateTime implement it; the last two read their wall clock at their offset or in their zone.

fn year(value: self) -> Int

interface DateParts

fn month(value: self) -> Int

interface DateParts

fn day(value: self) -> Int

interface DateParts

interface TimeParts
    fn hour(value: self) -> Int
    fn minute(value: self) -> Int
    fn second(value: self) -> Int
    fn nanosecond(value: self) -> Int
end

The hour (0 to 23), minute, second and nanosecond of a value that has a time of day. Time, NaiveDateTime, OffsetDateTime and DateTime implement it; the last two read their wall clock at their offset or in their zone.

fn hour(value: self) -> Int

interface TimeParts

fn minute(value: self) -> Int

interface TimeParts

fn second(value: self) -> Int

interface TimeParts

fn nanosecond(value: self) -> Int

interface TimeParts

interface Anchored
    fn to_instant(value: self) -> Instant
    fn offset(value: self) -> Duration
end

The Instant a value names and its UTC offset at that instant. OffsetDateTime and DateTime implement it.

fn to_instant(value: self) -> Instant

interface Anchored

fn offset(value: self) -> Duration

interface Anchored

struct Date

opaque — construction surface is private to its defining module

A calendar date: a year, a month and a day, with no time of day and no zone. Build one with the Date"…" typed literal, Date.new(y, m, d) or Date.parse, and read its parts with Date.year, Date.month and Date.day (the DateParts interface). The year is an Int of any size; one outside 0000 to 9999 is written with a sign and at least six digits.

assert Display.to_string(Date"2026-05-04") == "2026-05-04"
assert Date.month(Date"2026-05-04") == 5
assert Display.to_string(Date.new(-1, 12, 31)!) == "-000001-12-31"
assert Date"2026-05-04" + Years(300_000_000_000) == Date"+300000002026-05-04"
fn new(year: Int, month: Int, day: Int) -> Result<Date, Error>

type function on Date

Construct a Date, checking that the month is 1 to 12 and has the day: no February 30, and February 29 only in a leap year. A date that does not exist is Err(.InvalidValue(...)). Any year is valid.

assert Date.new(2026, 5, 4)? == Date"2026-05-04"
assert Err(Error.InvalidValue(_msg)) = Date.new(2026, 2, 30)
assert Date.new(Int.pow(10, 30), 2, 29)? == Date"+1000000000000000000000000000000-02-29"
fn parse(s: String) -> Result<Date, Error>

type function on Date

Parse an ISO 8601 date (YYYY-MM-DD). The Date"…" typed literal reads its text the same way. A year outside 0000 to 9999 takes a sign, as Display writes it; a year of more than four digits may go without one.

assert Date.parse("2026-05-04")? == Date"2026-05-04"
assert Err(Error.InvalidFormat(_msg)) = Date.parse("05/04/2026")
assert Date.parse("-000044-03-15")? == Date.new(-44, 3, 15)?
assert Date.parse("10000-01-01")? == Date"+010000-01-01"
fn days_between(earlier: Date, later: Date) -> Int

type function on Date

The number of days from earlier to later: positive when later is the later date, negative when it is the earlier one.

assert Date.days_between(Date"2026-05-04", Date"2026-05-07") == 3
assert Date.days_between(Date"2026-05-07", Date"2026-05-04") == -3
fn weekday(d: Date) -> Weekday

type function on Date

The day of the week the date falls on.

assert Date.weekday(Date"2026-10-20") == Weekday.Tuesday
assert Date.weekday(Date"2026-10-25") == Weekday.Sunday
assert Date.weekday(Date"1969-12-29") == Weekday.Monday
fn is_leap_year(year: Int) -> Bool

type function on Date

Whether year is a leap year in the Gregorian calendar, which Date follows for every year: one divisible by 4, except a century year not divisible by 400.

assert Date.is_leap_year(2024)
assert Date.is_leap_year(2000)
refute Date.is_leap_year(1900)
refute Date.is_leap_year(2026)
fn days_in_month(year: Int, month: Int) -> Result<Int, Error>

type function on Date

How many days month month (1 to 12) of year has: 28 to 31, with 29 in February of a leap year. A month outside 1 to 12 is Err(.InvalidValue(...)), as Date.new returns for it.

assert Date.days_in_month(2026, 1) == Ok(31)
assert Date.days_in_month(2026, 4) == Ok(30)
assert Date.days_in_month(2026, 2) == Ok(28)
assert Date.days_in_month(2024, 2) == Ok(29)
assert Date.days_in_month(2026, 13) == Err(Error.InvalidValue("month out of range: 13"))
fn format(d: Date, locale: Locale, style: DateStyle = DateStyle.Medium) -> String

type function on Date

The date as a reader of locale writes it, at the length style says: the locale decides the order, the punctuation and the words.

d = Date"2026-10-20"
assert Date.format(d, Locale"en") == "Oct 20, 2026"
assert Date.format(d, Locale"en", style: .Full) == "Tuesday, October 20, 2026"
assert Date.format(d, Locale"en", style: .Short) == "10/20/26"
assert Date.format(d, Locale"pl", style: .Long) == "20 października 2026"
assert Date.format(d, Locale"de", style: .Full) == "Dienstag, 20. Oktober 2026"
assert Date.format(d, Locale"ja", style: .Long) == "2026年10月20日"
fn format_fields(d: Date, locale: Locale, fields: DateFields) -> String

type function on Date

The date as a reader of locale writes the fields fields names, at their widths: a CLDR skeleton, from which the locale’s data gives the order, the punctuation and the words. yMMMd is a year, a month’s short name and a day; MMMMEEEEd a month’s name, a weekday’s and a day. A literal skeleton is checked when the program is checked.

d = Date"2026-10-20"
assert Date.format_fields(d, Locale"en", DateFields"yMMMd") == "Oct 20, 2026"
assert Date.format_fields(d, Locale"pl", DateFields"yMMMd") == "20 paź 2026"
assert Date.format_fields(d, Locale"en", DateFields"MMMMEEEEd") == "Tuesday, October 20"
assert Date.format_fields(d, Locale"pl", DateFields"MMMMd") == "20 października"
assert Date.format_fields(d, Locale"ja", DateFields"MMMMEEEEd") == "10月20日火曜日"
fn parse_in(text: String, locale: Locale, style: DateStyle = DateStyle.Short, lenient: Bool = False) -> Result<Date, Error>

type function on Date

Read a date a reader of locale typed, as Date.format writes it at style, strictly unless lenient: True. Strict takes one digit for a two-digit day or month, any space for a space the locale writes, and ASCII digits for the locale’s. Lenient also takes a name in any width or case, with or without its final period, any spaces and punctuation between the fields, a four-digit year where the locale writes two, and spaces around the date. A two-digit year is 2000 plus its digits, at every style.

assert Date.parse_in("4.5.26", Locale"de") == Ok(Date"2026-05-04")
assert Date.parse_in("20.10.26", Locale"de", style: .Medium) == Ok(Date"2026-10-20")
assert Date.parse_in("10/20/26", Locale"en") == Ok(Date"2026-10-20")
assert Date.parse_in("Oct 20, 2026", Locale"en", style: .Medium) == Ok(Date"2026-10-20")

assert Date.parse_in("october 20 2026", Locale"en", style: .Medium, lenient: True)
    == Ok(Date"2026-10-20")

assert Err(Error.InvalidFormat(_why)) = Date.parse_in("4.5.2026", Locale"de")
assert Date.parse_in("4.5.2026", Locale"de", lenient: True) == Ok(Date"2026-05-04")

assert Date.parse_in("31.2.26", Locale"de")
    == Err(Error.InvalidValue("month 2 of 2026 has no day 31"))
fn to_string_with(d: Date, pattern: DatePattern) -> String

type function on Date

The date by a fixed numeric pattern: the same text in every locale, for file names, logs and protocols.

assert Date.to_string_with(Date"2026-10-19", DatePattern"yyyy-MM-dd") == "2026-10-19"
assert Date.to_string_with(Date"2026-05-04", DatePattern"dd/MM/yyyy") == "04/05/2026"
assert Date.to_string_with(Date"2026-05-04", DatePattern"yyyyMMdd") == "20260504"
fn parse_with(text: String, pattern: DatePattern) -> Result<Date, Error>

type function on Date

Read a date by a fixed numeric pattern, as Date.to_string_with writes it. A one-digit day or month stands for a two-digit one.

assert Date.parse_with("19/10/2026", DatePattern"dd/MM/yyyy") == Ok(Date"2026-10-19")
assert Date.parse_with("20260504", DatePattern"yyyyMMdd") == Ok(Date"2026-05-04")
assert Err(Error.InvalidFormat(_why)) = Date.parse_with("2026-10-19", DatePattern"dd/MM/yyyy")

impl Literal for Date

fn from_fragments(fragments: List<Fragment<String>>) -> Result<Date, Error>

impl Literal.from_fragments

impl Display for Date

fn to_string(d: Date) -> String

impl Display.to_string

ISO 8601 date (YYYY-MM-DD). A year outside 0000 to 9999 has a sign and at least six digits.

impl Debug for Date

fn inspect(d: Date) -> String

impl Debug.inspect

impl DateParts for Date

fn year(value: Date) -> Int

impl DateParts.year

impl DateParts for Date

fn month(value: Date) -> Int

impl DateParts.month

impl DateParts for Date

fn day(value: Date) -> Int

impl DateParts.day

impl Add<Years, Date> for Date

fn add(lhs: Date, Years(n)) -> Date

impl Add.add

Add whole calendar years, clamping leap days when needed.

impl Add<Months, Date> for Date

fn add(lhs: Date, Months(n)) -> Date

impl Add.add

Add whole calendar months, clamping end-of-month.

assert Date"2011-01-31" + Months(1) == Date"2011-02-28"
assert Date"2012-01-31" + Months(1) == Date"2012-02-29"

impl Add<Weeks, Date> for Date

fn add(lhs: Date, Weeks(n)) -> Date

impl Add.add

Add whole calendar weeks.

impl Add<Days, Date> for Date

fn add(lhs: Date, Days(n)) -> Date

impl Add.add

Add whole calendar days.

impl Subtract<Years, Date> for Date

fn subtract(lhs: Date, Years(n)) -> Date

impl Subtract.subtract

Subtract whole calendar years, clamping leap days when needed.

impl Subtract<Months, Date> for Date

fn subtract(lhs: Date, Months(n)) -> Date

impl Subtract.subtract

Subtract whole calendar months, clamping end-of-month.

impl Subtract<Weeks, Date> for Date

fn subtract(lhs: Date, Weeks(n)) -> Date

impl Subtract.subtract

Subtract whole calendar weeks.

impl Subtract<Days, Date> for Date

fn subtract(lhs: Date, Days(n)) -> Date

impl Subtract.subtract

Subtract whole calendar days.

impl Localize for Date

fn localize(d: Date, locale: Locale) -> String

impl Localize.localize

The date as Date.format writes it at its default length.

assert Date.localize(Date"2026-10-20", Locale"en") == "Oct 20, 2026"

impl Equatable for Date

fn equal(a: Date, b: Date) -> Bool

impl Equatable.equal

impl Hashable for Date

fn hash(value: Date) -> Int

impl Hashable.hash

impl Comparable for Date

fn compare(a: Date, b: Date) -> Ordering

impl Comparable.compare

struct Time

opaque — construction surface is private to its defining module

A time of day: an hour, a minute, a second and a nanosecond, with no date and no zone. Build one with the Time"…" typed literal, Time.new(h, m, s, ns) or Time.parse, and read its parts with Time.hour, Time.minute, Time.second and Time.nanosecond (the TimeParts interface).

assert Display.to_string(Time"08:30:00") == "08:30:00"
assert Time.hour(Time"08:30:00") == 8
fn new(hour: Int, minute: Int, second: Int = 0, nanosecond: Int = 0) -> Result<Time, Error>

type function on Time

Construct a Time, checking each part’s range: the hour 0 to 23, the minute and second 0 to 59, the nanosecond 0 to 999_999_999. One out of range is Err(.InvalidValue(...)).

assert Time.new(8, 30)? == Time"08:30:00"
assert Time.new(8, 30, 15, 250_000_000)? == Time"08:30:15.25"
assert Err(Error.InvalidValue(_msg)) = Time.new(24, 0)
fn parse(s: String) -> Result<Time, Error>

type function on Time

Parse a time of day (HH:MM:SS or HH:MM:SS.fff…, with up to nine digits of the second). The seconds are required.

assert Time.parse("08:30:00")? == Time"08:30:00"
assert Err(Error.InvalidFormat(_msg)) = Time.parse("08:30")
assert Err(Error.InvalidFormat(_msg)) = Time.parse("nope")
fn between(earlier: Time, later: Time) -> Duration

type function on Time

Exact duration from earlier to later within one day, negative when later is the earlier time.

assert Time.between(Time"08:30:00", Time"08:33:00") == Duration.minutes(3)
assert Time.between(Time"08:33:00", Time"08:30:00") == Duration.minutes(-3)
fn format(t: Time, locale: Locale, style: TimeStyle = TimeStyle.Short) -> String

type function on Time

The time of day as a reader of locale writes it, at the length style says: a 12-hour clock with AM and PM in en, a 24-hour one in de. A Time has no zone, so Full and Long write what Medium does.

t = Time"21:30:00"
assert Time.format(t, Locale"en") == "9:30\u{202f}PM"
assert Time.format(t, Locale"de") == "21:30"
assert Time.format(t, Locale"fr", style: .Medium) == "21:30:00"
fn format_fields(t: Time, locale: Locale, fields: TimeFields) -> String

type function on Time

The time of day as a reader of locale writes the fields fields names: jm is the hour as the locale writes it and the minutes, Hm a 24-hour clock, hm a 12-hour one.

t = Time"21:30:00"
assert Time.format_fields(t, Locale"en", TimeFields"jm") == "9:30\u{202f}PM"
assert Time.format_fields(t, Locale"en", TimeFields"Hm") == "21:30"
assert Time.format_fields(t, Locale"de", TimeFields"hm") == "9:30\u{202f}PM"
fn parse_in(text: String, locale: Locale, style: TimeStyle = TimeStyle.Short, lenient: Bool = False) -> Result<Time, Error>

type function on Time

Read a time of day a reader of locale typed, as Time.format writes it at style, strictly unless lenient: True, as Date.parse_in reads a date.

assert Time.parse_in("9:30\u{202f}PM", Locale"en") == Ok(Time"21:30:00")
assert Time.parse_in("9:30 PM", Locale"en") == Ok(Time"21:30:00")
assert Time.parse_in("9:30 pm", Locale"en", lenient: True) == Ok(Time"21:30:00")
assert Time.parse_in("21:30", Locale"de") == Ok(Time"21:30:00")
fn to_string_with(t: Time, pattern: TimePattern) -> String

type function on Time

The time of day by a fixed numeric pattern, a 24-hour clock.

assert Time.to_string_with(Time"09:05:00", TimePattern"HHmmss") == "090500"
assert Time.to_string_with(Time"09:05:00.25", TimePattern"HH:mm:ss.SSS") == "09:05:00.250"
fn parse_with(text: String, pattern: TimePattern) -> Result<Time, Error>

type function on Time

Read a time of day by a fixed numeric pattern.

assert Time.parse_with("0905", TimePattern"HHmm") == Ok(Time"09:05:00")

impl Literal for Time

fn from_fragments(fragments: List<Fragment<String>>) -> Result<Time, Error>

impl Literal.from_fragments

impl Display for Time

fn to_string(t: Time) -> String

impl Display.to_string

ISO 8601 time (HH:MM:SS). A fraction of a second follows only when it is not zero, without trailing zeros: 09:30:00, 09:30:00.25.

impl Debug for Time

fn inspect(t: Time) -> String

impl Debug.inspect

impl TimeParts for Time

fn hour(value: Time) -> Int

impl TimeParts.hour

impl TimeParts for Time

fn minute(value: Time) -> Int

impl TimeParts.minute

impl TimeParts for Time

fn second(value: Time) -> Int

impl TimeParts.second

impl TimeParts for Time

fn nanosecond(value: Time) -> Int

impl TimeParts.nanosecond

impl Add<Duration, Time> for Time

fn add(lhs: Time, rhs: Duration) -> Time

impl Add.add

Add an exact Duration, wrapping around midnight.

assert Time"08:33:00" + Duration.minutes(3) == Time"08:36:00"
assert Time"23:00:00" + Duration.hours(2) == Time"01:00:00"

impl Subtract<Duration, Time> for Time

fn subtract(lhs: Time, rhs: Duration) -> Time

impl Subtract.subtract

Subtract an exact Duration, wrapping around midnight.

assert Time"08:36:00" - Duration.minutes(3) == Time"08:33:00"

impl Localize for Time

fn localize(t: Time, locale: Locale) -> String

impl Localize.localize

The time of day as Time.format writes it at its default length.

assert Time.localize(Time"21:30:00", Locale"de") == "21:30"

impl Equatable for Time

fn equal(a: Time, b: Time) -> Bool

impl Equatable.equal

impl Hashable for Time

fn hash(value: Time) -> Int

impl Hashable.hash

impl Comparable for Time

fn compare(a: Time, b: Time) -> Ordering

impl Comparable.compare

struct NaiveDateTime

opaque — construction surface is private to its defining module

A date and a time of day with no zone or offset: a wall-clock reading such as 2026-05-04T14:30:00. It looks like a timestamp, but without a zone it names no moment. Use DateTime for a moment, and NaiveDateTime where the value is a wall reading: a calendar template, a schedule pattern, a local time that a zone resolves later.

dt = NaiveDateTime"2026-05-04T14:30:00"
assert dt == NaiveDateTime.of(Date"2026-05-04", Time"14:30:00")
assert Display.to_string(dt + Hours(10)) == "2026-05-05T00:30:00"
fn format(dt: NaiveDateTime, locale: Locale, date: DateStyle = DateStyle.Medium, time: TimeStyle = TimeStyle.Short) -> String

type function on NaiveDateTime

The date and time as a reader of locale writes them, the date at the length date says and the time at time’s, joined as the locale joins them.

dt = NaiveDateTime"2026-10-20T09:30:00"
assert NaiveDateTime.format(dt, Locale"en") == "Oct 20, 2026, 9:30\u{202f}AM"
assert NaiveDateTime.format(dt, Locale"de", date: .Long) == "20. Oktober 2026, 09:30"
fn format_fields(dt: NaiveDateTime, locale: Locale, fields: DateTimeFields) -> String

type function on NaiveDateTime

The date and time as a reader of locale writes the fields fields names.

dt = NaiveDateTime"2026-10-20T09:30:00"

assert NaiveDateTime.format_fields(dt, Locale"en", DateTimeFields"MMMdjm")
    == "Oct 20, 9:30\u{202f}AM"
fn to_string_with(dt: NaiveDateTime, pattern: DateTimePattern) -> String

type function on NaiveDateTime

The date and time by a fixed numeric pattern.

dt = NaiveDateTime"2026-10-19T09:30:00"
assert NaiveDateTime.to_string_with(dt, DateTimePattern"yyyyMMdd'T'HHmmss") == "20261019T093000"
fn parse_with(text: String, pattern: DateTimePattern) -> Result<NaiveDateTime, Error>

type function on NaiveDateTime

Read a date and time by a fixed numeric pattern.

assert NaiveDateTime.parse_with("20261019T093000", DateTimePattern"yyyyMMdd'T'HHmmss")
    == Ok(NaiveDateTime"2026-10-19T09:30:00")
fn of(d: Date, t: Time) -> NaiveDateTime

type function on NaiveDateTime

Combine a Date and a Time. Both parts are valid already, so it cannot fail.

assert NaiveDateTime.of(Date"2026-05-04", Time"14:30:00") == NaiveDateTime"2026-05-04T14:30:00"
fn at_midnight(d: Date) -> NaiveDateTime

type function on NaiveDateTime

A NaiveDateTime at midnight (00:00:00) on the given date.

assert NaiveDateTime.at_midnight(Date"2026-05-04") == NaiveDateTime"2026-05-04T00:00:00"
fn to_date(dt: NaiveDateTime) -> Date

type function on NaiveDateTime

The date.

assert NaiveDateTime.to_date(NaiveDateTime"2026-05-04T14:30:00") == Date"2026-05-04"
fn to_time(dt: NaiveDateTime) -> Time

type function on NaiveDateTime

The time of day.

assert NaiveDateTime.to_time(NaiveDateTime"2026-05-04T14:30:00") == Time"14:30:00"
fn new(year: Int, month: Int, day: Int, hour: Int, minute: Int, second: Int = 0, nanosecond: Int = 0) -> Result<NaiveDateTime, Error>

type function on NaiveDateTime

Construct from a year, month, day, hour and minute, and a second and nanosecond when given, checking each part’s range and that the month has the day, as Date.new and Time.new do.

assert NaiveDateTime.new(2026, 5, 4, 14, 30)? == NaiveDateTime"2026-05-04T14:30:00"
assert Err(Error.InvalidValue(_msg)) = NaiveDateTime.new(2026, 2, 30, 12, 0)
fn parse(s: String) -> Result<NaiveDateTime, Error>

type function on NaiveDateTime

Parse an ISO 8601 date and time with no offset (YYYY-MM-DDTHH:MM:SS[.fff…]). One space may stand for the T.

assert NaiveDateTime.parse("2026-05-04T14:30:00")?
    == NaiveDateTime.of(Date"2026-05-04", Time"14:30:00")

assert NaiveDateTime.parse("2026-05-04 14:30:00")? == NaiveDateTime"2026-05-04T14:30:00"
fn between(earlier: NaiveDateTime, later: NaiveDateTime) -> Duration

type function on NaiveDateTime

Exact duration from earlier to later, counting each day as 24 hours; negative when later is the earlier reading.

assert NaiveDateTime.between(NaiveDateTime"2026-05-04T09:00:00", NaiveDateTime"2026-05-04T11:30:00")
    == Duration.minutes(150)
fn from_instant(i: Instant, offset: Duration = Duration.seconds(0)) -> NaiveDateTime

type function on NaiveDateTime

The wall reading of an Instant at a fixed UTC offset, UTC when no offset is given: what a clock at that offset showed at that moment. A sub-second offset is truncated to whole seconds, as OffsetDateTime.from_instant truncates it, and an offset of any length moves the reading by that much. For a reading in an IANA zone, read DateTime.from_instant_in(i, zone) with DateTime.to_naive.

assert NaiveDateTime.from_instant(Instant.from_seconds(0)) == NaiveDateTime"1970-01-01T00:00:00"

assert NaiveDateTime.from_instant(Instant.from_seconds(0), Duration.hours(-5))
    == NaiveDateTime"1969-12-31T19:00:00"

assert NaiveDateTime.from_instant(Instant.from_seconds(0), Duration.hours(48))
    == NaiveDateTime"1970-01-03T00:00:00"
fn utc_now() -> NaiveDateTime

type function on NaiveDateTime

Read the current wall clock in UTC: the form a database TIMESTAMP column (one without a time zone) holds when the program writes UTC into it. The same as NaiveDateTime.from_instant(Instant.now()). A naive reading names no moment by itself; for an absolute time read Instant.now(), and for a reading in a zone DateTime.now_in.

before = NaiveDateTime.from_instant(Instant.now())
assert NaiveDateTime.between(before, NaiveDateTime.utc_now()) >= Duration.seconds(0)
fn to_instant(dt: NaiveDateTime, offset: Duration = Duration.seconds(0)) -> Instant

type function on NaiveDateTime

The Instant a clock at a fixed UTC offset showed this reading at, reading it as UTC when no offset is given: the inverse of NaiveDateTime.from_instant. An Instant has no range, so every reading has one. To resolve a reading in an IANA zone, use DateTime.in_zone.

assert NaiveDateTime.to_instant(NaiveDateTime"1970-01-01T00:00:42") == Instant.from_seconds(42)

assert NaiveDateTime.to_instant(NaiveDateTime"1969-12-31T19:00:00", Duration.hours(-5))
    == Instant.from_seconds(0)

assert Instant.to_seconds(NaiveDateTime.to_instant(NaiveDateTime"2300-01-01T00:00:00"))
    == 10_413_792_000

i = Instant.from_nanos(-1_700_000_000_123_456_789)

assert NaiveDateTime.to_instant(NaiveDateTime.from_instant(i, Duration.hours(9)), Duration.hours(9))
    == i

impl Literal for NaiveDateTime

fn from_fragments(fragments: List<Fragment<String>>) -> Result<NaiveDateTime, Error>

impl Literal.from_fragments

impl Display for NaiveDateTime

fn to_string(dt: NaiveDateTime) -> String

impl Display.to_string

ISO 8601 date and time (YYYY-MM-DDTHH:MM:SS[.fff…]).

impl Debug for NaiveDateTime

fn inspect(dt: NaiveDateTime) -> String

impl Debug.inspect

impl DateParts for NaiveDateTime

fn year(value: NaiveDateTime) -> Int

impl DateParts.year

impl DateParts for NaiveDateTime

fn month(value: NaiveDateTime) -> Int

impl DateParts.month

impl DateParts for NaiveDateTime

fn day(value: NaiveDateTime) -> Int

impl DateParts.day

impl TimeParts for NaiveDateTime

fn hour(value: NaiveDateTime) -> Int

impl TimeParts.hour

impl TimeParts for NaiveDateTime

fn minute(value: NaiveDateTime) -> Int

impl TimeParts.minute

impl TimeParts for NaiveDateTime

fn second(value: NaiveDateTime) -> Int

impl TimeParts.second

impl TimeParts for NaiveDateTime

fn nanosecond(value: NaiveDateTime) -> Int

impl TimeParts.nanosecond

NaiveDateTime.add Add<Years, NaiveDateTime>

Section titled “NaiveDateTime.add Add<Years, NaiveDateTime>”

impl Add<Years, NaiveDateTime> for NaiveDateTime

fn add(lhs: NaiveDateTime, Years(n)) -> NaiveDateTime

impl Add.add

Add whole calendar years, clamping leap days when needed.

NaiveDateTime.add Add<Months, NaiveDateTime>

Section titled “NaiveDateTime.add Add<Months, NaiveDateTime>”

impl Add<Months, NaiveDateTime> for NaiveDateTime

fn add(lhs: NaiveDateTime, Months(n)) -> NaiveDateTime

impl Add.add

Add whole calendar months, clamping end-of-month.

NaiveDateTime.add Add<Weeks, NaiveDateTime>

Section titled “NaiveDateTime.add Add<Weeks, NaiveDateTime>”

impl Add<Weeks, NaiveDateTime> for NaiveDateTime

fn add(lhs: NaiveDateTime, Weeks(n)) -> NaiveDateTime

impl Add.add

Add whole calendar weeks.

NaiveDateTime.add Add<Days, NaiveDateTime>

Section titled “NaiveDateTime.add Add<Days, NaiveDateTime>”

impl Add<Days, NaiveDateTime> for NaiveDateTime

fn add(lhs: NaiveDateTime, Days(n)) -> NaiveDateTime

impl Add.add

Add whole calendar days.

NaiveDateTime.add Add<Hours, NaiveDateTime>

Section titled “NaiveDateTime.add Add<Hours, NaiveDateTime>”

impl Add<Hours, NaiveDateTime> for NaiveDateTime

fn add(lhs: NaiveDateTime, Hours(n)) -> NaiveDateTime

impl Add.add

Add whole civil hours.

NaiveDateTime.add Add<Minutes, NaiveDateTime>

Section titled “NaiveDateTime.add Add<Minutes, NaiveDateTime>”

impl Add<Minutes, NaiveDateTime> for NaiveDateTime

fn add(lhs: NaiveDateTime, Minutes(n)) -> NaiveDateTime

impl Add.add

Add whole civil minutes.

NaiveDateTime.add Add<Seconds, NaiveDateTime>

Section titled “NaiveDateTime.add Add<Seconds, NaiveDateTime>”

impl Add<Seconds, NaiveDateTime> for NaiveDateTime

fn add(lhs: NaiveDateTime, Seconds(n)) -> NaiveDateTime

impl Add.add

Add whole civil seconds.

NaiveDateTime.add Add<Milliseconds, NaiveDateTime>

Section titled “NaiveDateTime.add Add<Milliseconds, NaiveDateTime>”

impl Add<Milliseconds, NaiveDateTime> for NaiveDateTime

fn add(lhs: NaiveDateTime, Milliseconds(n)) -> NaiveDateTime

impl Add.add

Add whole civil milliseconds.

NaiveDateTime.add Add<Microseconds, NaiveDateTime>

Section titled “NaiveDateTime.add Add<Microseconds, NaiveDateTime>”

impl Add<Microseconds, NaiveDateTime> for NaiveDateTime

fn add(lhs: NaiveDateTime, Microseconds(n)) -> NaiveDateTime

impl Add.add

Add whole civil microseconds.

NaiveDateTime.add Add<Nanoseconds, NaiveDateTime>

Section titled “NaiveDateTime.add Add<Nanoseconds, NaiveDateTime>”

impl Add<Nanoseconds, NaiveDateTime> for NaiveDateTime

fn add(lhs: NaiveDateTime, Nanoseconds(n)) -> NaiveDateTime

impl Add.add

Add whole civil nanoseconds.

NaiveDateTime.add Add<Duration, NaiveDateTime>

Section titled “NaiveDateTime.add Add<Duration, NaiveDateTime>”

impl Add<Duration, NaiveDateTime> for NaiveDateTime

fn add(lhs: NaiveDateTime, rhs: Duration) -> NaiveDateTime

impl Add.add

Add an exact Duration.

NaiveDateTime.subtract Subtract<Years, NaiveDateTime>

Section titled “NaiveDateTime.subtract Subtract<Years, NaiveDateTime>”

impl Subtract<Years, NaiveDateTime> for NaiveDateTime

fn subtract(lhs: NaiveDateTime, Years(n)) -> NaiveDateTime

impl Subtract.subtract

Subtract whole calendar years, clamping leap days when needed.

NaiveDateTime.subtract Subtract<Months, NaiveDateTime>

Section titled “NaiveDateTime.subtract Subtract<Months, NaiveDateTime>”

impl Subtract<Months, NaiveDateTime> for NaiveDateTime

fn subtract(lhs: NaiveDateTime, Months(n)) -> NaiveDateTime

impl Subtract.subtract

Subtract whole calendar months, clamping end-of-month.

NaiveDateTime.subtract Subtract<Weeks, NaiveDateTime>

Section titled “NaiveDateTime.subtract Subtract<Weeks, NaiveDateTime>”

impl Subtract<Weeks, NaiveDateTime> for NaiveDateTime

fn subtract(lhs: NaiveDateTime, Weeks(n)) -> NaiveDateTime

impl Subtract.subtract

Subtract whole calendar weeks.

NaiveDateTime.subtract Subtract<Days, NaiveDateTime>

Section titled “NaiveDateTime.subtract Subtract<Days, NaiveDateTime>”

impl Subtract<Days, NaiveDateTime> for NaiveDateTime

fn subtract(lhs: NaiveDateTime, Days(n)) -> NaiveDateTime

impl Subtract.subtract

Subtract whole calendar days.

NaiveDateTime.subtract Subtract<Hours, NaiveDateTime>

Section titled “NaiveDateTime.subtract Subtract<Hours, NaiveDateTime>”

impl Subtract<Hours, NaiveDateTime> for NaiveDateTime

fn subtract(lhs: NaiveDateTime, Hours(n)) -> NaiveDateTime

impl Subtract.subtract

Subtract whole civil hours.

NaiveDateTime.subtract Subtract<Minutes, NaiveDateTime>

Section titled “NaiveDateTime.subtract Subtract<Minutes, NaiveDateTime>”

impl Subtract<Minutes, NaiveDateTime> for NaiveDateTime

fn subtract(lhs: NaiveDateTime, Minutes(n)) -> NaiveDateTime

impl Subtract.subtract

Subtract whole civil minutes.

NaiveDateTime.subtract Subtract<Seconds, NaiveDateTime>

Section titled “NaiveDateTime.subtract Subtract<Seconds, NaiveDateTime>”

impl Subtract<Seconds, NaiveDateTime> for NaiveDateTime

fn subtract(lhs: NaiveDateTime, Seconds(n)) -> NaiveDateTime

impl Subtract.subtract

Subtract whole civil seconds.

NaiveDateTime.subtract Subtract<Milliseconds, NaiveDateTime>

Section titled “NaiveDateTime.subtract Subtract<Milliseconds, NaiveDateTime>”

impl Subtract<Milliseconds, NaiveDateTime> for NaiveDateTime

fn subtract(lhs: NaiveDateTime, Milliseconds(n)) -> NaiveDateTime

impl Subtract.subtract

Subtract whole civil milliseconds.

NaiveDateTime.subtract Subtract<Microseconds, NaiveDateTime>

Section titled “NaiveDateTime.subtract Subtract<Microseconds, NaiveDateTime>”

impl Subtract<Microseconds, NaiveDateTime> for NaiveDateTime

fn subtract(lhs: NaiveDateTime, Microseconds(n)) -> NaiveDateTime

impl Subtract.subtract

Subtract whole civil microseconds.

NaiveDateTime.subtract Subtract<Nanoseconds, NaiveDateTime>

Section titled “NaiveDateTime.subtract Subtract<Nanoseconds, NaiveDateTime>”

impl Subtract<Nanoseconds, NaiveDateTime> for NaiveDateTime

fn subtract(lhs: NaiveDateTime, Nanoseconds(n)) -> NaiveDateTime

impl Subtract.subtract

Subtract whole civil nanoseconds.

NaiveDateTime.subtract Subtract<Duration, NaiveDateTime>

Section titled “NaiveDateTime.subtract Subtract<Duration, NaiveDateTime>”

impl Subtract<Duration, NaiveDateTime> for NaiveDateTime

fn subtract(lhs: NaiveDateTime, rhs: Duration) -> NaiveDateTime

impl Subtract.subtract

Subtract an exact Duration.

impl Localize for NaiveDateTime

fn localize(dt: NaiveDateTime, locale: Locale) -> String

impl Localize.localize

The date and time as NaiveDateTime.format writes them.

impl Equatable for NaiveDateTime

fn equal(a: NaiveDateTime, b: NaiveDateTime) -> Bool

impl Equatable.equal

impl Hashable for NaiveDateTime

fn hash(value: NaiveDateTime) -> Int

impl Hashable.hash

impl Comparable for NaiveDateTime

fn compare(a: NaiveDateTime, b: NaiveDateTime) -> Ordering

impl Comparable.compare

struct OffsetDateTime

opaque — construction surface is private to its defining module

A date and time at a fixed UTC offset (-05:00). It names a moment and follows no daylight-saving rules. It is the type for an ISO 8601 timestamp that carries an offset and no zone (2026-05-04T14:30:00-05:00). For a moment in a zone, use DateTime. An OffsetDateTime records no zone, so making a DateTime from one means naming the zone.

Equality and ordering compare the instant only: two values at one moment with different offsets are equal, and the offset decides how each displays. Build one with the OffsetDateTime"…" typed literal, OffsetDateTime.with_offset(naive, offset), OffsetDateTime.from_instant(instant, offset) or OffsetDateTime.parse.

odt = OffsetDateTime"2026-05-04T14:30:00-05:00"
assert Display.to_string(odt) == "2026-05-04T14:30:00-05:00"
assert odt == OffsetDateTime"2026-05-04T19:30:00Z"
fn with_offset(dt: NaiveDateTime, offset: Duration) -> Result<OffsetDateTime, Error>

type function on OffsetDateTime

The moment a clock at a fixed UTC offset showed the wall reading dt. Returns Err(.InvalidValue(...)) for an offset outside ±18 hours or one that is not a whole number of seconds.

assert OffsetDateTime.with_offset(NaiveDateTime"2026-05-04T09:00:00", Duration.hours(-5))?
    == OffsetDateTime"2026-05-04T09:00:00-05:00"

assert OffsetDateTime.with_offset(NaiveDateTime"2026-05-04T09:00:00", Duration.hours(19))
    == Err(Error.InvalidValue("offset out of range (±18h): 68400s"))
fn from_instant(i: Instant, offset: Duration) -> Result<OffsetDateTime, Error>

type function on OffsetDateTime

Attach a fixed offset to an absolute Instant, of any year. A sub-second offset is cut to whole seconds. Returns Err(.InvalidValue(...)) for an offset outside ±18 hours, as with_offset does.

assert OffsetDateTime.from_instant(Instant.from_seconds(0), Duration.hours(0))
    == Ok(OffsetDateTime"1970-01-01T00:00:00Z")

assert OffsetDateTime.from_instant(Instant.from_seconds(100_000_000_000), Duration.hours(0))
    == Ok(OffsetDateTime"5138-11-16T09:46:40Z")

assert OffsetDateTime.from_instant(Instant.from_seconds(Int.pow(10, 22)), Duration.hours(0))
    == Ok(OffsetDateTime"+316887385070084-04-22T17:46:40Z")

assert OffsetDateTime.from_instant(Instant.from_seconds(0), Duration.hours(19))
    == Err(Error.InvalidValue("offset out of range (±18h): 68400s"))
fn parse(s: String) -> Result<OffsetDateTime, Error>

type function on OffsetDateTime

Parse an ISO 8601 timestamp with an offset: YYYY-MM-DDTHH:MM:SS[.fff…] and then ±HH:MM or Z. The offset is required.

assert OffsetDateTime.parse("2026-05-04T14:30:00-05:00")?
    == OffsetDateTime"2026-05-04T14:30:00-05:00"

assert Err(Error.InvalidFormat(_msg)) = OffsetDateTime.parse("2026-05-04T14:30:00")
fn between(earlier: OffsetDateTime, later: OffsetDateTime) -> Duration

type function on OffsetDateTime

Exact duration from earlier to later, between their instants, whatever their offsets; negative when later is the earlier moment.

assert OffsetDateTime.between(
    OffsetDateTime"2026-05-04T14:30:00-05:00",
    OffsetDateTime"2026-05-04T20:30:00+00:00",
) == Duration.hours(1)
fn to_naive(odt: OffsetDateTime) -> NaiveDateTime

type function on OffsetDateTime

The wall reading at the value’s offset, with the offset dropped: the date and time its clock showed.

assert OffsetDateTime.to_naive(OffsetDateTime"2026-05-04T14:30:00-05:00")
    == NaiveDateTime"2026-05-04T14:30:00"

impl Literal for OffsetDateTime

fn from_fragments(fragments: List<Fragment<String>>) -> Result<OffsetDateTime, Error>

impl Literal.from_fragments

impl Display for OffsetDateTime

fn to_string(odt: OffsetDateTime) -> String

impl Display.to_string

ISO 8601 date and time with its offset (YYYY-MM-DDTHH:MM:SS[.fff…]±HH:MM). UTC is written +00:00.

impl Debug for OffsetDateTime

fn inspect(odt: OffsetDateTime) -> String

impl Debug.inspect

impl DateParts for OffsetDateTime

fn year(value: OffsetDateTime) -> Int

impl DateParts.year

impl DateParts for OffsetDateTime

fn month(value: OffsetDateTime) -> Int

impl DateParts.month

impl DateParts for OffsetDateTime

fn day(value: OffsetDateTime) -> Int

impl DateParts.day

impl TimeParts for OffsetDateTime

fn hour(value: OffsetDateTime) -> Int

impl TimeParts.hour

impl TimeParts for OffsetDateTime

fn minute(value: OffsetDateTime) -> Int

impl TimeParts.minute

impl TimeParts for OffsetDateTime

fn second(value: OffsetDateTime) -> Int

impl TimeParts.second

impl TimeParts for OffsetDateTime

fn nanosecond(value: OffsetDateTime) -> Int

impl TimeParts.nanosecond

impl Anchored for OffsetDateTime

fn to_instant(odt: OffsetDateTime) -> Instant

impl Anchored.to_instant

The moment the value names, with its offset dropped.

assert OffsetDateTime.to_instant(OffsetDateTime"1970-01-01T01:00:42+01:00")
    == Instant.from_seconds(42)

impl Anchored for OffsetDateTime

fn offset(odt: OffsetDateTime) -> Duration

impl Anchored.offset

The fixed UTC offset the value carries.

assert OffsetDateTime.offset(OffsetDateTime"2026-05-04T14:30:00-05:00") == Duration.hours(-5)

OffsetDateTime.add Add<Duration, OffsetDateTime>

Section titled “OffsetDateTime.add Add<Duration, OffsetDateTime>”

impl Add<Duration, OffsetDateTime> for OffsetDateTime

fn add(lhs: OffsetDateTime, rhs: Duration) -> OffsetDateTime

impl Add.add

Add an exact Duration, of any length.

OffsetDateTime.add Add<Years, OffsetDateTime>

Section titled “OffsetDateTime.add Add<Years, OffsetDateTime>”

impl Add<Years, OffsetDateTime> for OffsetDateTime

fn add(lhs: OffsetDateTime, Years(n)) -> OffsetDateTime

impl Add.add

Add whole calendar years, clamping leap days when needed.

OffsetDateTime.add Add<Months, OffsetDateTime>

Section titled “OffsetDateTime.add Add<Months, OffsetDateTime>”

impl Add<Months, OffsetDateTime> for OffsetDateTime

fn add(lhs: OffsetDateTime, Months(n)) -> OffsetDateTime

impl Add.add

Add whole calendar months, clamping end-of-month.

OffsetDateTime.add Add<Weeks, OffsetDateTime>

Section titled “OffsetDateTime.add Add<Weeks, OffsetDateTime>”

impl Add<Weeks, OffsetDateTime> for OffsetDateTime

fn add(lhs: OffsetDateTime, Weeks(n)) -> OffsetDateTime

impl Add.add

Add whole calendar weeks.

OffsetDateTime.add Add<Days, OffsetDateTime>

Section titled “OffsetDateTime.add Add<Days, OffsetDateTime>”

impl Add<Days, OffsetDateTime> for OffsetDateTime

fn add(lhs: OffsetDateTime, Days(n)) -> OffsetDateTime

impl Add.add

Add whole calendar days, each 24 hours at a fixed offset.

OffsetDateTime.add Add<Hours, OffsetDateTime>

Section titled “OffsetDateTime.add Add<Hours, OffsetDateTime>”

impl Add<Hours, OffsetDateTime> for OffsetDateTime

fn add(lhs: OffsetDateTime, Hours(n)) -> OffsetDateTime

impl Add.add

Add whole civil hours.

OffsetDateTime.add Add<Minutes, OffsetDateTime>

Section titled “OffsetDateTime.add Add<Minutes, OffsetDateTime>”

impl Add<Minutes, OffsetDateTime> for OffsetDateTime

fn add(lhs: OffsetDateTime, Minutes(n)) -> OffsetDateTime

impl Add.add

Add whole civil minutes.

OffsetDateTime.add Add<Seconds, OffsetDateTime>

Section titled “OffsetDateTime.add Add<Seconds, OffsetDateTime>”

impl Add<Seconds, OffsetDateTime> for OffsetDateTime

fn add(lhs: OffsetDateTime, Seconds(n)) -> OffsetDateTime

impl Add.add

Add whole civil seconds.

OffsetDateTime.add Add<Milliseconds, OffsetDateTime>

Section titled “OffsetDateTime.add Add<Milliseconds, OffsetDateTime>”

impl Add<Milliseconds, OffsetDateTime> for OffsetDateTime

fn add(lhs: OffsetDateTime, Milliseconds(n)) -> OffsetDateTime

impl Add.add

Add whole civil milliseconds.

OffsetDateTime.add Add<Microseconds, OffsetDateTime>

Section titled “OffsetDateTime.add Add<Microseconds, OffsetDateTime>”

impl Add<Microseconds, OffsetDateTime> for OffsetDateTime

fn add(lhs: OffsetDateTime, Microseconds(n)) -> OffsetDateTime

impl Add.add

Add whole civil microseconds.

OffsetDateTime.add Add<Nanoseconds, OffsetDateTime>

Section titled “OffsetDateTime.add Add<Nanoseconds, OffsetDateTime>”

impl Add<Nanoseconds, OffsetDateTime> for OffsetDateTime

fn add(lhs: OffsetDateTime, Nanoseconds(n)) -> OffsetDateTime

impl Add.add

Add whole civil nanoseconds.

OffsetDateTime.subtract Subtract<Duration, OffsetDateTime>

Section titled “OffsetDateTime.subtract Subtract<Duration, OffsetDateTime>”

impl Subtract<Duration, OffsetDateTime> for OffsetDateTime

fn subtract(lhs: OffsetDateTime, rhs: Duration) -> OffsetDateTime

impl Subtract.subtract

Subtract an exact Duration.

OffsetDateTime.subtract Subtract<Years, OffsetDateTime>

Section titled “OffsetDateTime.subtract Subtract<Years, OffsetDateTime>”

impl Subtract<Years, OffsetDateTime> for OffsetDateTime

fn subtract(lhs: OffsetDateTime, Years(n)) -> OffsetDateTime

impl Subtract.subtract

Subtract whole calendar years, clamping leap days when needed.

OffsetDateTime.subtract Subtract<Months, OffsetDateTime>

Section titled “OffsetDateTime.subtract Subtract<Months, OffsetDateTime>”

impl Subtract<Months, OffsetDateTime> for OffsetDateTime

fn subtract(lhs: OffsetDateTime, Months(n)) -> OffsetDateTime

impl Subtract.subtract

Subtract whole calendar months, clamping end-of-month.

OffsetDateTime.subtract Subtract<Weeks, OffsetDateTime>

Section titled “OffsetDateTime.subtract Subtract<Weeks, OffsetDateTime>”

impl Subtract<Weeks, OffsetDateTime> for OffsetDateTime

fn subtract(lhs: OffsetDateTime, Weeks(n)) -> OffsetDateTime

impl Subtract.subtract

Subtract whole calendar weeks.

OffsetDateTime.subtract Subtract<Days, OffsetDateTime>

Section titled “OffsetDateTime.subtract Subtract<Days, OffsetDateTime>”

impl Subtract<Days, OffsetDateTime> for OffsetDateTime

fn subtract(lhs: OffsetDateTime, Days(n)) -> OffsetDateTime

impl Subtract.subtract

Subtract whole calendar days.

OffsetDateTime.subtract Subtract<Hours, OffsetDateTime>

Section titled “OffsetDateTime.subtract Subtract<Hours, OffsetDateTime>”

impl Subtract<Hours, OffsetDateTime> for OffsetDateTime

fn subtract(lhs: OffsetDateTime, Hours(n)) -> OffsetDateTime

impl Subtract.subtract

Subtract whole civil hours.

OffsetDateTime.subtract Subtract<Minutes, OffsetDateTime>

Section titled “OffsetDateTime.subtract Subtract<Minutes, OffsetDateTime>”

impl Subtract<Minutes, OffsetDateTime> for OffsetDateTime

fn subtract(lhs: OffsetDateTime, Minutes(n)) -> OffsetDateTime

impl Subtract.subtract

Subtract whole civil minutes.

OffsetDateTime.subtract Subtract<Seconds, OffsetDateTime>

Section titled “OffsetDateTime.subtract Subtract<Seconds, OffsetDateTime>”

impl Subtract<Seconds, OffsetDateTime> for OffsetDateTime

fn subtract(lhs: OffsetDateTime, Seconds(n)) -> OffsetDateTime

impl Subtract.subtract

Subtract whole civil seconds.

OffsetDateTime.subtract Subtract<Milliseconds, OffsetDateTime>

Section titled “OffsetDateTime.subtract Subtract<Milliseconds, OffsetDateTime>”

impl Subtract<Milliseconds, OffsetDateTime> for OffsetDateTime

fn subtract(lhs: OffsetDateTime, Milliseconds(n)) -> OffsetDateTime

impl Subtract.subtract

Subtract whole civil milliseconds.

OffsetDateTime.subtract Subtract<Microseconds, OffsetDateTime>

Section titled “OffsetDateTime.subtract Subtract<Microseconds, OffsetDateTime>”

impl Subtract<Microseconds, OffsetDateTime> for OffsetDateTime

fn subtract(lhs: OffsetDateTime, Microseconds(n)) -> OffsetDateTime

impl Subtract.subtract

Subtract whole civil microseconds.

OffsetDateTime.subtract Subtract<Nanoseconds, OffsetDateTime>

Section titled “OffsetDateTime.subtract Subtract<Nanoseconds, OffsetDateTime>”

impl Subtract<Nanoseconds, OffsetDateTime> for OffsetDateTime

fn subtract(lhs: OffsetDateTime, Nanoseconds(n)) -> OffsetDateTime

impl Subtract.subtract

Subtract whole civil nanoseconds.

impl Equatable for OffsetDateTime

fn equal(a: OffsetDateTime, b: OffsetDateTime) -> Bool

impl Equatable.equal

impl Hashable for OffsetDateTime

fn hash(value: OffsetDateTime) -> Int

impl Hashable.hash

impl Comparable for OffsetDateTime

fn compare(a: OffsetDateTime, b: OffsetDateTime) -> Ordering

impl Comparable.compare

enum Disambiguation
    Compatible
    Earlier
    Later
    Reject
end

How DateTime.in_zone resolves a wall-clock reading that falls in a spring-forward gap (clocks jumped over it, so it never happens) or a fall-back fold (clocks rolled back, so it happens twice). The modes follow Temporal’s disambiguation option.

  • Compatible, the default, always returns an instant. In a fold it is the earlier one, before the transition. In a gap it moves the reading forward by the gap’s length, so 02:30 becomes 03:30 after the transition.
  • Earlier is the earlier instant in a fold, as Compatible’s is. In a gap it moves the reading back by the gap’s length, so 02:30 becomes 01:30 before the transition. Use it where earlier is safer, as for a deadline or a reminder.
  • Later is the later instant in a fold, after the transition. In a gap it is Compatible’s. Use it where later is safer, as for an expiration or a grace period.
  • Reject returns Err(Ambiguous ...) for a fold and Err(Nonexistent ...) for a gap. Use it when the reading came from a person (a form, an API request) who can be asked which they meant.

Civil shifts (+ Hours(...), + Months(...), …) always resolve with Compatible, so they are total.

gap = NaiveDateTime"2026-03-08T02:30:00"
fold = NaiveDateTime"2026-11-01T01:30:00"
zone = "America/New_York"
assert DateTime.in_zone(gap, zone)? == DateTime"2026-03-08T03:30:00-04:00[America/New_York]"

assert DateTime.in_zone(gap, zone, Disambiguation.Earlier)?
    == DateTime"2026-03-08T01:30:00-05:00[America/New_York]"

assert DateTime.in_zone(fold, zone)? == DateTime"2026-11-01T01:30:00-04:00[America/New_York]"

assert DateTime.in_zone(fold, zone, Disambiguation.Later)?
    == DateTime"2026-11-01T01:30:00-05:00[America/New_York]"

assert Err(Error.Nonexistent(_why)) = DateTime.in_zone(gap, zone, Disambiguation.Reject)
assert Err(Error.Ambiguous(_why)) = DateTime.in_zone(fold, zone, Disambiguation.Reject)

impl Debug for Disambiguation

fn inspect(value: Disambiguation) -> String

impl Debug.inspect

struct DateTime

opaque — construction surface is private to its defining module

A date and time in an IANA time zone (America/New_York), following the zone’s daylight-saving rules. It is the type for a moment, and the one to use for almost every timestamp a program handles. The zone database is embedded in the program, so a zone lookup works on every host.

Equality and ordering compare the instant only: one moment read in two zones is two equal values. The zone decides how each displays.

Build one with the DateTime"…" typed literal (RFC 9557’s bracket form), DateTime.in_zone(naive, zone, mode) (a wall reading in a zone; Disambiguation covers gaps and folds), DateTime.from_instant_in(instant, zone), DateTime.now_in(zone) or DateTime.parse. A function that takes a zone name returns Err(UnknownZone ...) for one the database lacks.

dt = DateTime"2026-06-15T12:00:00-04:00[America/New_York]"
assert Display.to_string(dt) == "2026-06-15T12:00:00-04:00[America/New_York]"
assert DateTime.hour(dt) == 12

paris = DateTime"2026-06-15T18:00:00+02:00[Europe/Paris]"
assert dt == paris
refute Display.to_string(dt) == Display.to_string(paris)
fn format(dt: DateTime, locale: Locale, date: DateStyle = DateStyle.Medium, time: TimeStyle = TimeStyle.Short) -> String

type function on DateTime

The moment as a reader of locale writes its wall clock, the date at the length date says and the time at time’s. A Long time ends with the zone’s offset in the locale’s short GMT format (GMT+2) and a Full one in its long format (GMT+02:00). std has no zone names.

dt = DateTime"2026-10-20T09:30:00+02:00[Europe/Warsaw]"
assert DateTime.format(dt, Locale"pl") == "20 paź 2026, 09:30"
assert DateTime.format(dt, Locale"en", time: .Full) == "Oct 20, 2026, 9:30:00\u{202f}AM GMT+02:00"

assert DateTime.format(dt, Locale"en", date: .Full, time: .Long)
    == "Tuesday, October 20, 2026, 9:30:00\u{202f}AM GMT+2"
fn format_fields(dt: DateTime, locale: Locale, fields: DateTimeFields) -> String

type function on DateTime

The moment as a reader of locale writes the fields fields names.

dt = DateTime"2026-10-20T09:30:00+02:00[Europe/Warsaw]"
assert DateTime.format_fields(dt, Locale"en", DateTimeFields"EEEEjm") == "Tuesday 9:30\u{202f}AM"
fn to_string_with(dt: DateTime, pattern: DateTimePattern) -> String

type function on DateTime

The moment’s wall clock by a fixed numeric pattern.

dt = DateTime"2026-10-20T09:30:00+02:00[Europe/Warsaw]"
assert DateTime.to_string_with(dt, DateTimePattern"yyyyMMdd'T'HHmmss") == "20261020T093000"
fn in_zone(dt: NaiveDateTime, zone: String, mode: Disambiguation = Disambiguation.Compatible) -> Result<DateTime, Error>

type function on DateTime

The moment the clocks of an IANA zone showed the wall reading dt. An unknown zone is Err(UnknownZone ...). A reading in a gap or a fold resolves as mode says (Disambiguation), and is an Err, Nonexistent or Ambiguous, only with Disambiguation.Reject.

assert DateTime.in_zone(NaiveDateTime"2026-06-15T12:00:00", "America/New_York")?
    == DateTime"2026-06-15T12:00:00-04:00[America/New_York]"

assert Err(Error.UnknownZone(_zone)) = DateTime.in_zone(
    NaiveDateTime"2026-06-15T12:00:00",
    "Mars/Base",
)
fn from_instant_in(i: Instant, zone: String) -> Result<DateTime, Error>

type function on DateTime

Project an absolute Instant, of any year, into an IANA zone. Fails only on an unknown zone, UnknownZone. Past the last transition a zone’s database lists, its offset follows the rule the database extends forever (New York’s daylight saving every summer); before the first, it is the zone’s first offset, its local mean time. Past about 292 billion years either way, where no rule reaches, the offset is the one at the nearer end.

assert DateTime.from_instant_in(Instant.from_seconds(0), "UTC")?
    == DateTime"1970-01-01T00:00:00Z[UTC]"

assert DateTime.from_instant_in(Instant.from_seconds(100_000_000_000), "America/New_York")?
    == DateTime"5138-11-16T04:46:40-05:00[America/New_York]"
fn now_in(zone: String) -> Result<DateTime, Error>

type function on DateTime

The current moment, read in a zone. The same as DateTime.from_instant_in(Instant.now(), zone).

assert Err(Error.UnknownZone(_zone)) = DateTime.now_in("Mars/Base")
fn to_offset(d: DateTime) -> OffsetDateTime

type function on DateTime

The same moment as an OffsetDateTime, at the offset the zone has at that moment. The result does not record the zone.

assert DateTime.to_offset(DateTime"2026-06-15T12:00:00-04:00[America/New_York]")
    == OffsetDateTime"2026-06-15T12:00:00-04:00"
fn to_naive(d: DateTime) -> NaiveDateTime

type function on DateTime

The wall reading in the value’s zone, with the zone dropped: the date and time its clock showed. A UTC reading of an Instant is NaiveDateTime.from_instant(i).

assert DateTime.to_naive(DateTime"2026-06-15T12:00:00-04:00[America/New_York]")
    == NaiveDateTime"2026-06-15T12:00:00"
fn with_zone(d: DateTime, zone: String) -> Result<DateTime, Error>

type function on DateTime

The same instant read in another IANA zone. Fails only on an unknown zone, UnknownZone.

assert DateTime.with_zone(DateTime"2026-06-15T12:00:00-04:00[America/New_York]", "Europe/Paris")?
    == DateTime"2026-06-15T18:00:00+02:00[Europe/Paris]"
fn zone(d: DateTime) -> String

type function on DateTime

The IANA zone the value reads its wall clock in, which its construction checked.

assert DateTime.zone(DateTime"2026-06-15T12:00:00-04:00[America/New_York]") == "America/New_York"
fn parse(s: String) -> Result<DateTime, Error>

type function on DateTime

Parse an RFC 9557 date and time with a zone (YYYY-MM-DDTHH:MM:SS[.fff…]±HH:MM[Zone/Name]). The offset and the bracketed zone are both required; text with an offset and no bracket reads with OffsetDateTime.parse. The offset names the instant and the zone reads it, so where the offset is not the zone’s at that moment the wall reading changes.

assert DateTime.parse("2026-06-15T12:00:00-04:00[America/New_York]")?
    == DateTime.in_zone(NaiveDateTime"2026-06-15T12:00:00", "America/New_York")?

winter_offset = DateTime.parse("2026-06-15T12:00:00-05:00[America/New_York]")?
assert Display.to_string(winter_offset) == "2026-06-15T13:00:00-04:00[America/New_York]"

assert Err(Error.InvalidFormat(_msg)) = DateTime.parse("2026-06-15T12:00:00-04:00")
fn between(earlier: DateTime, later: DateTime) -> Duration

type function on DateTime

Exact duration from earlier to later, between their instants, whatever their zones; negative when later is the earlier moment.

assert DateTime.between(
    DateTime"2026-06-15T12:00:00-04:00[America/New_York]",
    DateTime"2026-06-15T18:30:00+02:00[Europe/Paris]",
) == Duration.minutes(30)

impl Literal for DateTime

fn from_fragments(fragments: List<Fragment<String>>) -> Result<DateTime, Error>

impl Literal.from_fragments

impl Display for DateTime

fn to_string(d: DateTime) -> String

impl Display.to_string

RFC 9557 date and time with its offset and zone (2026-06-15T12:00:00-04:00[America/New_York]).

impl Debug for DateTime

fn inspect(d: DateTime) -> String

impl Debug.inspect

impl DateParts for DateTime

fn year(value: DateTime) -> Int

impl DateParts.year

impl DateParts for DateTime

fn month(value: DateTime) -> Int

impl DateParts.month

impl DateParts for DateTime

fn day(value: DateTime) -> Int

impl DateParts.day

impl TimeParts for DateTime

fn hour(value: DateTime) -> Int

impl TimeParts.hour

impl TimeParts for DateTime

fn minute(value: DateTime) -> Int

impl TimeParts.minute

impl TimeParts for DateTime

fn second(value: DateTime) -> Int

impl TimeParts.second

impl TimeParts for DateTime

fn nanosecond(value: DateTime) -> Int

impl TimeParts.nanosecond

impl Anchored for DateTime

fn to_instant(d: DateTime) -> Instant

impl Anchored.to_instant

The moment the value names, with its zone dropped.

assert DateTime.to_instant(DateTime"1970-01-01T00:00:42Z[UTC]") == Instant.from_seconds(42)

impl Anchored for DateTime

fn offset(d: DateTime) -> Duration

impl Anchored.offset

The zone’s UTC offset at this moment, which changes with the zone’s daylight saving.

assert DateTime.offset(DateTime"2026-06-15T12:00:00-04:00[America/New_York]") == Duration.hours(-4)
assert DateTime.offset(DateTime"2026-01-15T12:00:00-05:00[America/New_York]") == Duration.hours(-5)

impl Add<Duration, DateTime> for DateTime

fn add(lhs: DateTime, rhs: Duration) -> DateTime

impl Add.add

Add an exact Duration, of any length.

impl Add<Years, DateTime> for DateTime

fn add(lhs: DateTime, Years(n)) -> DateTime

impl Add.add

Add whole calendar years, clamping leap days when needed.

impl Add<Months, DateTime> for DateTime

fn add(lhs: DateTime, Months(n)) -> DateTime

impl Add.add

Add whole calendar months, clamping end-of-month.

impl Add<Weeks, DateTime> for DateTime

fn add(lhs: DateTime, Weeks(n)) -> DateTime

impl Add.add

Add whole calendar weeks.

impl Add<Days, DateTime> for DateTime

fn add(lhs: DateTime, Days(n)) -> DateTime

impl Add.add

Add whole calendar days.

impl Add<Hours, DateTime> for DateTime

fn add(lhs: DateTime, Hours(n)) -> DateTime

impl Add.add

Add whole civil hours.

impl Add<Minutes, DateTime> for DateTime

fn add(lhs: DateTime, Minutes(n)) -> DateTime

impl Add.add

Add whole civil minutes.

impl Add<Seconds, DateTime> for DateTime

fn add(lhs: DateTime, Seconds(n)) -> DateTime

impl Add.add

Add whole civil seconds.

impl Add<Milliseconds, DateTime> for DateTime

fn add(lhs: DateTime, Milliseconds(n)) -> DateTime

impl Add.add

Add whole civil milliseconds.

impl Add<Microseconds, DateTime> for DateTime

fn add(lhs: DateTime, Microseconds(n)) -> DateTime

impl Add.add

Add whole civil microseconds.

impl Add<Nanoseconds, DateTime> for DateTime

fn add(lhs: DateTime, Nanoseconds(n)) -> DateTime

impl Add.add

Add whole civil nanoseconds.

DateTime.subtract Subtract<Duration, DateTime>

Section titled “DateTime.subtract Subtract<Duration, DateTime>”

impl Subtract<Duration, DateTime> for DateTime

fn subtract(lhs: DateTime, rhs: Duration) -> DateTime

impl Subtract.subtract

Subtract an exact Duration.

DateTime.subtract Subtract<Years, DateTime>

Section titled “DateTime.subtract Subtract<Years, DateTime>”

impl Subtract<Years, DateTime> for DateTime

fn subtract(lhs: DateTime, Years(n)) -> DateTime

impl Subtract.subtract

Subtract whole calendar years, clamping leap days when needed.

DateTime.subtract Subtract<Months, DateTime>

Section titled “DateTime.subtract Subtract<Months, DateTime>”

impl Subtract<Months, DateTime> for DateTime

fn subtract(lhs: DateTime, Months(n)) -> DateTime

impl Subtract.subtract

Subtract whole calendar months, clamping end-of-month.

DateTime.subtract Subtract<Weeks, DateTime>

Section titled “DateTime.subtract Subtract<Weeks, DateTime>”

impl Subtract<Weeks, DateTime> for DateTime

fn subtract(lhs: DateTime, Weeks(n)) -> DateTime

impl Subtract.subtract

Subtract whole calendar weeks.

DateTime.subtract Subtract<Days, DateTime>

Section titled “DateTime.subtract Subtract<Days, DateTime>”

impl Subtract<Days, DateTime> for DateTime

fn subtract(lhs: DateTime, Days(n)) -> DateTime

impl Subtract.subtract

Subtract whole calendar days.

DateTime.subtract Subtract<Hours, DateTime>

Section titled “DateTime.subtract Subtract<Hours, DateTime>”

impl Subtract<Hours, DateTime> for DateTime

fn subtract(lhs: DateTime, Hours(n)) -> DateTime

impl Subtract.subtract

Subtract whole civil hours.

DateTime.subtract Subtract<Minutes, DateTime>

Section titled “DateTime.subtract Subtract<Minutes, DateTime>”

impl Subtract<Minutes, DateTime> for DateTime

fn subtract(lhs: DateTime, Minutes(n)) -> DateTime

impl Subtract.subtract

Subtract whole civil minutes.

DateTime.subtract Subtract<Seconds, DateTime>

Section titled “DateTime.subtract Subtract<Seconds, DateTime>”

impl Subtract<Seconds, DateTime> for DateTime

fn subtract(lhs: DateTime, Seconds(n)) -> DateTime

impl Subtract.subtract

Subtract whole civil seconds.

DateTime.subtract Subtract<Milliseconds, DateTime>

Section titled “DateTime.subtract Subtract<Milliseconds, DateTime>”

impl Subtract<Milliseconds, DateTime> for DateTime

fn subtract(lhs: DateTime, Milliseconds(n)) -> DateTime

impl Subtract.subtract

Subtract whole civil milliseconds.

DateTime.subtract Subtract<Microseconds, DateTime>

Section titled “DateTime.subtract Subtract<Microseconds, DateTime>”

impl Subtract<Microseconds, DateTime> for DateTime

fn subtract(lhs: DateTime, Microseconds(n)) -> DateTime

impl Subtract.subtract

Subtract whole civil microseconds.

DateTime.subtract Subtract<Nanoseconds, DateTime>

Section titled “DateTime.subtract Subtract<Nanoseconds, DateTime>”

impl Subtract<Nanoseconds, DateTime> for DateTime

fn subtract(lhs: DateTime, Nanoseconds(n)) -> DateTime

impl Subtract.subtract

Subtract whole civil nanoseconds.

impl Equatable for DateTime

fn equal(a: DateTime, b: DateTime) -> Bool

impl Equatable.equal

impl Hashable for DateTime

fn hash(value: DateTime) -> Int

impl Hashable.hash

impl Comparable for DateTime

fn compare(a: DateTime, b: DateTime) -> Ordering

impl Comparable.compare

impl Localize for DateTime

fn localize(dt: DateTime, locale: Locale) -> String

impl Localize.localize

The moment as DateTime.format writes it.

enum Weekday
    Monday
    Tuesday
    Wednesday
    Thursday
    Friday
    Saturday
    Sunday
end

A day of the week, Monday first, as ISO 8601 counts them. Display gives its English name, the same in every locale; a message selects by one with :nomi:weekday.

assert Display.to_string(Weekday.Tuesday) == "Tuesday"

impl Display for Weekday

fn to_string(day: Weekday) -> String

impl Display.to_string

impl Debug for Weekday

fn inspect(value: Weekday) -> String

impl Debug.inspect

impl Equatable for Weekday

fn equal(a: Weekday, b: Weekday) -> Bool

impl Equatable.equal

impl Hashable for Weekday

fn hash(value: Weekday) -> Int

impl Hashable.hash

enum DateStyle
    Full
    Long
    Medium
    Short
end

How much of a date Date.format writes, in each locale’s way: Full (Tuesday, October 20, 2026 in en), Long (October 20, 2026), Medium (Oct 20, 2026) and Short (10/20/26).

impl Debug for DateStyle

fn inspect(value: DateStyle) -> String

impl Debug.inspect

impl Equatable for DateStyle

fn equal(a: DateStyle, b: DateStyle) -> Bool

impl Equatable.equal

enum TimeStyle
    Full
    Long
    Medium
    Short
end

How much of a time of day Time.format writes, in each locale’s way: Short is hours and minutes, Medium adds the seconds, and Long and Full the zone’s offset, where the value has a zone.

impl Debug for TimeStyle

fn inspect(value: TimeStyle) -> String

impl Debug.inspect

impl Equatable for TimeStyle

fn equal(a: TimeStyle, b: TimeStyle) -> Bool

impl Equatable.equal

enum TimeUnit
    Second
    Minute
    Hour
    Day
    Week
    Month
    Quarter
    Year
end

A unit of civil time, which TimeUnit.format_relative counts in. A month and a year are not fixed lengths of time, so relative time takes a unit and a count, not a Duration.

fn format_relative(count: Int, locale: Locale, unit: TimeUnit, numeric: Bool = False) -> String

type function on TimeUnit

count units from now, as a reader of locale says it: in 3 days and 3 days ago in en, za 3 dni and 3 dni temu in pl, each count in the plural form the locale’s rules give it. Unless numeric: True, a count the locale has a word for is that word (yesterday, tomorrow, vorgestern).

assert TimeUnit.format_relative(3, Locale"en", TimeUnit.Day) == "in 3 days"
assert TimeUnit.format_relative(-1, Locale"en", TimeUnit.Day) == "yesterday"
assert TimeUnit.format_relative(0, Locale"en", TimeUnit.Day) == "today"
assert TimeUnit.format_relative(-1, Locale"en", TimeUnit.Day, numeric: True) == "1 day ago"
assert TimeUnit.format_relative(-3, Locale"de", TimeUnit.Day) == "vor 3 Tagen"
assert TimeUnit.format_relative(3, Locale"pl", TimeUnit.Week) == "za 3 tygodnie"
assert TimeUnit.format_relative(5, Locale"pl", TimeUnit.Week) == "za 5 tygodni"

impl Debug for TimeUnit

fn inspect(value: TimeUnit) -> String

impl Debug.inspect

impl Equatable for TimeUnit

fn equal(a: TimeUnit, b: TimeUnit) -> Bool

impl Equatable.equal

type DateFields String

opaque — construction surface is private to its defining module

The fields a date shows and how wide, as a CLDR skeleton: y the year, M the month (M its number, MMM its short name, MMMM its name), d the day, E the weekday (EEEE its name) and G the era. The locale decides the order, the punctuation and the words (Date.format_fields). A literal without slots is checked when the program is checked, and its patterns are worked out when the program is built.

assert DateFields.parse("yMMMd") == Ok(DateFields"yMMMd")
assert Err(Error.InvalidFormat(_why)) = DateFields.parse("yMMMdHH")
fn parse(text: String) -> Result<DateFields, Error>

type function on DateFields

The skeleton text names, or why it names none a date has.

impl Literal for DateFields

fn from_fragments(fragments: List<Fragment<String>>) -> Result<DateFields, Error>

impl Literal.from_fragments

impl Debug for DateFields

fn inspect(fields: DateFields) -> String

impl Debug.inspect

impl Equatable for DateFields

fn equal(a: DateFields, b: DateFields) -> Bool

impl Equatable.equal

type TimeFields String

opaque — construction surface is private to its defining module

The fields a time of day shows, as a CLDR skeleton: j the hour as the locale writes it (a 12-hour clock with AM and PM, or a 24-hour one), h a 12-hour clock’s and H a 24-hour one’s, m the minutes, s the seconds and S their fraction.

assert TimeFields.parse("jm") == Ok(TimeFields"jm")
fn parse(text: String) -> Result<TimeFields, Error>

type function on TimeFields

The skeleton text names, or why it names none a time has.

impl Literal for TimeFields

fn from_fragments(fragments: List<Fragment<String>>) -> Result<TimeFields, Error>

impl Literal.from_fragments

impl Debug for TimeFields

fn inspect(fields: TimeFields) -> String

impl Debug.inspect

impl Equatable for TimeFields

fn equal(a: TimeFields, b: TimeFields) -> Bool

impl Equatable.equal

type DateTimeFields String

opaque — construction surface is private to its defining module

The fields a date and time show, as a CLDR skeleton of DateFields’ letters and TimeFields’.

assert DateTimeFields.parse("yMMMdjm") == Ok(DateTimeFields"yMMMdjm")
fn parse(text: String) -> Result<DateTimeFields, Error>

type function on DateTimeFields

The skeleton text names, or why it names none.

impl Literal for DateTimeFields

fn from_fragments(fragments: List<Fragment<String>>) -> Result<DateTimeFields, Error>

impl Literal.from_fragments

impl Debug for DateTimeFields

fn inspect(fields: DateTimeFields) -> String

impl Debug.inspect

impl Equatable for DateTimeFields

fn equal(a: DateTimeFields, b: DateTimeFields) -> Bool

impl Equatable.equal

type DatePattern String

opaque — construction surface is private to its defining module

A fixed numeric pattern for a date, the same text in every locale: y the year (yyyy four digits, yy two), M the month and d the day (doubled for two digits), D the day of the year, with anything else, or text in single quotes, written as it is. A month’s or a weekday’s name is a word of a language, so a pattern holds none: MMM is a compile error that points to Date.format_fields.

assert DatePattern.parse("yyyy-MM-dd") == Ok(DatePattern"yyyy-MM-dd")
assert Err(Error.InvalidFormat(_why)) = DatePattern.parse("dd MMM yyyy")
fn parse(text: String) -> Result<DatePattern, Error>

type function on DatePattern

The pattern text is, or why it is not a fixed date pattern.

impl Literal for DatePattern

fn from_fragments(fragments: List<Fragment<String>>) -> Result<DatePattern, Error>

impl Literal.from_fragments

impl Debug for DatePattern

fn inspect(pattern: DatePattern) -> String

impl Debug.inspect

impl Equatable for DatePattern

fn equal(a: DatePattern, b: DatePattern) -> Bool

impl Equatable.equal

type TimePattern String

opaque — construction surface is private to its defining module

A fixed numeric pattern for a time of day: H the hour of a 24-hour clock, m the minutes, s the seconds (each doubled for two digits) and S the fraction of a second, one letter per digit. A 12-hour clock needs AM or PM, a word, so a pattern has none.

assert TimePattern.parse("HH:mm") == Ok(TimePattern"HH:mm")
fn parse(text: String) -> Result<TimePattern, Error>

type function on TimePattern

The pattern text is, or why it is not a fixed time pattern.

impl Literal for TimePattern

fn from_fragments(fragments: List<Fragment<String>>) -> Result<TimePattern, Error>

impl Literal.from_fragments

impl Debug for TimePattern

fn inspect(pattern: TimePattern) -> String

impl Debug.inspect

impl Equatable for TimePattern

fn equal(a: TimePattern, b: TimePattern) -> Bool

impl Equatable.equal

type DateTimePattern String

opaque — construction surface is private to its defining module

A fixed numeric pattern for a date and time, of DatePattern’s letters and TimePattern’s.

assert DateTimePattern.parse("yyyyMMdd'T'HHmmss") == Ok(DateTimePattern"yyyyMMdd'T'HHmmss")
fn parse(text: String) -> Result<DateTimePattern, Error>

type function on DateTimePattern

The pattern text is, or why it is not a fixed date and time pattern.

impl Literal for DateTimePattern

fn from_fragments(fragments: List<Fragment<String>>) -> Result<DateTimePattern, Error>

impl Literal.from_fragments

impl Debug for DateTimePattern

fn inspect(pattern: DateTimePattern) -> String

impl Debug.inspect

impl Equatable for DateTimePattern

fn equal(a: DateTimePattern, b: DateTimePattern) -> Bool

impl Equatable.equal