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>
