date and time

Date-time literals use the a subset of ISO 8601 syntax, extended format only.

An empty date-time literal generates the current date-time in your time zone. A date-time literal with only a time zone offset or Z (UTC) specified generates the current date-time in that time zone.

The mode nowIncludesNano determines if nanoseconds are included (defaults to false).

If not specifying a time zone only, the year, month, and day are required. Hours, minutes, and seconds are optional (defaulting to 0).

The date and time are separated by either a space or a capital T.

Dates are proleptic Gregorian.

Fractional seconds may be 1 to 9 digits.

The operators ==, >, <=, etc. can be used to compare date-times.

time zone

The default time zone used is your local time zone.

The letter Z gives the UTC time zone (same as +00:00).


A formatting string may be passed to the string type (such as string(dt//, .formatstring)) or used in a date-time interpolation modifier.

The Go time package expects the following numbers and formats in a format string.

A number preceeded with a zero is zero-padded and with an underscore is space-padded.

date-time math

Durations can be added to or subtracted from date-times. You can also add or subtract a number (nanoseconds), but a duration might give a more predicatable result in terms of "years" and "months."

dt/2015-05-01/ + dr/1Y 1M 1D T 1H/ dt/2015-05-01/ - dr/1Y 1M 1D T 1H/ # adding or subtracting durations

dt/2015-05-01/ + 1000 dt/2015-05-01/ - 1000 # adding or subtracting nanoseconds

You can get the difference between 2 date-time values, yielding a duration (in years, months, etc.).

dt/2015-05-01/ - dt/2016-06-02T01:01:01.000000001/ == dr/1Y 1M 1D T 1H 1M 1.000000001S/

type conversion and type checking

Using type names helps to do conversion and type checking. See the built-ins, operators, and type pages for details.

The datetime type name can be used to generate a date-time value or to convert a date-time value to another time zone, such as datetime(123).

Conversion to a hash (using hash(dt//)) will give you all the data about a date-time value in separate hash fields.

When converting a date-time to a number (number(dt//)), it will return the number of nanoseconds since the start of January 1, 1970 UTC.

Conversion to a string, without a second argument (string(dt//)), will produce an ISO 8601/RFC 3339 timestamp. A second argument would be a format string to use. This formatting is currently the same as that used by the Go time package.