date and time

Langur 0.9 introduces date-time literals, the syntax of which uses a subset of ISO 8601, extended format only. 0.10.1 introduces date-time durations, shown farther down this page. Here are some date-time literal examples.

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.

0.12.6 adds the mode nowIncludesNano. Prior to this, "now" always included nanoseconds.

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.

0.12.6 adds fractional seconds to the literal syntax. This 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).


Some built-in functions help with dealing with date-times. See the built-ins page for details.

The toDateTime() function can be used to generate a date-time value or to convert a date-time value to another time zone.

The toHash() function will give you all the data about a date-time value in separate hash fields.

When passing a date-time to the toNumber() function, it will return the number of nanoseconds since the start of January 1, 1970 UTC.

The toString() function, without a second argument, 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.


A formatting string may be passed to the toString() function 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.


Durations also use the dt// tokens and begin with a capital P.

They also follow ISO 8601 syntax (see the Wikipedia article section on durations). Time durations must include a capital T first. The following shows the general syntax, with [n] as a placeholder for an integer. All parts are optional, but there must be at least one. They also must be in order (most significant portions first).

dt/P[n]Y[n]M[n]DT[n]H[n]M[n[.n]]S/ dt/P[n]W/

The letters represent Years, Months, Days, then Hours, Minutes, and Seconds, or Weeks.

Durations are converted directly to nanoseconds. Here are some examples. Note that you can directly add or subtract nanoseconds on a date-time value, as in the third example below.

A "month" and a "year" are hard to define in this way. Currently, a "year" is the equivalent of 365.25 days and a "month" of 30.4375 days (365.25 / 12).

0.12.6 adds fractional seconds to the literal syntax. This may be 1 to 9 digits.