Temporal spec draft

=encoding utf8

=head1 TITLE

DRAFT: Synopsis 32: Setting Library - Temporal

=head1 AUTHORS

    Carl Mäsak <cmasak@gmail.com>
    Martin Berends <mberends@autoexec.demon.nl>
    (but see FOOTNOTE at bottom)

=head1 VERSION

    Created: 19 Mar 2009

    Last Modified: 8 Apr 2010
    Version: 7

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 -- if you
would like to make changes to the document, that's the place to look.

=head1 Time and time again

Two chief aspects of a Perl 6 synopsis seem to contribute to it having some
extra volatility: how far it sits from the rest of the data model of the
language, and how everyday the topic in question is. C<S32> has always been
volatile for these reasons; C<S32::Temporal> doubly so.

The truth is that while there are many interests to satisfy in the case of a
C<Temporal> module, and many details to take into account, there's also the
danger of putting too much in. Therefore, Perl 6's C<Temporal> module takes
the C<DateTime> module on CPAN as a starting point, adapts it to the Perl 6
OO system, and boils it down to bare essentials.

One of the unfortunate traditions that Perl 6 aims to break is that of having a
set of "core" modules which could better serve the community on CPAN than in
the Perl core. For this reason, this module doesn't handle all the world's
time zones, locales, date formatters or calendars. Instead, it handles a number
of "natural" operations well enough for most people to be happy, and shows how
those who want more than that can load a module, or roll their own variants.
Put differently, the below are the aspects of time that are felt to be stable
enough to belong in the core.

=head1 C<time>

Returns an C<Instant> representing the current time as measured in atomic
second since the epoch, suitable for feeding to some of the C<DateTime>
constructors.

=head1 C<DateTime>

A C<DateTime> object describes the time as it would appear on someone's
calendar and someone's clock. You can create a C<DateTime> object from the
C<Instant> returned by the C<time> function:

    my $now = DateTime.from_epoch(time);

This is such a common use case, that there's a C<DateTime.now> constructor
that does this for you:

    my $now = DateTime.now();

If you're interested in the current date but not the time, you can use
the C<today> method instead:

    my $today = DateTime.today();

This has the same effect as doing C<DateTime.now().truncate('day')>; see
'"Set" methods' below.

General dates can be specified through the C<new> constructor:

    my $moonlanding = DateTime.new( :year(1969), :month(7), :day(16),
                                    :hour(20), :minute(17) ); # UTC time

The full list of named arguments is as follows:

    :year       required
    :month      defaults to 1   range 1..12
    :day        defaults to 1   range 1..31
    :hour       defaults to 0   range 0..23
    :minute     defaults to 0   range 0..59
    :second     defaults to 0   range 0..61
    :nanosecond defaults to 0
    :timezone   defaults to '+0000' (UTC)
    :formatter  defaults to an iso8601 formatter, see below

A shorter way to send in date and time information to is providing a single
string with a full ISO8601 date and time. The example from above would then
be

    my $moonlanding = DateTime.new( '1969-07-16T20:17:00Z' ); # UTC time

The general form is C<< <date>T<time><offset> >>, with C<< <date> >> given
as C<YYYY-MM-DD> and C<< <time> >> given as C<hh:mm:ss>.

The final C<Z> is a short form for C<+0000>, meaning UTC time. The general
notation for the C<< <offset> >> is C<+hhmm> or C<-hhmm>.

With all the above constructors, if you attempt to pass in values that are
outside of the ranges specified in the list above, you'll get an exception.
An exception will also be thrown if the particular day doesn't exist in that
month (for example April 31st) or in that non-leap year (for example February
29th 1996). By default, no such checking is done against leap seconds. This
class also explicitly does not check against ambiguous or invalid local times
caused by Daylight Saving Time.

If you pass in a C<:nanosecond> value greater or equal to one billion (1e9),
it will be normalized, and the excess seconds will be transferred to the
C<:second> value.

=head2 "Get" methods

There are methods C<year>, C<month>, C<day>, C<hour>, C<minute>, C<second>,
and C<nanosecond>, giving you the corresponding values of the C<DateTime>
object. The C<day> method also has the synonym C<day_of_month>.

The method C<week> returns two values, the I<week year> and I<week number>.
(These are also available through the methods C<week_year> and C<week_number>,
respectively.) The first week of the year is defined by ISO as the one which
contains the fourth day of January. Thus, dates early in January often end
up in the last week of the prior year, and similarly, the final few days of
December may be placed in the first week of the next year.

There's a C<day_of_week> method, which returns the day of the week as a number
1..7, with 1 being Monday and 7 being Sunday.

The C<weekday_of_month> method returns a number 1..5 indicating the number of
times a particular weekday has occurred so far during that month, the day
itself included. For example, June 9, 2003 is the second Monday of the month,
and so this method returns 2 for that day.

The C<quarter> method returns the quarter of the year, a value between 1 and 4.
The C<day_of_quarter> method returns the day of the quarter.

The C<day_of_year> method returns the day of the year, a value between 1 and
366.

The method C<fractional_second> returns the second as a real number, with the
fractional part coming from the C<nanosecond> value. The methods
C<millisecond>, C<microsecond>, and C<nanosecond> return the nanosecond part
in the corresponding unit, rounded to an integer.

The following methods work as a sort of formatting methods:

    $dt.ymd('-')    (also $dt.date('-'))
    $dt.mdy('-')
    $dt.dmy('-')
    
    $dt.hms(':')    (also $dt.time(':'))

The single argument of each of those methods is optional, but the above shows
the defaults: C<'-'> for dates and C<':'> for times.

The C<time_zone> method returns the C<DateTime::TimeZone> object for the
C<DateTime> object. The method C<offset> returns the offset from UTC, in
seconds, of the C<DateTime> object according to the time zone.

The C<formatter> method returns the formatter for the C<DateTime> object.

=head2 "Set" methods

To set the the day of a C<DateTime> object to something, just assign to its
public accessor:

    $dt.day = 15;

The same methods exists for all the values you can set in the constructor:
C<year>, C<month>, C<day>, C<hour>, C<minute>, C<second>, C<nanosecond>,
C<time_zone> and C<formatter>. Also, there's a C<set> method, which accepts
all of these as named arguments, allowing several values to be set at once:

    $dt.set( :year(2014), :month(12), :day(25) );

Just as with the C<new> method, validation is performed on the resulting
values, and an exception is thrown if the result isn't a sensible date and
time.

If you use the C<time_zone> public accessor to adjust the time zone, the
local time zone is adjusted accordingly:

    my $dt = DateTime.new('2005-02-01T15:00:00+0900');
    say $dt.hour;     # 15
    $dt.time_zone = '+0600';
    say $dt.hour;     # 12

The C<truncate> method allows you to "clear" a number of time values below
a given resolution:

    $dt.truncate( :to<hour> ); # clears minutes, seconds, and nanoseconds

The time units are "cleared" in the sense that they are set to their inherent
defaults: 1 for months and days, 0 for the time components.

If you pass in C<< :to<week> >>, the C<DateTime> object is set to the Monday
of the week in which it occurs, and the time components are all set to 0.

=head1 Additions

Please post errors and feedback to C<perl6-language>. If you are making
a general laundry list, please separate messages by topic. Please try to
keep bikeshedding down.

=head1 FOOTNOTE

The indirect contribution of the previous authors prevents the authors of
the current rewrite to fail to mention:

    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>
    Matthew (lue) <rnddim@gmail.com>