Not a member of Pastebin yet?
Sign Up,
it unlocks many cool features!
- =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>
Add Comment
Please, Sign In to add comment