Dates and times
Write a date with a month name: 12 May; 12 May 2026; May 12;
May 12 2026; or May 12, 2026. Answers read the same way, such as
5pm on 26 Jun 2026, so you can paste one back in. ISO order also works
after an @: @2026-05-27, @2026-05-27T14:30. The month is Jan to Dec, the
full name, or Sept, with a capital letter. A date without a year is the
next one, today included: in October, 3 March is next March. Write the year
for one that has passed. A day that is not on the calendar, such as
Feb 30 2026, is an error. A month
name you have defined yourself keeps your meaning: after May = 5, 12 May
is 60, and after May rent = 1200, 3 May rent is 3600. A day may be an
ordinal with its correct suffix: 22nd May, May 3rd 2026, or 12th alone
for the next 12th. A wrong suffix (1th) is not a date, and a suffix you have defined
yourself (th = 5) keeps your meaning.
12 May 2026
May 12, 2026
22nd May 2026
May 3rd 2026
@2026-05-27T12:00Zon puts a time on a date. in attaches a time zone. to shows the same
moment in another zone.
5pm on 26 Jun 2026
5pm on 26 Jun 2026 in Europe/London
5pm on 26 Jun 2026 in Europe/London to America/New_York
5pm on 26 Jun 2026 in Europe/London to Asia/Tokyonow, today, tomorrow, and yesterday come from the clock.
now
today
tomorrowA document can define its own today or now. A date you write without a
year or month, such as May 12 or 12th, then fills it in from yours, and
3pm on today uses yours too. Converting a bare time (3pm to Asia/Tokyo),
ago, and hence all still use the clock.
Times of day
Section titled “Times of day”A time can be spelled 3pm, 3 pm, 9am, 9:30, 14:30:15, 1:45am,
12:30 pm or @14:30. A time with am or pm needs an hour from 1 to 12,
and 13:00pm is an error. Colon times need two digits for the minutes.
9:30
14:30:15
1:45am
12:30 pm
3 pmA bare time such as 3pm or noon has no date. It floats. Add or
subtract a duration and you get another time of day, wrapping at midnight.
An operation that needs a date takes one from the other side: the other
operand’s date, else today’s.
3pm
noon
3pm + 2 hours
11pm + 2 hours
5pm - 3pm
now < 3pm
3pm in Europe/London to Asia/TokyoTo keep the date a shift crosses, put the time on a date first.
3pm on today + 12 hoursto reads a bare time in the clock’s zone, then converts it: with the clock
in London, 3pm to Asia/Tokyo is 11pm in Tokyo. in gives the time a zone
instead.
3pm to Asia/Tokyoat is on the other way round: it puts a date before its time. It needs
the date on its left, so 3pm at 12 May 2026 is an error.
3pm on 12 May 2026
12 May 2026 at 3pmA date has no time of its own to lend, so comparing a time with a date, as in
midnight == today, is an error. Put the time on the date first.
midnight on today == todayDate arithmetic
Section titled “Date arithmetic”Add or subtract a duration. Whole days, weeks, fortnights, months and years
move by the calendar, keeping the time of day across a clock change, and
months clamp to the end of a short month. So does a unit you declare from
them, such as unit sprint = 2 weeks. Hours are elapsed time: 24 hours
across a clock change lands an hour away from 1 day.
27 May 2026 + 1 day
26 Jun 2026 + 3 weeks
31 Jan 2026 + 1 month
31 Jan 2028 + 1 monthThe difference of two dates is a duration. Ask for the units you want.
25 Dec 2026 - 26 Jun 2026
25 Dec 2026 - today to days
today - 20 Jul 1969 to years, days to 0 dpThe words ago, hence, before, and after read like English.
3 days ago
2 weeks hence
2 days before 22 Jun 2026
2 hours after 9amDates compare with the usual operators, and earlier and later pick
one of two.
22 Jun 2026 < 23 Jun 2026
later(9am on 22 Jun 2026, 10:30am on 22 Jun 2026)date, time, and timezone take an instant apart.
date(now)
time(now)
timezone(5pm on 26 Jun 2026 in Europe/Berlin)Time zones and daylight saving
Section titled “Time zones and daylight saving”default timezone: gives every zoneless date-time in the document a zone.
Daylight saving is resolved per zone and per date, so the same meeting can
land at a different hour abroad in the weeks when only one side has changed
its clocks.
default timezone: Europe/Berlin
sync = 4pm on 4 May 2026
sync to America/New_York
autumn = 4pm on 28 Oct 2026
autumn to America/New_YorkZones can be IANA names (Europe/Berlin), fixed offsets (UTC+4,
UTC-05:30), or UTC. A zone is a value: tz = Europe/Paris then
now to tz.
The common names work too: PST, Eastern, BST, CEST, IST, JST,
AEST, NZDT and others name the zone, not a fixed offset, so PST in
summer is Pacific daylight time. Where an abbreviation means more than one
place it means the most common one: IST is India, CST is US Central.
EST and MST are the exception: the zone database holds them as fixed
offsets, so in summer use Eastern and Mountain.