Skip to content

Dates & Times

Three standard library modules cover dates and times:

  • std::calendar has the types a person reads off a calendar or a clock, plus periods such as Days and Months:
    • Date: a day on the calendar.
    • Time: a time of day.
    • NaiveDateTime: a date and a time with no zone.
    • OffsetDateTime: a date and time at a fixed offset from UTC, such as -04:00.
    • DateTime: a date and time in a named zone such as America/New_York.
  • std::instant.Instant is a machine timestamp.
  • std::duration.Duration is an exact length of time, such as 5 seconds or 30 minutes.

For an event that happens at a real moment, use DateTime. “10:30 AM on June 15 in New York” names one moment, and a DateTime holds exactly that: a date, a time, and a time zone such as America/New_York. It knows the zone’s daylight saving rules.

NaiveDateTime is a date and time with no zone. It is useful for templates and for data that came without a zone. It does not name a real moment, so don’t use it for “when the meeting happens”. The word “Naive” in its name is there as a warning.

Each calendar type has a typed literal. Without a ${...} slot, it is checked when the program compiles, so it needs no ?. DateTime puts the zone name in square brackets at the end, a format from RFC 9557:

import std::calendar.{Date, DateTime}

fn main()
    d = Date"2026-06-15"
    dbg d

    dt = DateTime"2026-06-15T14:30:00-04:00[America/New_York]"
    dbg dt

    dbg DateTime.year(dt)
    dbg DateTime.month(dt)
    dbg DateTime.hour(dt)
end

Add or subtract days, weeks, months and years from a Date with + and -. When you add months or years and the target month is too short for the day, you get the month’s last day. January 31 plus one month is February 28:

import std::calendar.{Date, Days, Months, Weeks, Years}

fn main()
    start = Date"2026-05-04"
    jan31 = Date"2026-01-31"
    leap = Date"2024-02-29"

    dbg start + Days(10)
    dbg start + Weeks(2)
    dbg start - Weeks(1)
    dbg jan31 + Months(1)
    dbg jan31 - Months(1)
    dbg leap + Years(1)
end

An Instant is a point in time, stored as nanoseconds since the Unix epoch. It has no calendar and no time zone. Instant.now() returns one. Store an Instant when you need a moment that doesn’t depend on any zone.

A Duration is an exact number of nanoseconds. You add it to an instant, subtract it from one, get it back from later - earlier, or pass it to timer.sleep. Make one with a unit function such as Duration.seconds(5) or Duration.minutes(30). Combine durations with +, -, * and /:

import
    std::duration.Duration
    std::instant.Instant
end

fn main()
    start = Instant.from_seconds(1_700_000_000)
    five_minutes = Duration.minutes(5)

    dbg Duration.as_minutes(five_minutes)

    later = start + five_minutes
    dbg Instant.to_seconds(later)
    dbg later - start
end

This example doesn’t use Instant.now() or timer.sleep, because they read the real clock and wait in real time, so their output changes from run to run.

An Instant and a Duration are counts of any size, so Instant.from_seconds takes any timestamp, and Instant + Duration and the difference of two instants never overflow. Go’s clock counts the years 1677 to 2262, and a function that hands an Instant to Go says what one outside them means: a deadline past 2262 never comes. The calendar types have no range either: a year is an Int of any size, and one outside 0000 to 9999 is written with a sign and at least six digits, as in Date"+010000-01-01".

A DateTime holds a moment and the zone to show it in. Two DateTimes are equal when they are the same moment, even if their zones differ. Noon in New York and 6 PM in Paris on the same day are equal:

import std::calendar.DateTime

fn main()
    ny = DateTime"2026-06-15T12:00:00-04:00[America/New_York]"
    paris = DateTime"2026-06-15T18:00:00+02:00[Europe/Paris]"

    dbg ny == paris
    dbg ny
    dbg paris
end

DateTime.with_zone(dt, zone) keeps the same moment and shows it in another zone. Noon in New York is 1 AM the next day in Tokyo:

import std::calendar.{DateTime, Error}

fn main() -> Result<Unit, Error>
    ny = DateTime"2026-06-15T12:00:00-04:00[America/New_York]"
    tokyo = DateTime.with_zone(ny, "Asia/Tokyo")?
    dbg tokyo
    dbg ny == tokyo
    Ok(Unit)
end

In 2026, New York’s clocks jump from 2 AM to 3 AM on March 8. Start at noon on March 7. Adding one calendar day gives noon on March 8. Adding exactly 24 hours gives 1 PM, because that night was one hour short:

import
    std::calendar.{DateTime, Days}
    std::duration.Duration
end

fn main()
    start = DateTime"2026-03-07T12:00:00-05:00[America/New_York]"
    civil = start + Days(1)
    physical = start + Duration.hours(24)

    dbg start
    dbg civil
    dbg physical
end

Both results are correct for different questions. + Days(1) keeps the clock reading, noon, and works out the new UTC offset. + Duration.hours(24) moves the moment forward by exactly 24 hours.

DateTime.in_zone puts a NaiveDateTime into a zone. Daylight saving makes two cases hard:

  • A gap: the clock time never happens, because the clocks jumped over it.
  • A fold: the clock time happens twice, because the clocks went back.

The Disambiguation argument says which moment to pick:

import std::calendar.{DateTime, Error, NaiveDateTime}

fn main() -> Result<Unit, Error>
    // 2026-11-01 01:30 NY happens twice (2am EDT rolls back to 1am EST).
    naive = NaiveDateTime"2026-11-01T01:30:00"

    earlier = DateTime.in_zone(naive, "America/New_York", .Earlier)?
    later = DateTime.in_zone(naive, "America/New_York", .Later)?

    // Same wall reading, different offsets, different instants.
    dbg earlier
    dbg later

    // One hour apart as moments.
    dbg DateTime.to_instant(later) - DateTime.to_instant(earlier)

    // Different moments, so not equal.
    dbg earlier == later
    Ok(Unit)
end

If you pass no mode, you get Disambiguation.Compatible. In a fold it picks the earlier moment. In a gap it moves forward past the jump, so 2:30 becomes 3:30.

Disambiguation.Reject returns an Err for a gap or a fold instead of picking. Use it when a person typed the time, so you can ask them which one they meant.

dbg and "${date}" write ISO 8601, 2026-10-20, the same everywhere. A person reads a date the way their language writes it, so Date.format takes a locale:

import std::calendar.Date

fn main()
    ships = Date"2026-10-20"
    dbg Date.format(ships, Locale"en-US", style: .Long)
    dbg Date.format(ships, Locale"de", style: .Long)
end

Locales & Formatting covers the styles, choosing the fields, times, and reading dates people type.

DateTime.now_in(zone) reads the system clock and gives the time in that zone. It is short for Instant.now() |> DateTime.from_instant_in(zone):

import std::calendar.{DateTime, Error}

fn main() -> Result<Unit, Error>
    now = DateTime.now_in("America/New_York")?
    dbg now // example: dbg line 5: now = 2026-05-26T17:42:00-04:00[America/New_York]
    Ok(Unit)
end

The output changes each time, because it reads the real clock.

A reading with no zone, such as a database timestamp column, is a NaiveDateTime. NaiveDateTime.from_instant(Instant.now()) gives the UTC reading, and NaiveDateTime.to_instant reads one back. DateTime.to_naive and OffsetDateTime.to_naive drop the zone or offset and keep the clock reading.

Where to look next

Money is next. It works with amounts in a currency.