Author: masak
Date: 2010-07-22 23:54:10 +0200 (Thu, 22 Jul 2010)
New Revision: 31789
Modified:
docs/Perl6/Spec/S32-setting-library/Temporal.pod
Log:
[S32] DateTime immutable, leap seconds validation
The rest of this message is from Kodi++, who prepared the combined
spec/Rakudo patch:
There are two major changes here: DateTimes are now immutable and
DateTime constructors now validate leap seconds.
tai-utc should provide a hash, not a subroutine, but this doesn't
work when Rakudo is compiled.
It shouldn't be too hard to write a Perl 5 script, to be run as
part of Rakudo's build process, that automatically updates the
leap-second table in tai-utc.pm.
I haven't run DateTime-strftime.t because ++supernovus is moving
strftime out of Rakudo, and hence DateTime-strftime.t out of
pugs.
Modified: docs/Perl6/Spec/S32-setting-library/Temporal.pod
===
--- docs/Perl6/Spec/S32-setting-library/Temporal.pod2010-07-22 19:08:46 UTC
(rev 31788)
+++ docs/Perl6/Spec/S32-setting-library/Temporal.pod2010-07-22 21:54:10 UTC
(rev 31789)
@@ -15,8 +15,8 @@
Created: 19 Mar 2009
-Last Modified: 20 Jul 2010
-Version: 16
+Last Modified: 21 Jul 2010
+Version: 17
The document is a draft.
@@ -66,10 +66,10 @@
=head1 CDateTime
-A CDateTime object describes the time as it would appear on someone's
-calendar and someone's clock. You can create a CDateTime object from an
-CInstant or from an CInt; in the latter case, the argument is
-interpreted as POSIX time.
+A CDateTime object, which is immutable, describes a moment in time as it
+would appear on someone's calendar and someone's clock. You can create a
+CDateTime object from an CInstant or from an CInt; in the latter
+case, the argument is interpreted as POSIX time.
my $now = DateTime.new(now);
my $now = DateTime.new(time);
@@ -94,7 +94,7 @@
Another multi exists with CDate :date instead of C:year, C:month and
C:day (and the same defaults as listed above).
-All four of the aforementioned forms of Cnew accept two additional named
+All of the aforementioned forms of Cnew accept two additional named
arguments. C:formatter is a callable object that takes a CDateTime and
returns a string. The default formatter creates an ISO 8601 timestamp (see
below). C:timezone is a callable object that takes a CDateTime to
@@ -123,17 +123,45 @@
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 2006). 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.
+exception. An exception will also be thrown if the given day (like 31 April
+2000 or 29 February 2006) or second (like 23:59:60 on 1 January 2000)
+doesn't exist. The same checks are run when you produce an object with
+Cclone:
+my $dt = DateTime.new(:year(1999), :month(1), :day(29));
+say $dt.clone(:year(2000), :month(2)); # 2000-02-29T00:00:00Z
+say $dt.clone(:year(1999), :month(2)); # WRONG; 1999 was a common year
+
+However, this class explicitly does not check against ambiguous or invalid
+local times caused by Daylight Saving Time.
+
+To convert an object from one time zone to another, use the Cin-timezone
+method:
+
+my $dt = DateTime.new('2005-02-01T15:00:00+0900');
+say $dt.hour; # 15
+$dt = $dt.in-timezone(6 * 60 * 60); # 6 hours ahead of UTC
+say $dt.hour; # 12
+
+The Cutc method is shorthand for Cin-timezone(0).
+
+The Ctruncated-to method allows you to clear a number of time values
+below a given resolution:
+
+my $dt = DateTime.new('2005-02-01T15:20:35Z');
+say $dt.truncated-to(:hour); # 2005-02-01T15:00:00Z
+
+An argument of C:week yields an object with the date of the last Monday
+(or the same date, if it already is a Monday) and with hours, minutes, and
+seconds all set to zero:
+
+say $dt.truncated-to(:week); # 2005-01-31T00:00:00Z
+
There's one additional constructor: Cnow. It works just like
CDateTime.new(now) except that there is no positional parameter and the
C:timezone argument defaults to the system's local time zone.
-=head2 Get methods
+=head2 Accessors
There are methods Cyear, Cmonth, Cday, Chour, Cminute, Csecond,
Ctimezone, and Cformatter, giving you the corresponding values of the
@@ -178,52 +206,11 @@
C$dt.timezone($dt, True); otherwise, C$dt.offset returns
C$dt.timezone as is.
-=head2 Set methods
-
-To set the the day of a CDateTime 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: Cyear, Cmonth, Cday,
