Author: Kodi
Date: 2010-07-21 02:12:24 +0200 (Wed, 21 Jul 2010)
New Revision: 31777
Modified:
docs/Perl6/Spec/S32-setting-library/Temporal.pod
Log:
[S32/Temporal] Reverted DateTime back to being mutable. I think we ought to
make a big change like this only after reaching some kind of consensus to do
so, not least because I just implemented a lot of mutating methods!
Note that += and friends need only the *container* on the LHS to be mutable,
not the value?\226?\128?\148'$x += 1' should be allowed whether $x holds an
Int, a Date, or a DateTime.
Modified: docs/Perl6/Spec/S32-setting-library/Temporal.pod
===================================================================
--- docs/Perl6/Spec/S32-setting-library/Temporal.pod 2010-07-20 21:51:26 UTC
(rev 31776)
+++ docs/Perl6/Spec/S32-setting-library/Temporal.pod 2010-07-21 00:12:24 UTC
(rev 31777)
@@ -16,7 +16,7 @@
Created: 19 Mar 2009
Last Modified: 20 Jul 2010
- Version: 15
+ Version: 16
The document is a draft.
@@ -67,11 +67,7 @@
=head1 C<DateTime>
A C<DateTime> object describes the time as it would appear on someone's
-calendar and someone's clock.
-
-C<DateTime> objects are immutables.
-
-You can create a C<DateTime> object from an
+calendar and someone's clock. You can create a C<DateTime> object from an
C<Instant> or from an C<Int>; in the latter case, the argument is
interpreted as POSIX time.
@@ -98,11 +94,7 @@
Another multi exists with C<Date :date> instead of C<:year>, C<:month> and
C<:day> (and the same defaults as listed above).
-A C<DateTime> can also be created by modifying an existing object:
-
- my $moonlanding_anniv = DateTime.new($moonlanding, :year(2010));
-
-All five of the aforementioned forms of C<new> accept two additional named
+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> to
@@ -186,11 +178,38 @@
C<$dt.timezone($dt, True)>; otherwise, C<$dt.offset> returns
C<$dt.timezone> as is.
-The C<truncate> method returns a new object where a number of time values
-have been cleared below a given resolution:
+=head2 "Set" methods
- $dt2 = $dt.truncate( :to<hour> ); # clears minutes and seconds
+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<timezone> 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<timezone> 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.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:
+
+ $dt.truncate( :to<hour> ); # clears minutes and seconds
+
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.
@@ -198,6 +217,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.
@@ -246,8 +268,6 @@
$d + 3 # Date.new('2010-12-27')
3 + $d # Date.new('2010-12-27')
-As temporal objects are immutable, += -= ... do not work.
-
=head1 Additions
Please post errors and feedback to C<perl6-language>. If you are making
