Author: Kodi
Date: 2010-07-11 19:56:33 +0200 (Sun, 11 Jul 2010)
New Revision: 31627
Modified:
docs/Perl6/Spec/S32-setting-library/Temporal.pod
Log:
[S32/Temporal] Changed to use a different way of specifying time zones, which
is hopefully saner than my last proposal.
Modified: docs/Perl6/Spec/S32-setting-library/Temporal.pod
===================================================================
--- docs/Perl6/Spec/S32-setting-library/Temporal.pod 2010-07-11 17:09:44 UTC
(rev 31626)
+++ docs/Perl6/Spec/S32-setting-library/Temporal.pod 2010-07-11 17:56:33 UTC
(rev 31627)
@@ -15,8 +15,8 @@
Created: 19 Mar 2009
- Last Modified: 8 Apr 2010
- Version: 7
+ Last Modified: 11 July 2010
+ Version: 8
The document is a draft.
@@ -88,11 +88,12 @@
All four of the aforementioned forms of C<new> accept two additional named
arguments. C<:formatter> is a callable object that takes a C<DateTime> and
returns a string. The default formatter creates an ISO 8601 timestamp (see
-below). C<:timezone> is a callable object that takes a C<DateTime> and
-returns a two-element list giving the difference from UTC in (possibly both
-negative, but not of opposite signs) hours and minutes. Alternatively,
-C<:timezone> can be a two-element list, which is interpreted as a static
-offset from UTC. The default time zone is C<(0, 0)> (i.e., UTC).
+below). C<:timezone> is a callable object that takes a C<DateTime> to
+convert and a C<Bool> that specifies the direction of the conversion: to
+UTC if true, from UTC if false. The C<:timezone> signifies the necessary
+conversion by returning an integer giving the difference from UTC in
+seconds. Alternatively, C<:timezone> can be a number, which is interpreted
+as a static offset from UTC. The default time zone is C<0> (i.e., UTC).
A shorter way to send in date and time information is to provide a
single string with a full ISO 8601 date and time. The example from above
@@ -100,14 +101,16 @@
my $moonlanding = DateTime.new( '1969-07-16T20:17:00Z' ); # UTC time
-The general form is C<[date]T[time][offset]>, with [date] given as
-C<YYYY-MM-DD> and [time] given as C<hh:mm:ss>. The final C<Z> is a short
+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. (Note that while this form of C<new>
accepts all of C<+0000>, C<-0000>, and C<Z>, the default formatter for
-C<DateTime> always expresses UTC as C<Z>.) The general notation for the C<<
-<offset> >> is C<+hhmm> or C<-hhmm>. As before, a C<:formatter> argument is
-permitted. The C<:timezone>, if not supplied, is assumed to be a static
-offset equal to the offset in the given timestamp.
+C<DateTime> always expresses UTC as C<Z>.) The general notation for the
+C<[offset]> is C<+hhmm> or C<-hhmm>. The time zone of the new object is
+assumed to be a static offset equal to the C<[offset]>. The C<[offset]> is
+optional; if omitted, a C<:timezone> argument is permitted; if this too is
+omitted, UTC is assumed. Finally, the constructor also accepts a
+C<:formatter> argument.
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
@@ -155,8 +158,8 @@
The method C<offset> returns the object's current offset from UTC: if
C<$dt.timezone> does C<Callable>, C<$dt.offset> is equivalent to
-C<$dt.timezone($dt)>; otherwise, C<$dt.offset> is equivlent to
-C<@($dt.timezone)>.
+C<$dt.timezone($dt, True)>; otherwise, C<$dt.offset> returns
+C<$dt.timezone> as is.
=head2 "Set" methods
@@ -181,9 +184,9 @@
local time zone is adjusted accordingly:
my $dt = DateTime.new('2005-02-01T15:00:00+0900');
- say $dt.hour; # 15
- $dt.timezone = (6, 0);
- say $dt.hour; # 12
+ say $dt.hour; # 15
+ $dt.timezone = 6 * 60 * 60; # 6 hours ahead of UTC
+ say $dt.hour; # 12
The C<truncate> method allows you to "clear" a number of time values
below a given resolution:
@@ -197,6 +200,9 @@
Monday of the week in which it occurs, and the time components are all
set to 0.
+For the convenience of method chaining, C<set> and C<truncate> return the
+calling object.
+
=head1 Date
C<Date> objects are immutable and represent a day without a time component.
