date

Build, parse, format and compare dates and times, do arithmetic on them, and show them in any time zone.

std:date is for anything with a calendar or a clock: parsing a timestamp, adding 30 days to a deadline, working out how long ago something happened, or showing the same moment in London and Tokyo. Three types do the work:

• date.DateTime is one instant in time, held in UTC. Every date you parse or build is one.
• date.Duration is a length of time, such as the gap between two instants.
• date.ZonedDateTime is a view of an instant in a time zone, for showing local times.

A DateTime never changes. Every method that "changes" it returns a new one.

Parsing a date#

date.parse(text) reads ISO 8601 dates and times and returns a result, because the text may not be a date:

import "std:date"

auto d = date.parse("2024-03-15T14:30:00Z").unwrap()
log d.iso()
log d.unix()

iso() writes the instant back as text in UTC. unix() is whole seconds since 1 January 1970 (the Unix epoch), the form most APIs and files use.

Without a format, parse accepts these shapes:

import "std:date"

string[] inputs = [
  "2024-03-01",
  "2024-03-01T12:30",
  "2024-03-01 12:30:05",
  "2024-03-01T12:30:05.250Z",
  "2024-03-01T12:30:05+02:00"
]
for text in inputs (
  log date.parse(text).unwrap().iso()
)

Missing parts default to the start of the period (a date with no time is midnight). An offset such as +02:00 is applied, so the last line is two hours earlier in UTC.

When parsing fails#

Dates from users and files are often wrong. A bad one fails with a ParseError, and the calendar is checked, so 30 February is rejected:

import "std:date"

string[] inputs = ["2024-03-15", "yesterday", "2024-02-30"]
for text in inputs (
  date.DateTime d = date.parse(text) catch (e) (
    log text ++ " -> " ++ e.kind
    continue
  )
  log text ++ " -> ok " ++ d.format("MMM D")
)

Parsing other formats#

Pass format with the same tokens that format() uses (listed below) to read a layout that isn't ISO:

import "std:date"

auto uk = date.parse("15/03/2024", {format: "DD/MM/YYYY"}).unwrap()
auto us = date.parse("March 5, 2024", {format: "MMMM D, YYYY"}).unwrap()
log uk.iso()
log us.iso()

Text with no offset is read as UTC. If it was written in another zone, say which with the timezone option and it is converted:

import "std:date"

auto tokyo = date.parse("2024-06-01 09:00", {timezone: "Asia/Tokyo"}).unwrap()
log tokyo.iso()

Nine in the morning in Tokyo (UTC+9) is midnight UTC, nine hours earlier on the same clock. Keep this habit: parse at the edge of your program into an instant, work with instants, and convert to a zone only to display.

Formatting#

format(layout) writes the date using tokens:

import "std:date"

auto d = date.parse("2024-03-15T14:30:05Z").unwrap()
log d.format("YYYY-MM-DD")
log d.format("D MMM YYYY")
log d.format("dddd, MMMM D, YYYY")
log d.format("HH:mm:ss")
log d.format("h:mm A")
log d.format("[Week] ddd")
log d.format("X")

Wrap literal text in square brackets, as [Week] is above, so its letters aren't read as tokens.

Building dates from parts#

There is no constructor taking year, month and day. Parse a string, or start from a unix time and move from there:

import "std:date"

log date.fromUnix(0).iso()
log date.fromUnixMillis(1700000000000).iso()

auto year = 2025
auto month = 9
auto d = date.parse(year ++ "-0" ++ month ++ "-01").unwrap()
log d.format("dddd")

date.daysInMonth(year, month) and date.isLeap(year) answer calendar questions without a date at all:

import "std:date"

log date.daysInMonth(2024, 2) date.daysInMonth(2025, 2)
log date.isLeap(2024) date.isLeap(1900) date.isLeap(2000)

Arithmetic#

add(unit, amount) and subtract move an instant. Units are "y", "mo", "d", "h", "m", "s", "ms" and "us", or the long names such as "days":

import "std:date"

