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