Skip to content

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:00Z

on 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/Tokyo

now, today, tomorrow, and yesterday come from the clock.

now
today
tomorrow

A 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.

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 pm

A 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/Tokyo

To keep the date a shift crosses, put the time on a date first.

3pm on today + 12 hours

to 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/Tokyo

at 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 3pm

A 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 == today

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 month

The 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 dp

The words ago, hence, before, and after read like English.

3 days ago
2 weeks hence
2 days before 22 Jun 2026
2 hours after 9am

Dates 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)

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_York

Zones 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.