Author: mberends Date: 2010-04-12 13:01:15 +0200 (Mon, 12 Apr 2010) New Revision: 30364
Modified: docs/Perl6/Spec/S32-setting-library/Temporal.pod Log: [Temporal.pod] remove invalid markup that may have blocked updating of the HTML version online, and minor cosmetic changes. Modified: docs/Perl6/Spec/S32-setting-library/Temporal.pod =================================================================== --- docs/Perl6/Spec/S32-setting-library/Temporal.pod 2010-04-12 05:42:57 UTC (rev 30363) +++ docs/Perl6/Spec/S32-setting-library/Temporal.pod 2010-04-12 11:01:15 UTC (rev 30364) @@ -1,4 +1,3 @@ - =encoding utf8 =head1 TITLE @@ -9,7 +8,7 @@ Carl Mäsak <cma...@gmail.com> Martin Berends <mbere...@autoexec.demon.nl> - (but see FOOTNOTE at bottom) + (and others named in FOOTNOTE at bottom) =head1 VERSION @@ -21,47 +20,49 @@ The document is a draft. If you read the HTML version, it is generated from the Pod in the pugs -repository under /docs/Perl6/Spec/S32-setting-library/Temporal.pod -- if you -would like to make changes to the document, that's the place to look. +repository under /docs/Perl6/Spec/S32-setting-library/Temporal.pod -- if +you would like to make changes to the document, that's the place to +look. =head1 Time and time again -Two chief aspects of a Perl 6 synopsis seem to contribute to it having some -extra volatility: how far it sits from the rest of the data model of the -language, and how everyday the topic in question is. C<S32> has always been -volatile for these reasons; C<S32::Temporal> doubly so. +Two chief aspects of a Perl 6 synopsis seem to contribute to it having +some extra volatility: how far it sits from the rest of the data model +of the language, and how everyday the topic in question is. C<S32> has +always been volatile for these reasons; C<S32::Temporal> doubly so. -The truth is that while there are many interests to satisfy in the case of a -C<Temporal> module, and many details to take into account, there's also the -danger of putting too much in. Therefore, Perl 6's C<Temporal> module takes -the C<DateTime> module on CPAN as a starting point, adapts it to the Perl 6 -OO system, and boils it down to bare essentials. +The truth is that while there are many interests to satisfy in the case +of a C<Temporal> module, and many details to take into account, there's +also the danger of putting too much in. Therefore, Perl 6's C<Temporal> +module takes the C<DateTime> module on CPAN as a starting point, adapts +it to the Perl 6 OO system, and boils it down to bare essentials. -One of the unfortunate traditions that Perl 6 aims to break is that of having a -set of "core" modules which could better serve the community on CPAN than in -the Perl core. For this reason, this module doesn't handle all the world's -time zones, locales, date formatters or calendars. Instead, it handles a number -of "natural" operations well enough for most people to be happy, and shows how -those who want more than that can load a module, or roll their own variants. -Put differently, the below are the aspects of time that are felt to be stable -enough to belong in the core. +One of the unfortunate traditions that Perl 6 aims to break is that of +having a set of "core" modules which could better serve the community on +CPAN than in the Perl core. For this reason, this module doesn't handle +all the world's time zones, locales, date formatters or calendars. +Instead, it handles a number of "natural" operations well enough for +most people to be happy, and shows how those who want more than that can +load a module, or roll their own variants. Put differently, the below +are the aspects of time that are felt to be stable enough to belong in +the core. =head1 C<time> -Returns an C<Instant> representing the current time as measured in atomic -second since the epoch, suitable for feeding to some of the C<DateTime> -constructors. +Returns an C<Instant> representing the current time as measured in +atomic seconds since the Unix epoch, suitable for feeding to some of the +C<DateTime> constructors. =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 the -C<Instant> returned by the C<time> function: +calendar and someone's clock. You can create a C<DateTime> object from +the C<Instant> returned by the C<time> function: my $now = DateTime.from_epoch(time); -This is such a common use case, that there's a C<DateTime.now> constructor -that does this for you: +This is such a common use case, that there's a C<DateTime.now> +constructor that does this for you: my $now = DateTime.now(); @@ -89,30 +90,30 @@ :timezone defaults to '+0000' (UTC) :formatter defaults to an iso8601 formatter, see below -A shorter way to send in date and time information to is providing a single -string with a full ISO8601 date and time. The example from above would then -be +A shorter way to send in date and time information to is providing a +single string with a full ISO8601 date and time. The example from above +would then be my $moonlanding = DateTime.new( '1969-07-16T20:17:00Z' ); # UTC time -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 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 form for C<+0000>, meaning UTC time. The general -notation for the C<< <offset> >> is C<+hhmm> or C<-hhmm>. +The final C<Z> is a short form for C<+0000>, meaning UTC time. The +general notation for the C<< <offset> >> is C<+hhmm> or C<-hhmm>. -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 exception. -An exception will also be thrown if the particular day doesn't exist in that -month (for example April 31st) or in that non-leap year (for example February -29th 2006). By default, no such checking is done against leap seconds. This -class also explicitly does not check against ambiguous or invalid local times -caused by Daylight Saving Time. +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 +exception. An exception will also be thrown if the particular day +doesn't exist in that month (for example April 31st) or in that non-leap +year (for example February 29th 2006). By default, no such checking is +done against leap seconds. This class also explicitly does not check +against ambiguous or invalid local times caused by Daylight Saving Time. =head2 "Get" methods -There are methods C<year>, C<month>, C<day>, C<hour>, C<minute>, -and C<second>, giving you the corresponding values of the C<DateTime> +There are methods C<year>, C<month>, C<day>, C<hour>, C<minute>, and +C<second>, giving you the corresponding values of the C<DateTime> object. The C<day> method also has the synonym C<day_of_month>. The method C<week> returns two values, the I<week year> and I<week number>. @@ -122,19 +123,19 @@ up in the last week of the prior year, and similarly, the final few days of December may be placed in the first week of the next year. -There's a C<day_of_week> method, which returns the day of the week as a number -1..7, with 1 being Monday and 7 being Sunday. +There's a C<day_of_week> method, which returns the day of the week as a +number 1..7, with 1 being Monday and 7 being Sunday. -The C<weekday_of_month> method returns a number 1..5 indicating the number of -times a particular weekday has occurred so far during that month, the day -itself included. For example, June 9, 2003 is the second Monday of the month, -and so this method returns 2 for that day. +The C<weekday_of_month> method returns a number 1..5 indicating the +number of times a particular weekday has occurred so far during that +month, the day itself included. For example, June 9, 2003 is the second +Monday of the month, and so this method returns 2 for that day. -The C<quarter> method returns the quarter of the year, a value between 1 and 4. -The C<day_of_quarter> method returns the day of the quarter. +The C<quarter> method returns the quarter of the year, a value between 1 +and 4. The C<day_of_quarter> method returns the day of the quarter. -The C<day_of_year> method returns the day of the year, a value between 1 and -366. +The C<day_of_year> method returns the day of the year, a value between 1 +and 366. The method C<whole_second> returns the second truncated to an integer. @@ -146,8 +147,8 @@ $dt.hms(':') (also $dt.time(':')) -The single argument of each of those methods is optional, but the above shows -the defaults: C<'-'> for dates and C<':'> for times. +The single argument of each of those methods is optional, but the above +shows the defaults: C<'-'> for dates and C<':'> for times. The C<time_zone> method returns the C<DateTime::TimeZone> object for the C<DateTime> object. The method C<offset> returns the offset from UTC, in @@ -157,21 +158,22 @@ =head2 "Set" methods -To set the the day of a C<DateTime> object to something, just assign to its -public accessor: +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<time_zone> 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: +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<time_zone> 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. +values, and an exception is thrown if the result isn't a sensible date +and time. If you use the C<time_zone> public accessor to adjust the time zone, the local time zone is adjusted accordingly: @@ -181,16 +183,17 @@ $dt.time_zone = '+0600'; say $dt.hour; # 12 -The C<truncate> method allows you to "clear" a number of time values below -a given resolution: +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. +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. -If you pass in C<< :to<week> >>, the C<DateTime> object is set to the Monday -of the week in which it occurs, and the time components are all set to 0. +If you pass in C<< :to<week> >>, the C<DateTime> object is set to the +Monday of the week in which it occurs, and the time components are all +set to 0. =head1 Additions @@ -200,8 +203,8 @@ =head1 FOOTNOTE -The indirect contribution of the previous authors prevents the authors of -the current rewrite to fail to mention: +The authors of the current rewrite want to mention, with thanks, the +indirect contribution made by the previous authors: The authors of the related Perl 5 docs Rod Adams <r...@rodadams.net>