Author: dolmen
Date: 2010-07-20 23:51:26 +0200 (Tue, 20 Jul 2010)
New Revision: 31776
Modified:
docs/Perl6/Spec/S32-setting-library/Temporal.pod
Log:
[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 = DateTime.new($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
- $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.
@@ -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 # 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
@@ -290,3 +270,4 @@
Daniel Ruoso <dan...@ruoso.com>
Dave Rolsky <auta...@urth.org>
Matthew (lue) <rnd...@gmail.com>
+ Olivier Mengué <dol...@cpan.org>