auto d = date.parse("2024-03-15T14:30:00Z").unwrap()
log d.add("days", 20).iso()
log d.add("hours", 36).iso()
log d.subtract("m", 45).iso()
log d.add("y", 1).iso()
log d.iso()

The last line shows d itself is untouched.

Months and years follow the calendar, so they can land past the end of a short month. January 31 plus a month is "February 31", which rolls over to March:

import "std:date"

auto d = date.parse("2024-01-31T10:00:00Z").unwrap()
log d.add("mo", 1).iso()

If you need "the last day of next month", use date.daysInMonth and with. Days are always 24 hours, so adding a day never lands on a different time of day.

Changing one field#

with(field, value) replaces one field. truncate(unit) zeroes everything smaller than a unit:

import "std:date"

auto d = date.parse("2024-03-15T14:30:45Z").unwrap()
log d.with("year", 2000).iso()
log d.with("day", 1).iso()
log d.truncate("day").iso()
log d.truncate("hour").iso()

truncate("day") is how you get the start of a day, to group events by date or compare dates ignoring the time.

Comparing#

Compare with before, after, equals or compare, which is -1, 0 or 1 and suits sorting:

import "std:date"

auto a = date.parse("2024-01-01").unwrap()
auto b = date.parse("2024-06-01").unwrap()
log a.before(b) a.after(b) a.equals(a)
log a.compare(b)

date.DateTime[] dates = [b, a, date.parse("2023-01-01").unwrap()]
log dates.toSortedBy(d -> d.unix()).map(d -> d.format("YYYY-MM-DD"))

Durations#

until(other) and since(other) return a date.Duration, which you read in whatever unit you want. until is negative when the other date is earlier, and since is the opposite:

import "std:date"

auto start = date.parse("2024-07-01T12:00:00Z").unwrap()
auto end = date.parse("2024-12-25").unwrap()
auto gap = start.until(end)

log floor(gap.days())
log gap.hours()
log end.until(start).days() < 0

A duration offers days(), hours(), minutes(), seconds() (numbers, with fractions) and millis() and micros() (whole numbers). To get whole days, use floor as above.

date.millis(ms) makes a duration to add, and the constants date.second, date.minute, date.hour, date.day and date.week are those lengths in milliseconds:

import "std:date"

auto d = date.parse("2024-03-15T14:30:00Z").unwrap()
log d.addDuration(date.millis(date.hour * 2)).iso()
log date.week / date.day

Time zones#

inTimezone(name) returns a ZonedDateTime for an IANA name such as Europe/London. It is the same instant, shown on that zone's clock, daylight saving included:

import "std:date"

auto launch = date.parse("2024-07-01T12:00:00Z").unwrap()
for zone in ["Europe/London", "America/Los_Angeles", "Asia/Tokyo"] (
  auto z = launch.inTimezone(zone).unwrap()
  log zone z.format("HH:mm z")
)
log launch.inTimezone("America/Los_Angeles").unwrap().iso()

A zoned value can format and write iso() with its offset, tell you its timezone(), and give back the plain instant with toDateTime(). To do arithmetic, go back to a DateTime, do it, and convert again. An unknown zone name returns an error result, so a user-supplied zone should be checked:

import "std:date"

auto d = date.parse("2024-07-01T12:00:00Z").unwrap()
log d.inTimezone("Nowhere/Land").isErr()

The current time#

date.now() is the current instant, and now.unix() is a timestamp in seconds. The value differs every run, so print facts about it, not the value:

import "std:date"

auto now = date.now()
auto earlier = now.subtract("d", 1)
log now.after(earlier)
log floor(earlier.until(now).hours())
log now.unix() > 1700000000

To time how long something takes, subtract two instants: date.now().since(start).millis().

auto d = date.parse("2024-01-31T10:00:00Z").unwrap()
log d.add("mo", 1).iso()

import "std:date"

auto today = date.parse("2025-02-14").unwrap()
auto due = date.parse("2025-03-31").unwrap()

log today.iso() due.iso()

import "std:date"

auto today = date.parse("2025-02-14").unwrap()
auto due = date.parse("2025-03-31").unwrap()

log today.iso() due.iso()

45
Monday

API reference#