TITLE

DRAFT: Synopsis 32: Setting Library - Temporal

AUTHORS

    The authors of the related Perl 5 docs
    Rod Adams <rod@rodadams.net>
    Larry Wall <larry@wall.org>
    Aaron Sherman <ajs@ajs.com>
    Mark Stosberg <mark@summersault.com>
    Carl Mäsak <cmasak@gmail.com>
    Moritz Lenz <moritz@faui2k3.org>
    Tim Nelson <wayland@wayland.id.au>
    Daniel Ruoso <daniel@ruoso.com>
    Dave Rolsky <autarch@urth.org>

VERSION

    Created: 19 Mar 2009 extracted from S29-functions.pod and S16-IO.pod
    Last Modified: 8 Jan 2010
    Version: 5

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.

Roles

Instant

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

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:

tai

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

Calendar

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 roles, or special case for the known Calendars.

method formatter is rw

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

Calendar::TimeZoneObservant

This is a generic role used to identify all calendars that observe the time zones. Not all calendars are time-zone observants. 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 role 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'))

DateTime

The generic DateTime role 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 constructor of the bare DateTime type will delegate to Gregorian::DateTime.

It defines the following attributes.

formatter

The object that will stringify this specific object.

calendar

Returns the calendar that governs this datetime.

And the following methods

tai

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

TimeZone

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.

TimeRange

This object represents a given period of time, and may exclude either endpoint. It might be composed by:

  $datetime1 .. $datetime2
  $datetime1 ^.. $datetime2
  $datetime1 ..^ $datetime2

These may be iterated, but only on seconds. To iterate with some other duration, you may use the series operator to produce a series of datetimes:

  $datetime1 ... *+$duration, $datetime2

Gregorian::Calendar

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

Gregorian::DateTime

The gregorian DateTime declares the following additional attributes.

year

month

day

minute

second

nanosecond

time-zone

The following methods provide additional information

week-of-year

day-of-week

week-of-month

year-of-week

Gregorian::Duration

The gregorian Duration declares the following attributes.

year

month

day

minute

second

nanosecond

Additions

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