Author: dolmen
Date: 2010-07-20 23:51:26 +0200 (Tue, 20 Jul 2010)
New Revision: 31776

[S32/Temporal] Make DateTime immutable.

Modified: docs/Perl6/Spec/S32-setting-library/Temporal.pod
--- docs/Perl6/Spec/S32-setting-library/Temporal.pod    2010-07-20 21:11:32 UTC 
(rev 31775)
+++ docs/Perl6/Spec/S32-setting-library/Temporal.pod    2010-07-20 21:51:26 UTC 
(rev 31776)
@@ -15,8 +15,8 @@
     Created: 19 Mar 2009
-    Last Modified: 15 Jul 2010
-    Version: 14
+    Last Modified: 20 Jul 2010
+    Version: 15
 The document is a draft.
@@ -67,7 +67,11 @@
 =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 an
+calendar and someone's clock.
+C<DateTime> objects are immutables.
+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.
@@ -94,7 +98,11 @@
 Another multi exists with C<Date :date> instead of C<:year>, C<:month> and
 C<:day> (and the same defaults as listed above).
-All four of the aforementioned forms of C<new> accept two additional named
+A C<DateTime> can also be created by modifying an existing object:
+    my $moonlanding_anniv =$moonlanding, :year(2010));
+All five 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
@@ -178,38 +186,11 @@
 C<$dt.timezone($dt, True)>; otherwise, C<$dt.offset> returns
 C<$dt.timezone> as is.
-=head2 "Set" methods
+The C<truncate> method returns a new object where a number of time values
+have been cleared below a given resolution:
-To set the the day of a C<DateTime> object to something, just assign to
-its public accessor:
+    $dt2 = $dt.truncate( :to<hour> ); # clears minutes and seconds
-    $ = 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 ='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.
@@ -217,9 +198,6 @@
 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.
@@ -268,6 +246,8 @@
     $d + 3                      #'2010-12-27')
     3  + $d                     #'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
@@ -290,3 +270,4 @@
     Daniel Ruoso <>
     Dave Rolsky <>
     Matthew (lue) <>
+    Olivier Mengué <>

Reply via email to