Skip to the content.

date

import "date" as date

Dates, times and durations. A Date is a moment in time, stored as a Unix timestamp in milliseconds. Its calendar fields (year, month, …) are in UTC, and there are matching functions for the computer’s local time zone. A Duration is a length of time.

import "date" as date

let launch = date.Date(year = 2026, month = 7, day = 28, hour = 15)
let week_later = launch + date.Duration(weeks = 1)

term.log(launch)                         # 2026-07-28T15:00:00.000Z
term.log(week_later.to_string("%d %b"))  # 04 Aug
term.log(week_later - launch)            # 7 days, 00:00:00
term.log(launch.weekday_name)            # Tuesday

Creating dates

Date(...)

Date(timestamp_ms=null, timestamp_s=null, date=null,
     year=null, month=null, day=null, hour=null, minute=null, second=null, millisecond=null,
     utc=true)

Describe the date in one of these ways, by keyword:

Arguments Meaning
timestamp_ms Unix timestamp in milliseconds
timestamp_s Unix timestamp in seconds
date a copy of another Date
year, month, day, hour, minute, second, millisecond calendar fields; missing ones default to the start of 1970-01-01
(nothing) the Unix epoch, 1970-01-01T00:00:00Z

Calendar fields are read as UTC, or as local time if utc = false. Fields that are out of range roll over: Date(year = 2026, month = 13) is January 2027, and second = 90 is a minute and a half.

import "date" as date

term.log(date.Date(timestamp_ms = 0))                   # 1970-01-01T00:00:00.000Z
term.log(date.Date(timestamp_s = 1785250800))           # 2026-07-28T15:00:00.000Z
term.log(date.Date(year = 2026, month = 7, day = 28))   # 2026-07-28T00:00:00.000Z
term.log(date.Date(year = 2026, month = 7, day = 28, hour = 9, utc = false).to_local_string())   # 2026-07-28 09:00:00

Date.now() and Date.today(utc=true)

Date.now() is the current moment. Date.today() is midnight at the start of today, in UTC or (with utc = false) in local time.

Date.from_string(text, format="%Y-%m-%d %H:%M:%S", utc=true)

Parses a date using a format string. The result is read as UTC, or as local time if utc = false. Fields missing from the format default to 1970-01-01 00:00:00. If text doesn’t match the format exactly, it throws a ValueError:

import "date" as date

let d = date.Date.from_string("28/07/2026 09:30", "%d/%m/%Y %H:%M")
term.log(d)   # 2026-07-28T09:30:00.000Z

try date.Date.from_string("next tuesday", "%d/%m/%Y")
catch (ValueError as e) term.log(e.message)

Date.from_iso_string(text, utc=true)

Parses an ISO 8601 / RFC 3339 date, as used by JSON APIs. The time, seconds, fractional seconds and time zone are optional. A time zone suffix (Z, +01:00, -0530) is always respected; without one, the time is read as UTC (or local time if utc = false). Invalid dates, like 2026-02-30, throw a ValueError.

import "date" as date

term.log(date.Date.from_iso_string("2026-07-28"))                 # 2026-07-28T00:00:00.000Z
term.log(date.Date.from_iso_string("2026-07-28T15:30:00.25Z"))    # 2026-07-28T15:30:00.250Z
term.log(date.Date.from_iso_string("2026-07-28 15:30:00+01:00"))  # 2026-07-28T14:30:00.000Z

Fields

These are read as attributes, and are all in UTC (see Local time for local fields):

Field Description
year e.g. 2026
month 1 to 12
day 1 to 31
hour 0 to 23
minute 0 to 59
second 0 to 59
millisecond 0 to 999
day_of_week 0 (Sunday) to 6 (Saturday)
day_of_year 1 to 366
weekday_name e.g. "Tuesday"
month_name e.g. "July"
is_leap_year whether the date’s year is a leap year
days_in_month the number of days in the date’s month

year, month, day, hour, minute, second and millisecond can be assigned (or set with set_year(value), set_month(value), …), which changes the date in place. To get a changed copy instead, use replace:

import "date" as date

let d = date.Date(year = 2026, month = 1, day = 31)
let first = d.replace(day = 1)
d.month = 3
term.log(first, d)   # 2026-01-01T00:00:00.000Z 2026-03-31T00:00:00.000Z

