Find file
Fetching contributors…
Cannot retrieve contributors at this time
308 lines (185 sloc) 7.7 KB


DRAFT: Synopsis 32: Setting Library - Temporal


    The authors of the related Perl 5 docs
    Rod Adams <>
    Larry Wall <>
    Aaron Sherman <>
    Mark Stosberg <>
    Carl Mäsak <>
    Moritz Lenz <>
    Tim Nelson <>
    Daniel Ruoso <>
    Dave Rolsky <>


    Created: 19 Mar 2009 extracted from S29-functions.pod and S16-IO.pod
    Last Modified: 9 Sep 2009
    Version: 4

The document is a draft.

If you read the HTML version, it is generated from the Pod in the pugs repository under /docs/Perl6/Spec/S32-setting-library/Temporal.pod so edit it there in the SVN repository if you would like to make changes.



The epoch used in Perl 6 to represent time instants is the International Atomic Time - TAI - which is independent of calendars, timezones as well as leap seconds. Of course Perl can't go beyond the machine to get a real TAI value, but it should perform any platform-specific transformation to give you the most precise value it can for the TAI.

 our Instant sub time()

Returns a TAI epoch value for the current time.


Duration objects describe an amount of time, it's the fundamental type for time math. The base Duration object is only TAI-seconds aware, but if you use its constructor with any other parameters it will delegate to Gregorian::Duration in order to make the most common cases easier.

The following attribute is declared:


Returns the amount of TAI seconds described in this duration. Note that usually you shouldn't be doing math with the result of .tai for different datetime and duration objects. The result of .tai might also be an estimated value for Duration types that depend on an anchor date (i.e.: 1 month).


Every DateTime needs to follow the rules of a given calendar. The default is the Gregorian calendar, but several other calendars exist in the real world.

The current default calendar is stored in $*CALENDAR.

method calendartime($epoch = time(), *%options)
multi calendartime($epoch = time(), $calendar = $*CALENDAR, *%options)

Returns a DateTime object in the current calendar for the given TAI epoch time. Each calendar type might accept different options.

Note that simply changing the current calendar is not magically going to make any code portable to different calendars. The code using it should either use only the methods in the generic Calendar and DateTime classes, or special case for the known Calendars.

method formatter is rw

The default formatter object used for DateTime objects in this calendar.


This is a generic class used to identify all calendars that observe the time zones. Not all calendars are time-zone observant. One way or another, two multi subs will be available that depend on a time-zone observant calendar. They will fail if you try to call them with a non-tz calendar.

This class also implies that the calendartime method might receive a time-zone named parameter.

method gmtime($epoch = time(), *%options )
multi gmtime($epoch = time(), $calendar = $*CALENDAR, *%options)

Returns a DateTime object in the GMT timezone, considering $epoch to be TAI. Same as:

 calendartime($epoch, $calendar, :time-zone<GMT>)
method localtime($epoch = time(), *%options )
multi localtime($epoch = time(), $calendar = $*CALENDAR, *%options)

Returns a DateTime object in the local timezone taken from the system, considering $epoch to be TAI. Same as:

 calendartime($epoch, $calendar, :time-zone<local>)


The generic DateTime class specifies the basic operations that should be possible independent of the Calendar being used, and are, therefore, considerably restricted.

In order to make it easier to deal with the most common scenario, the contructor of the bare DateTime type will delegate to Gregorian::DateTime.

It defines the following attributes.


The object that will stringify this specific object.


Returns the calendar that governs this datetime.

And the following methods


Returns the TAI value for this specific datetime, useful for inter-calendar comparison and conversion.


This is the base for the entire time-zone database with the complete information about daylight-saving-time and other variations that can happen.

This should be a straight port from perl 5 DateTime::TimeZone module.


Also known as the "civil" calendar. This is the calendar used in most of the world, specially in the western countries.


The gregorian DateTime declares the following additional attributes.


The class provides a constructor which either accepts the attributes as named parameters, or takes a single string value with a date/time value. If both the string and named parameters are passed, the named parameters take precedence. The string value can have any of the following forms, all taken from ISO 8601:

'2010-04-01 00:00' Separate date and time.
'2010-04-01T00:00' Combined date and time.
'2010-04-01' Just the date. Assumes 00:00.
'2010-04' Just the year and month. Assumes the first of that month.
'2010' Just the year. Assumes January.
'2010-091' Year and three-digit day-of-year.
'01:02:03' Time. Assumes today.
'01:02' Hours and minutes. Assumes 00 seconds.
'01' Just hours.
'01:02:03Z' UTC time. All time designations can end in a 'Z'.

The following methods provide additional information:


By default, a Gregorian::DateTime object stringifies to something of the form '2010-04-01T00:00'.


The gregorian Duration declares the following attributes.


As with Gregorian::DateTime, this class provides a constructor which either accepts the attributes as named parameters, or takes a single string value with a duration value, and here also the named parameters take precedence. The string value can have any of the following forms:


The letters stand for 'period', 'years', 'months', 'days', 'time', 'hours', 'minutes', and 'seconds', respectively. The 1's stand in for any non-negative integer, which may be arbitrarily large.

The above format with any one of the letter/digit groups omitted.

The omitted groups are assumed to be 0. The following exceptions hold: the 'P' may not be removed. The 'T' may be removed, but keep in mind that it's used to disambiguate between months and minutes.

Any of the above with the least significant specified value a fractional value.

'P0.5Y' would mean 'half a year', for example.

A duration on the form 'P2010-04-01T00:00:00'

Where any number of the least significant values may be omitted. By contrast with the above forms, this form doesn't allow values to exceed their "carry-over point", so a month value may not be '13' and an hour value may not be '25', for example.

By default, a Gregorian::DateTime object stringifies to the second format given above, and omits letter/digit groups where the number is 0.


Please post errors and feedback to perl6-language. If you are making a general laundry list, please separate messages by topic.