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.
Exports
Section titled “Exports”Types
Interfaces
The type ladder
Section titled “The type ladder”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 + DurationandInstant - Durationare Instants;a - bon two Instants is theDurationfrombtoa(Instant.between(b, a)).Duration(std::duration): exact elapsed time, a count of nanoseconds. Build one with a unit function such asDuration.seconds(5), or with a literal asDisplaywrites 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.
Construction and typed literals
Section titled “Construction and typed literals”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).
Years of any size
Section titled “Years of any size”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: Duration and civil periods
Section titled “Arithmetic: Duration and civil periods”Arithmetic has two intents, and they differ because + Hours(24) is not
always + Duration.hours(24) around a DST transition.
value + Durationandvalue - Durationare 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 implementsAddandSubtractwithDurationas the right-hand operand and itself as the result (impl Add<Duration, DateTime> for DateTime).value + Years(...)andMonths,Weeks,Days,Hours,Minutes,Seconds,Milliseconds,MicrosecondsandNanoseconds(and-of each) are civil period arithmetic. They adjust the wall reading and, for a zonedDateTime, resolve it through the zone again. Months and years clamp to the end of the month (Date"2026-01-31" + Months(1)isDate"2026-02-28"). ADatetakes years, months, weeks and days; the date-time types take all ten; aTimetakes only aDuration, 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.
DST: gaps, folds and Disambiguation
Section titled “DST: gaps, folds and Disambiguation”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:30in 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:30in 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:
| Mode | In a fold | In a gap |
|---|---|---|
Compatible (default) | Earlier instant (pre-transition) | Post-transition instant |
Earlier | Earlier instant | Pre-transition instant |
Later | Later instant | Post-transition instant |
Reject | Err(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.
The conversion lattice
Section titled “The conversion lattice” 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:
OffsetDateTimetoDateTime. A fixed offset does not determine an IANA zone: offset-05:00is in effect in many zones at various points in history. The caller names the zone:OffsetDateTime.to_instant, thenDateTime.from_instant_in(instant, zone).DateorTimetoInstant. A calendar day or a time of day is not a moment.NaiveDateTime.of(date, time)makes aNaiveDateTime, andin_zonecarries it the rest of the way.
Equality and ordering
Section titled “Equality and ordering”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.
Text for a reader
Section titled “Text for a reader”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).
Embedded IANA tzdata
Section titled “Embedded IANA tzdata”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
Section titled “enum Error”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"
Error.to_string
Section titled “Error.to_string”impl Display for Error
fn to_string(e: Error) -> String
impl Display.to_string
Error.inspect
Section titled “Error.inspect”impl Debug for Error
fn inspect(value: Error) -> String
impl Debug.inspect
Error.equal
Section titled “Error.equal”impl Equatable for Error
fn equal(a: Error, b: Error) -> Bool
impl Equatable.equal
type Years
Section titled “type Years”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"
Years.inspect
Section titled “Years.inspect”impl Debug for Years
fn inspect(value: Years) -> String
impl Debug.inspect
Years.equal
Section titled “Years.equal”impl Equatable for Years
fn equal(a: Years, b: Years) -> Bool
impl Equatable.equal
Years.hash
Section titled “Years.hash”impl Hashable for Years
fn hash(value: Years) -> Int
impl Hashable.hash
Years.compare
Section titled “Years.compare”impl Comparable for Years
fn compare(a: Years, b: Years) -> Ordering
impl Comparable.compare
Years.to_string
Section titled “Years.to_string”impl Display for Years
fn to_string(value: Years) -> String
impl Display.to_string
type Months
Section titled “type Months”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"
Months.inspect
Section titled “Months.inspect”impl Debug for Months
fn inspect(value: Months) -> String
impl Debug.inspect
Months.equal
Section titled “Months.equal”impl Equatable for Months
fn equal(a: Months, b: Months) -> Bool
impl Equatable.equal
Months.hash
Section titled “Months.hash”impl Hashable for Months
fn hash(value: Months) -> Int
impl Hashable.hash
Months.compare
Section titled “Months.compare”impl Comparable for Months
fn compare(a: Months, b: Months) -> Ordering
impl Comparable.compare
Months.to_string
Section titled “Months.to_string”impl Display for Months
fn to_string(value: Months) -> String
impl Display.to_string
type Weeks
Section titled “type Weeks”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"
Weeks.inspect
Section titled “Weeks.inspect”impl Debug for Weeks
fn inspect(value: Weeks) -> String
impl Debug.inspect
Weeks.equal
Section titled “Weeks.equal”impl Equatable for Weeks
fn equal(a: Weeks, b: Weeks) -> Bool
impl Equatable.equal
Weeks.hash
Section titled “Weeks.hash”impl Hashable for Weeks
fn hash(value: Weeks) -> Int
impl Hashable.hash
Weeks.compare
Section titled “Weeks.compare”impl Comparable for Weeks
fn compare(a: Weeks, b: Weeks) -> Ordering
impl Comparable.compare
Weeks.to_string
Section titled “Weeks.to_string”impl Display for Weeks
fn to_string(value: Weeks) -> String
impl Display.to_string
type Days
Section titled “type Days”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]"
Days.inspect
Section titled “Days.inspect”impl Debug for Days
fn inspect(value: Days) -> String
impl Debug.inspect
Days.equal
Section titled “Days.equal”impl Equatable for Days
fn equal(a: Days, b: Days) -> Bool
impl Equatable.equal
Days.hash
Section titled “Days.hash”impl Hashable for Days
fn hash(value: Days) -> Int
impl Hashable.hash
Days.compare
Section titled “Days.compare”impl Comparable for Days
fn compare(a: Days, b: Days) -> Ordering
impl Comparable.compare
Days.to_string
Section titled “Days.to_string”impl Display for Days
fn to_string(value: Days) -> String
impl Display.to_string
type Hours
Section titled “type Hours”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]"
Hours.inspect
Section titled “Hours.inspect”impl Debug for Hours
fn inspect(value: Hours) -> String
impl Debug.inspect
Hours.equal
Section titled “Hours.equal”impl Equatable for Hours
fn equal(a: Hours, b: Hours) -> Bool
impl Equatable.equal
Hours.hash
Section titled “Hours.hash”impl Hashable for Hours
fn hash(value: Hours) -> Int
impl Hashable.hash
Hours.compare
Section titled “Hours.compare”impl Comparable for Hours
fn compare(a: Hours, b: Hours) -> Ordering
impl Comparable.compare
Hours.to_string
Section titled “Hours.to_string”impl Display for Hours
fn to_string(value: Hours) -> String
impl Display.to_string
type Minutes
Section titled “type Minutes”type Minutes Int
Whole civil minutes for date-time wall-clock arithmetic.
Minutes.inspect
Section titled “Minutes.inspect”impl Debug for Minutes
fn inspect(value: Minutes) -> String
impl Debug.inspect
Minutes.equal
Section titled “Minutes.equal”impl Equatable for Minutes
fn equal(a: Minutes, b: Minutes) -> Bool
impl Equatable.equal
Minutes.hash
Section titled “Minutes.hash”impl Hashable for Minutes
fn hash(value: Minutes) -> Int
impl Hashable.hash
Minutes.compare
Section titled “Minutes.compare”impl Comparable for Minutes
fn compare(a: Minutes, b: Minutes) -> Ordering
impl Comparable.compare
Minutes.to_string
Section titled “Minutes.to_string”impl Display for Minutes
fn to_string(value: Minutes) -> String
impl Display.to_string
type Seconds
Section titled “type Seconds”type Seconds Int
Whole civil seconds for date-time wall-clock arithmetic.
Seconds.inspect
Section titled “Seconds.inspect”impl Debug for Seconds
fn inspect(value: Seconds) -> String
impl Debug.inspect
Seconds.equal
Section titled “Seconds.equal”impl Equatable for Seconds
fn equal(a: Seconds, b: Seconds) -> Bool
impl Equatable.equal
Seconds.hash
Section titled “Seconds.hash”impl Hashable for Seconds
fn hash(value: Seconds) -> Int
impl Hashable.hash
Seconds.compare
Section titled “Seconds.compare”impl Comparable for Seconds
fn compare(a: Seconds, b: Seconds) -> Ordering
impl Comparable.compare
Seconds.to_string
Section titled “Seconds.to_string”impl Display for Seconds
fn to_string(value: Seconds) -> String
impl Display.to_string
type Milliseconds
Section titled “type Milliseconds”type Milliseconds Int
Whole civil milliseconds for date-time wall-clock arithmetic.
Milliseconds.inspect
Section titled “Milliseconds.inspect”impl Debug for Milliseconds
fn inspect(value: Milliseconds) -> String
impl Debug.inspect
Milliseconds.equal
Section titled “Milliseconds.equal”impl Equatable for Milliseconds
fn equal(a: Milliseconds, b: Milliseconds) -> Bool
impl Equatable.equal
Milliseconds.hash
Section titled “Milliseconds.hash”impl Hashable for Milliseconds
fn hash(value: Milliseconds) -> Int
impl Hashable.hash
Milliseconds.compare
Section titled “Milliseconds.compare”impl Comparable for Milliseconds
fn compare(a: Milliseconds, b: Milliseconds) -> Ordering
impl Comparable.compare
Milliseconds.to_string
Section titled “Milliseconds.to_string”impl Display for Milliseconds
fn to_string(value: Milliseconds) -> String
impl Display.to_string
type Microseconds
Section titled “type Microseconds”type Microseconds Int
Whole civil microseconds for date-time wall-clock arithmetic.
Microseconds.inspect
Section titled “Microseconds.inspect”impl Debug for Microseconds
fn inspect(value: Microseconds) -> String
impl Debug.inspect
Microseconds.equal
Section titled “Microseconds.equal”impl Equatable for Microseconds
fn equal(a: Microseconds, b: Microseconds) -> Bool
impl Equatable.equal
Microseconds.hash
Section titled “Microseconds.hash”impl Hashable for Microseconds
fn hash(value: Microseconds) -> Int
impl Hashable.hash
Microseconds.compare
Section titled “Microseconds.compare”impl Comparable for Microseconds
fn compare(a: Microseconds, b: Microseconds) -> Ordering
impl Comparable.compare
Microseconds.to_string
Section titled “Microseconds.to_string”impl Display for Microseconds
fn to_string(value: Microseconds) -> String
impl Display.to_string
type Nanoseconds
Section titled “type Nanoseconds”type Nanoseconds Int
Whole civil nanoseconds for date-time wall-clock arithmetic.
Nanoseconds.inspect
Section titled “Nanoseconds.inspect”impl Debug for Nanoseconds
fn inspect(value: Nanoseconds) -> String
impl Debug.inspect
Nanoseconds.equal
Section titled “Nanoseconds.equal”impl Equatable for Nanoseconds
fn equal(a: Nanoseconds, b: Nanoseconds) -> Bool
impl Equatable.equal
Nanoseconds.hash
Section titled “Nanoseconds.hash”impl Hashable for Nanoseconds
fn hash(value: Nanoseconds) -> Int
impl Hashable.hash
Nanoseconds.compare
Section titled “Nanoseconds.compare”impl Comparable for Nanoseconds
fn compare(a: Nanoseconds, b: Nanoseconds) -> Ordering
impl Comparable.compare
Nanoseconds.to_string
Section titled “Nanoseconds.to_string”impl Display for Nanoseconds
fn to_string(value: Nanoseconds) -> String
impl Display.to_string
interface DateParts
Section titled “interface DateParts”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.
DateParts.year
Section titled “DateParts.year”fn year(value: self) -> Int
interface DateParts
DateParts.month
Section titled “DateParts.month”fn month(value: self) -> Int
interface DateParts
DateParts.day
Section titled “DateParts.day”fn day(value: self) -> Int
interface DateParts
interface TimeParts
Section titled “interface TimeParts”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.
TimeParts.hour
Section titled “TimeParts.hour”fn hour(value: self) -> Int
interface TimeParts
TimeParts.minute
Section titled “TimeParts.minute”fn minute(value: self) -> Int
interface TimeParts
TimeParts.second
Section titled “TimeParts.second”fn second(value: self) -> Int
interface TimeParts
TimeParts.nanosecond
Section titled “TimeParts.nanosecond”fn nanosecond(value: self) -> Int
interface TimeParts
interface Anchored
Section titled “interface Anchored”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.
Anchored.to_instant
Section titled “Anchored.to_instant”fn to_instant(value: self) -> Instant
interface Anchored
Anchored.offset
Section titled “Anchored.offset”fn offset(value: self) -> Duration
interface Anchored
struct Date
Section titled “struct Date”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"
Date.new
Section titled “Date.new”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"
Date.parse
Section titled “Date.parse”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"
Date.days_between
Section titled “Date.days_between”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
Date.weekday
Section titled “Date.weekday”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
Date.is_leap_year
Section titled “Date.is_leap_year”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)
Date.days_in_month
Section titled “Date.days_in_month”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"))
Date.format
Section titled “Date.format”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日"
Date.format_fields
Section titled “Date.format_fields”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日火曜日"
Date.parse_in
Section titled “Date.parse_in”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"))
Date.to_string_with
Section titled “Date.to_string_with”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"
Date.parse_with
Section titled “Date.parse_with”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")
Date.from_fragments
Section titled “Date.from_fragments”impl Literal for Date
fn from_fragments(fragments: List<Fragment<String>>) -> Result<Date, Error>
Date.to_string
Section titled “Date.to_string”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.
Date.inspect
Section titled “Date.inspect”impl Debug for Date
fn inspect(d: Date) -> String
impl Debug.inspect
Date.year
Section titled “Date.year”impl DateParts for Date
fn year(value: Date) -> Int
impl DateParts.year
Date.month
Section titled “Date.month”impl DateParts for Date
fn month(value: Date) -> Int
impl DateParts.month
Date.day
Section titled “Date.day”impl DateParts for Date
fn day(value: Date) -> Int
impl DateParts.day
Date.add Add<Years, Date>
Section titled “Date.add Add<Years, Date>”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.
Date.add Add<Months, Date>
Section titled “Date.add Add<Months, Date>”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"
Date.add Add<Weeks, Date>
Section titled “Date.add Add<Weeks, Date>”impl Add<Weeks, Date> for Date
fn add(lhs: Date, Weeks(n)) -> Date
impl Add.add
Add whole calendar weeks.
Date.add Add<Days, Date>
Section titled “Date.add Add<Days, Date>”impl Add<Days, Date> for Date
fn add(lhs: Date, Days(n)) -> Date
impl Add.add
Add whole calendar days.
Date.subtract Subtract<Years, Date>
Section titled “Date.subtract Subtract<Years, Date>”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.
Date.subtract Subtract<Months, Date>
Section titled “Date.subtract Subtract<Months, Date>”impl Subtract<Months, Date> for Date
fn subtract(lhs: Date, Months(n)) -> Date
impl Subtract.subtract
Subtract whole calendar months, clamping end-of-month.
Date.subtract Subtract<Weeks, Date>
Section titled “Date.subtract Subtract<Weeks, Date>”impl Subtract<Weeks, Date> for Date
fn subtract(lhs: Date, Weeks(n)) -> Date
impl Subtract.subtract
Subtract whole calendar weeks.
Date.subtract Subtract<Days, Date>
Section titled “Date.subtract Subtract<Days, Date>”impl Subtract<Days, Date> for Date
fn subtract(lhs: Date, Days(n)) -> Date
impl Subtract.subtract
Subtract whole calendar days.
Date.localize
Section titled “Date.localize”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"
Date.equal
Section titled “Date.equal”impl Equatable for Date
fn equal(a: Date, b: Date) -> Bool
impl Equatable.equal
Date.hash
Section titled “Date.hash”impl Hashable for Date
fn hash(value: Date) -> Int
impl Hashable.hash
Date.compare
Section titled “Date.compare”impl Comparable for Date
fn compare(a: Date, b: Date) -> Ordering
impl Comparable.compare
struct Time
Section titled “struct Time”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
Time.new
Section titled “Time.new”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)
Time.parse
Section titled “Time.parse”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")
Time.between
Section titled “Time.between”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)
Time.format
Section titled “Time.format”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"
Time.format_fields
Section titled “Time.format_fields”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"
Time.parse_in
Section titled “Time.parse_in”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")
Time.to_string_with
Section titled “Time.to_string_with”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"
Time.parse_with
Section titled “Time.parse_with”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")
Time.from_fragments
Section titled “Time.from_fragments”impl Literal for Time
fn from_fragments(fragments: List<Fragment<String>>) -> Result<Time, Error>
Time.to_string
Section titled “Time.to_string”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.
Time.inspect
Section titled “Time.inspect”impl Debug for Time
fn inspect(t: Time) -> String
impl Debug.inspect
Time.hour
Section titled “Time.hour”impl TimeParts for Time
fn hour(value: Time) -> Int
impl TimeParts.hour
Time.minute
Section titled “Time.minute”impl TimeParts for Time
fn minute(value: Time) -> Int
impl TimeParts.minute
Time.second
Section titled “Time.second”impl TimeParts for Time
fn second(value: Time) -> Int
impl TimeParts.second
Time.nanosecond
Section titled “Time.nanosecond”impl TimeParts for Time
fn nanosecond(value: Time) -> Int
impl TimeParts.nanosecond
Time.add
Section titled “Time.add”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"
Time.subtract
Section titled “Time.subtract”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"
Time.localize
Section titled “Time.localize”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"
Time.equal
Section titled “Time.equal”impl Equatable for Time
fn equal(a: Time, b: Time) -> Bool
impl Equatable.equal
Time.hash
Section titled “Time.hash”impl Hashable for Time
fn hash(value: Time) -> Int
impl Hashable.hash
Time.compare
Section titled “Time.compare”impl Comparable for Time
fn compare(a: Time, b: Time) -> Ordering
impl Comparable.compare
struct NaiveDateTime
Section titled “struct NaiveDateTime”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"
NaiveDateTime.format
Section titled “NaiveDateTime.format”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"
NaiveDateTime.format_fields
Section titled “NaiveDateTime.format_fields”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"
NaiveDateTime.to_string_with
Section titled “NaiveDateTime.to_string_with”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"
NaiveDateTime.parse_with
Section titled “NaiveDateTime.parse_with”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")
NaiveDateTime.of
Section titled “NaiveDateTime.of”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"
NaiveDateTime.at_midnight
Section titled “NaiveDateTime.at_midnight”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"
NaiveDateTime.to_date
Section titled “NaiveDateTime.to_date”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"
NaiveDateTime.to_time
Section titled “NaiveDateTime.to_time”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"
NaiveDateTime.new
Section titled “NaiveDateTime.new”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)
NaiveDateTime.parse
Section titled “NaiveDateTime.parse”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"
NaiveDateTime.between
Section titled “NaiveDateTime.between”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)
NaiveDateTime.from_instant
Section titled “NaiveDateTime.from_instant”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"
NaiveDateTime.utc_now
Section titled “NaiveDateTime.utc_now”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)
NaiveDateTime.to_instant
Section titled “NaiveDateTime.to_instant”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
NaiveDateTime.from_fragments
Section titled “NaiveDateTime.from_fragments”impl Literal for NaiveDateTime
fn from_fragments(fragments: List<Fragment<String>>) -> Result<NaiveDateTime, Error>
NaiveDateTime.to_string
Section titled “NaiveDateTime.to_string”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…]).
NaiveDateTime.inspect
Section titled “NaiveDateTime.inspect”impl Debug for NaiveDateTime
fn inspect(dt: NaiveDateTime) -> String
impl Debug.inspect
NaiveDateTime.year
Section titled “NaiveDateTime.year”impl DateParts for NaiveDateTime
fn year(value: NaiveDateTime) -> Int
impl DateParts.year
NaiveDateTime.month
Section titled “NaiveDateTime.month”impl DateParts for NaiveDateTime
fn month(value: NaiveDateTime) -> Int
impl DateParts.month
NaiveDateTime.day
Section titled “NaiveDateTime.day”impl DateParts for NaiveDateTime
fn day(value: NaiveDateTime) -> Int
impl DateParts.day
NaiveDateTime.hour
Section titled “NaiveDateTime.hour”impl TimeParts for NaiveDateTime
fn hour(value: NaiveDateTime) -> Int
impl TimeParts.hour
NaiveDateTime.minute
Section titled “NaiveDateTime.minute”impl TimeParts for NaiveDateTime
fn minute(value: NaiveDateTime) -> Int
impl TimeParts.minute
NaiveDateTime.second
Section titled “NaiveDateTime.second”impl TimeParts for NaiveDateTime
fn second(value: NaiveDateTime) -> Int
impl TimeParts.second
NaiveDateTime.nanosecond
Section titled “NaiveDateTime.nanosecond”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.
NaiveDateTime.localize
Section titled “NaiveDateTime.localize”impl Localize for NaiveDateTime
fn localize(dt: NaiveDateTime, locale: Locale) -> String
impl Localize.localize
The date and time as NaiveDateTime.format writes them.
NaiveDateTime.equal
Section titled “NaiveDateTime.equal”impl Equatable for NaiveDateTime
fn equal(a: NaiveDateTime, b: NaiveDateTime) -> Bool
impl Equatable.equal
NaiveDateTime.hash
Section titled “NaiveDateTime.hash”impl Hashable for NaiveDateTime
fn hash(value: NaiveDateTime) -> Int
impl Hashable.hash
NaiveDateTime.compare
Section titled “NaiveDateTime.compare”impl Comparable for NaiveDateTime
fn compare(a: NaiveDateTime, b: NaiveDateTime) -> Ordering
impl Comparable.compare
struct OffsetDateTime
Section titled “struct OffsetDateTime”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"
OffsetDateTime.with_offset
Section titled “OffsetDateTime.with_offset”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"))
OffsetDateTime.from_instant
Section titled “OffsetDateTime.from_instant”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"))
OffsetDateTime.parse
Section titled “OffsetDateTime.parse”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")
OffsetDateTime.between
Section titled “OffsetDateTime.between”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)
OffsetDateTime.to_naive
Section titled “OffsetDateTime.to_naive”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"
OffsetDateTime.from_fragments
Section titled “OffsetDateTime.from_fragments”impl Literal for OffsetDateTime
fn from_fragments(fragments: List<Fragment<String>>) -> Result<OffsetDateTime, Error>
OffsetDateTime.to_string
Section titled “OffsetDateTime.to_string”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.
OffsetDateTime.inspect
Section titled “OffsetDateTime.inspect”impl Debug for OffsetDateTime
fn inspect(odt: OffsetDateTime) -> String
impl Debug.inspect
OffsetDateTime.year
Section titled “OffsetDateTime.year”impl DateParts for OffsetDateTime
fn year(value: OffsetDateTime) -> Int
impl DateParts.year
OffsetDateTime.month
Section titled “OffsetDateTime.month”impl DateParts for OffsetDateTime
fn month(value: OffsetDateTime) -> Int
impl DateParts.month
OffsetDateTime.day
Section titled “OffsetDateTime.day”impl DateParts for OffsetDateTime
fn day(value: OffsetDateTime) -> Int
impl DateParts.day
OffsetDateTime.hour
Section titled “OffsetDateTime.hour”impl TimeParts for OffsetDateTime
fn hour(value: OffsetDateTime) -> Int
impl TimeParts.hour
OffsetDateTime.minute
Section titled “OffsetDateTime.minute”impl TimeParts for OffsetDateTime
fn minute(value: OffsetDateTime) -> Int
impl TimeParts.minute
OffsetDateTime.second
Section titled “OffsetDateTime.second”impl TimeParts for OffsetDateTime
fn second(value: OffsetDateTime) -> Int
impl TimeParts.second
OffsetDateTime.nanosecond
Section titled “OffsetDateTime.nanosecond”impl TimeParts for OffsetDateTime
fn nanosecond(value: OffsetDateTime) -> Int
impl TimeParts.nanosecond
OffsetDateTime.to_instant
Section titled “OffsetDateTime.to_instant”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)
OffsetDateTime.offset
Section titled “OffsetDateTime.offset”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.
OffsetDateTime.equal
Section titled “OffsetDateTime.equal”impl Equatable for OffsetDateTime
fn equal(a: OffsetDateTime, b: OffsetDateTime) -> Bool
impl Equatable.equal
OffsetDateTime.hash
Section titled “OffsetDateTime.hash”impl Hashable for OffsetDateTime
fn hash(value: OffsetDateTime) -> Int
impl Hashable.hash
OffsetDateTime.compare
Section titled “OffsetDateTime.compare”impl Comparable for OffsetDateTime
fn compare(a: OffsetDateTime, b: OffsetDateTime) -> Ordering
impl Comparable.compare
enum Disambiguation
Section titled “enum Disambiguation”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, so02:30becomes03:30after the transition.Earlieris the earlier instant in a fold, asCompatible’s is. In a gap it moves the reading back by the gap’s length, so02:30becomes01:30before the transition. Use it where earlier is safer, as for a deadline or a reminder.Lateris the later instant in a fold, after the transition. In a gap it isCompatible’s. Use it where later is safer, as for an expiration or a grace period.RejectreturnsErr(Ambiguous ...)for a fold andErr(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)
Disambiguation.inspect
Section titled “Disambiguation.inspect”impl Debug for Disambiguation
fn inspect(value: Disambiguation) -> String
impl Debug.inspect
struct DateTime
Section titled “struct DateTime”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)
DateTime.format
Section titled “DateTime.format”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"
DateTime.format_fields
Section titled “DateTime.format_fields”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"
DateTime.to_string_with
Section titled “DateTime.to_string_with”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"
DateTime.in_zone
Section titled “DateTime.in_zone”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",
)
DateTime.from_instant_in
Section titled “DateTime.from_instant_in”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]"
DateTime.now_in
Section titled “DateTime.now_in”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")
DateTime.to_offset
Section titled “DateTime.to_offset”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"
DateTime.to_naive
Section titled “DateTime.to_naive”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"
DateTime.with_zone
Section titled “DateTime.with_zone”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]"
DateTime.zone
Section titled “DateTime.zone”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"
DateTime.parse
Section titled “DateTime.parse”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")
DateTime.between
Section titled “DateTime.between”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)
DateTime.from_fragments
Section titled “DateTime.from_fragments”impl Literal for DateTime
fn from_fragments(fragments: List<Fragment<String>>) -> Result<DateTime, Error>
DateTime.to_string
Section titled “DateTime.to_string”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]).
DateTime.inspect
Section titled “DateTime.inspect”impl Debug for DateTime
fn inspect(d: DateTime) -> String
impl Debug.inspect
DateTime.year
Section titled “DateTime.year”impl DateParts for DateTime
fn year(value: DateTime) -> Int
impl DateParts.year
DateTime.month
Section titled “DateTime.month”impl DateParts for DateTime
fn month(value: DateTime) -> Int
impl DateParts.month
DateTime.day
Section titled “DateTime.day”impl DateParts for DateTime
fn day(value: DateTime) -> Int
impl DateParts.day
DateTime.hour
Section titled “DateTime.hour”impl TimeParts for DateTime
fn hour(value: DateTime) -> Int
impl TimeParts.hour
DateTime.minute
Section titled “DateTime.minute”impl TimeParts for DateTime
fn minute(value: DateTime) -> Int
impl TimeParts.minute
DateTime.second
Section titled “DateTime.second”impl TimeParts for DateTime
fn second(value: DateTime) -> Int
impl TimeParts.second
DateTime.nanosecond
Section titled “DateTime.nanosecond”impl TimeParts for DateTime
fn nanosecond(value: DateTime) -> Int
impl TimeParts.nanosecond
DateTime.to_instant
Section titled “DateTime.to_instant”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)
DateTime.offset
Section titled “DateTime.offset”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)
DateTime.add Add<Duration, DateTime>
Section titled “DateTime.add Add<Duration, DateTime>”impl Add<Duration, DateTime> for DateTime
fn add(lhs: DateTime, rhs: Duration) -> DateTime
impl Add.add
Add an exact Duration, of any length.
DateTime.add Add<Years, DateTime>
Section titled “DateTime.add Add<Years, DateTime>”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.
DateTime.add Add<Months, DateTime>
Section titled “DateTime.add Add<Months, DateTime>”impl Add<Months, DateTime> for DateTime
fn add(lhs: DateTime, Months(n)) -> DateTime
impl Add.add
Add whole calendar months, clamping end-of-month.
DateTime.add Add<Weeks, DateTime>
Section titled “DateTime.add Add<Weeks, DateTime>”impl Add<Weeks, DateTime> for DateTime
fn add(lhs: DateTime, Weeks(n)) -> DateTime
impl Add.add
Add whole calendar weeks.
DateTime.add Add<Days, DateTime>
Section titled “DateTime.add Add<Days, DateTime>”impl Add<Days, DateTime> for DateTime
fn add(lhs: DateTime, Days(n)) -> DateTime
impl Add.add
Add whole calendar days.
DateTime.add Add<Hours, DateTime>
Section titled “DateTime.add Add<Hours, DateTime>”impl Add<Hours, DateTime> for DateTime
fn add(lhs: DateTime, Hours(n)) -> DateTime
impl Add.add
Add whole civil hours.
DateTime.add Add<Minutes, DateTime>
Section titled “DateTime.add Add<Minutes, DateTime>”impl Add<Minutes, DateTime> for DateTime
fn add(lhs: DateTime, Minutes(n)) -> DateTime
impl Add.add
Add whole civil minutes.
DateTime.add Add<Seconds, DateTime>
Section titled “DateTime.add Add<Seconds, DateTime>”impl Add<Seconds, DateTime> for DateTime
fn add(lhs: DateTime, Seconds(n)) -> DateTime
impl Add.add
Add whole civil seconds.
DateTime.add Add<Milliseconds, DateTime>
Section titled “DateTime.add Add<Milliseconds, DateTime>”impl Add<Milliseconds, DateTime> for DateTime
fn add(lhs: DateTime, Milliseconds(n)) -> DateTime
impl Add.add
Add whole civil milliseconds.
DateTime.add Add<Microseconds, DateTime>
Section titled “DateTime.add Add<Microseconds, DateTime>”impl Add<Microseconds, DateTime> for DateTime
fn add(lhs: DateTime, Microseconds(n)) -> DateTime
impl Add.add
Add whole civil microseconds.
DateTime.add Add<Nanoseconds, DateTime>
Section titled “DateTime.add Add<Nanoseconds, DateTime>”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.
DateTime.equal
Section titled “DateTime.equal”impl Equatable for DateTime
fn equal(a: DateTime, b: DateTime) -> Bool
impl Equatable.equal
DateTime.hash
Section titled “DateTime.hash”impl Hashable for DateTime
fn hash(value: DateTime) -> Int
impl Hashable.hash
DateTime.compare
Section titled “DateTime.compare”impl Comparable for DateTime
fn compare(a: DateTime, b: DateTime) -> Ordering
impl Comparable.compare
DateTime.localize
Section titled “DateTime.localize”impl Localize for DateTime
fn localize(dt: DateTime, locale: Locale) -> String
impl Localize.localize
The moment as DateTime.format writes it.
enum Weekday
Section titled “enum Weekday”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"
Weekday.to_string
Section titled “Weekday.to_string”impl Display for Weekday
fn to_string(day: Weekday) -> String
impl Display.to_string
Weekday.inspect
Section titled “Weekday.inspect”impl Debug for Weekday
fn inspect(value: Weekday) -> String
impl Debug.inspect
Weekday.equal
Section titled “Weekday.equal”impl Equatable for Weekday
fn equal(a: Weekday, b: Weekday) -> Bool
impl Equatable.equal
Weekday.hash
Section titled “Weekday.hash”impl Hashable for Weekday
fn hash(value: Weekday) -> Int
impl Hashable.hash
enum DateStyle
Section titled “enum DateStyle”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).
DateStyle.inspect
Section titled “DateStyle.inspect”impl Debug for DateStyle
fn inspect(value: DateStyle) -> String
impl Debug.inspect
DateStyle.equal
Section titled “DateStyle.equal”impl Equatable for DateStyle
fn equal(a: DateStyle, b: DateStyle) -> Bool
impl Equatable.equal
enum TimeStyle
Section titled “enum TimeStyle”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.
TimeStyle.inspect
Section titled “TimeStyle.inspect”impl Debug for TimeStyle
fn inspect(value: TimeStyle) -> String
impl Debug.inspect
TimeStyle.equal
Section titled “TimeStyle.equal”impl Equatable for TimeStyle
fn equal(a: TimeStyle, b: TimeStyle) -> Bool
impl Equatable.equal
enum TimeUnit
Section titled “enum TimeUnit”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.
TimeUnit.format_relative
Section titled “TimeUnit.format_relative”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"
TimeUnit.inspect
Section titled “TimeUnit.inspect”impl Debug for TimeUnit
fn inspect(value: TimeUnit) -> String
impl Debug.inspect
TimeUnit.equal
Section titled “TimeUnit.equal”impl Equatable for TimeUnit
fn equal(a: TimeUnit, b: TimeUnit) -> Bool
impl Equatable.equal
type DateFields
Section titled “type DateFields”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")
DateFields.parse
Section titled “DateFields.parse”fn parse(text: String) -> Result<DateFields, Error>
type function on DateFields
The skeleton text names, or why it names none a date has.
DateFields.from_fragments
Section titled “DateFields.from_fragments”impl Literal for DateFields
fn from_fragments(fragments: List<Fragment<String>>) -> Result<DateFields, Error>
DateFields.inspect
Section titled “DateFields.inspect”impl Debug for DateFields
fn inspect(fields: DateFields) -> String
impl Debug.inspect
DateFields.equal
Section titled “DateFields.equal”impl Equatable for DateFields
fn equal(a: DateFields, b: DateFields) -> Bool
impl Equatable.equal
type TimeFields
Section titled “type TimeFields”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")
TimeFields.parse
Section titled “TimeFields.parse”fn parse(text: String) -> Result<TimeFields, Error>
type function on TimeFields
The skeleton text names, or why it names none a time has.
TimeFields.from_fragments
Section titled “TimeFields.from_fragments”impl Literal for TimeFields
fn from_fragments(fragments: List<Fragment<String>>) -> Result<TimeFields, Error>
TimeFields.inspect
Section titled “TimeFields.inspect”impl Debug for TimeFields
fn inspect(fields: TimeFields) -> String
impl Debug.inspect
TimeFields.equal
Section titled “TimeFields.equal”impl Equatable for TimeFields
fn equal(a: TimeFields, b: TimeFields) -> Bool
impl Equatable.equal
type DateTimeFields
Section titled “type DateTimeFields”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")
DateTimeFields.parse
Section titled “DateTimeFields.parse”fn parse(text: String) -> Result<DateTimeFields, Error>
type function on DateTimeFields
The skeleton text names, or why it names none.
DateTimeFields.from_fragments
Section titled “DateTimeFields.from_fragments”impl Literal for DateTimeFields
fn from_fragments(fragments: List<Fragment<String>>) -> Result<DateTimeFields, Error>
DateTimeFields.inspect
Section titled “DateTimeFields.inspect”impl Debug for DateTimeFields
fn inspect(fields: DateTimeFields) -> String
impl Debug.inspect
DateTimeFields.equal
Section titled “DateTimeFields.equal”impl Equatable for DateTimeFields
fn equal(a: DateTimeFields, b: DateTimeFields) -> Bool
impl Equatable.equal
type DatePattern
Section titled “type DatePattern”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")
DatePattern.parse
Section titled “DatePattern.parse”fn parse(text: String) -> Result<DatePattern, Error>
type function on DatePattern
The pattern text is, or why it is not a fixed date pattern.
DatePattern.from_fragments
Section titled “DatePattern.from_fragments”impl Literal for DatePattern
fn from_fragments(fragments: List<Fragment<String>>) -> Result<DatePattern, Error>
DatePattern.inspect
Section titled “DatePattern.inspect”impl Debug for DatePattern
fn inspect(pattern: DatePattern) -> String
impl Debug.inspect
DatePattern.equal
Section titled “DatePattern.equal”impl Equatable for DatePattern
fn equal(a: DatePattern, b: DatePattern) -> Bool
impl Equatable.equal
type TimePattern
Section titled “type TimePattern”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")
TimePattern.parse
Section titled “TimePattern.parse”fn parse(text: String) -> Result<TimePattern, Error>
type function on TimePattern
The pattern text is, or why it is not a fixed time pattern.
TimePattern.from_fragments
Section titled “TimePattern.from_fragments”impl Literal for TimePattern
fn from_fragments(fragments: List<Fragment<String>>) -> Result<TimePattern, Error>
TimePattern.inspect
Section titled “TimePattern.inspect”impl Debug for TimePattern
fn inspect(pattern: TimePattern) -> String
impl Debug.inspect
TimePattern.equal
Section titled “TimePattern.equal”impl Equatable for TimePattern
fn equal(a: TimePattern, b: TimePattern) -> Bool
impl Equatable.equal
type DateTimePattern
Section titled “type DateTimePattern”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")
DateTimePattern.parse
Section titled “DateTimePattern.parse”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.
DateTimePattern.from_fragments
Section titled “DateTimePattern.from_fragments”impl Literal for DateTimePattern
fn from_fragments(fragments: List<Fragment<String>>) -> Result<DateTimePattern, Error>
DateTimePattern.inspect
Section titled “DateTimePattern.inspect”impl Debug for DateTimePattern
fn inspect(pattern: DateTimePattern) -> String
impl Debug.inspect
DateTimePattern.equal
Section titled “DateTimePattern.equal”impl Equatable for DateTimePattern
fn equal(a: DateTimePattern, b: DateTimePattern) -> Bool
impl Equatable.equal