replace(year=null, month=null, day=null, hour=null, minute=null, second=null, millisecond=null, utc=true) works on the UTC fields, or the local fields if utc = false.

Durations and date arithmetic

Duration(weeks=0, days=0, hours=0, minutes=0, seconds=0, milliseconds=0) is a length of time. Durations can be negative and fractional.

Expression Result
date + duration, date - duration a Date
date - other_date a Duration
duration + duration, duration - duration, -duration a Duration
duration * number, duration / number a Duration
duration / duration a number (how many times one fits into the other)

Dates and durations can be compared with ==, !=, <, <=, > and >=, and used as dictionary keys.

import "date" as date

let start = date.Date(year = 2026, month = 7, day = 28, hour = 9)
let end = date.Date(year = 2026, month = 12, day = 25)
let gap = end - start

term.log(gap)                     # 149 days, 15:00:00
term.log(gap.total_days)          # 149.625
term.log(start < end)             # true
term.log(date.Duration(hours = 1) / date.Duration(minutes = 15))   # 4

A Duration has total_milliseconds, total_seconds, total_minutes, total_hours and total_days properties. Printing it gives [N days, ]HH:MM:SS[.mmm].

Calendar arithmetic

Method Returns
add(weeks=0, days=0, hours=0, minutes=0, seconds=0, milliseconds=0) the date plus that much time
add_months(n, utc=true) the same day n months later (or earlier, if negative); the day is clamped to the month’s length
add_years(n, utc=true) the same date n years later; February 29 becomes February 28 in non-leap years
start_of_day(utc=true) / end_of_day(utc=true) 00:00:00.000 / 23:59:59.999 on the same day
start_of_month(utc=true) / start_of_year(utc=true) midnight on the first day of the month / year
copy() a copy of the date

With utc = false, these work on local calendar days and months.

import "date" as date

let d = date.Date(year = 2026, month = 1, day = 31, hour = 12)
term.log(d.add_months(1))          # 2026-02-28T12:00:00.000Z
term.log(d.add(days = 1, hours = 6))   # 2026-02-01T18:00:00.000Z
term.log(d.start_of_month())       # 2026-01-01T00:00:00.000Z

Local time

Method Description
local() the local calendar fields as a dictionary: year, month, day, hour, minute, second, millisecond, day_of_week, day_of_year and utc_offset
utc_offset() the local time zone’s offset from UTC at this moment, as a Duration (it includes daylight saving time)
to_local_string(format="%Y-%m-%d %H:%M:%S") format in local time
to_local_iso_string() ISO 8601 with the local offset, e.g. 2026-07-28T16:00:00.000+01:00
import "date" as date

let now = date.Date.now()
let here = now.local()
term.log(`It's $(here.hour):$(here.minute) here, UTC$(now.to_local_iso_string()[-6:])`)

Formatting and timestamps

Method Returns
to_string(format="%Y-%m-%d %H:%M:%S") the date formatted in UTC
to_iso_string() ISO 8601 in UTC, e.g. 2026-07-28T15:00:00.000Z (also what printing a date shows)
http_date() HTTP date format, e.g. Tue, 28 Jul 2026 15:00:00 GMT
unix() Unix timestamp in whole seconds
unix_ms() Unix timestamp in milliseconds

Measuring elapsed time

Date.monotonic() returns a reading, in nanoseconds, from a clock that never jumps when the system clock changes. Subtract two readings to time something:

import "date" as date
import "time" as time

let start = date.Date.monotonic()
time.snooze(0.1)
let elapsed_ms = (date.Date.monotonic() - start) / 1000000
term.log(elapsed_ms >= 100)   # true

Module functions

Name Description
date.is_leap_year(year) whether year is a leap year
date.days_in_month(year, month) the number of days in a month
date.WEEKDAYS ["Sunday", ..., "Saturday"]
date.MONTHS ["January", ..., "December"]

Format strings

Formatting and parsing use strftime-style codes. Some common ones:

Code Meaning Example
%Y four-digit year 2026
%m month number 07
%d day of the month 28
%H hour (24-hour clock) 15
%M minute 30
%S second 00
%a / %A weekday name Tue / Tuesday
%b / %B month name Jul / July
%Z time zone name (in to_local_string) BST
%% a literal % %

Names produced by %a, %b and so on depend on the system’s locale. The weekday_name and month_name fields are always English.

Next