Author: lue
Date: 2010-04-03 20:18:43 +0200 (Sat, 03 Apr 2010)
New Revision: 30293
Modified:
docs/Perl6/Spec/S32-setting-library/Temporal.pod
Log:
[P6 Spec] completely changed S32::Temporal
Modified: docs/Perl6/Spec/S32-setting-library/Temporal.pod
===
--- docs/Perl6/Spec/S32-setting-library/Temporal.pod2010-04-03 13:03:58 UTC
(rev 30292)
+++ docs/Perl6/Spec/S32-setting-library/Temporal.pod2010-04-03 18:18:43 UTC
(rev 30293)
@@ -17,12 +17,13 @@
Tim Nelson
Daniel Ruoso
Dave Rolsky
+Matthew (lue)
=head1 VERSION
Created: 19 Mar 2009 extracted from S29-functions.pod and S16-IO.pod
-Last Modified: 18 Feb 2010
+Last Modified: 2 Apr 2010
Version: 6
The document is a draft.
@@ -31,224 +32,144 @@
repository under /docs/Perl6/Spec/S32-setting-library/Temporal.pod so edit it
there in
the SVN repository if you would like to make changes.
-=head1 Roles
+=head1 Temporal
-=head2 Instant
+Time is just a jumbled iTem.
-The epoch used in Perl 6 to represent time instants is the
-International Atomic Time - TAI - which is independent of calendars,
-timezones as well as leap seconds. Of course Perl can't go beyond the
-machine to get a real TAI value, but it should perform any
-platform-specific transformation to give you the most precise value it
-can for the TAI.
+Temporal is divided into two parts: date and time.
- our Instant sub time()
+=head2 Time
-Returns a TAI epoch value for the current time.
+Time is called upon as such:
-=head2 Duration
-
-Duration objects describe an amount of time, it's the fundamental type
-for time math. The base Duration object is only TAI-seconds aware, but
-if you use its constructor with any other parameters it will delegate
-to Gregorian::Duration in order to make the most common cases easier.
-
-The following attribute is declared:
-
=over
-=item tai
+=item Time.new($timesystem = $*CLOCK, $time = $*NOW)
-Returns the amount of TAI seconds described in this duration. Note
-that usually you shouldn't be doing math with the result of .tai for
-different datetime and duration objects. The result of .tai might also
-be an estimated value for Duration types that depend on an anchor date
-(i.e.: 1 month).
+Creates a new Time object. $timesystem is what clock you wish to use. If
unspecified, whatever is in $*CLOCK is used. $time specifies the $time, it
defaults to what is in $*NOW. What you enter in $time should match the format
that $timesystem is in. $*NOW and $*CLOCK should be specified in the same
format (i.e., if $*CLOCK is 'unixepoch', $*NOW should be something like
127666216.432)
+Possible (string!) values for $timesystem (and therefore $*CLOCK) are:
-=back
-
-=head2 Calendar
-
-Every DateTime needs to follow the rules of a given calendar. The
-default is the Gregorian calendar, but several other calendars exist
-in the real world.
-
-The current default calendar is stored in $*CALENDAR.
-
=over
-=item method calendartime($epoch = time(), *%options)
+=item * 12hour
-=item multi calendartime($epoch = time(), $calendar = $*CALENDAR, *%options)
+=item * 24hour (this and 12hour are essentialy the same system, but for
simplicity they are separate)
-Returns a DateTime object in the current calendar for the given TAI
-epoch time. Each calendar type might accept different options.
+=item * hextime
-Note that simply changing the current calendar is not magically going
-to make any code portable to different calendars. The code using it
-should either use only the methods in the generic Calendar and
-DateTime roles, or special case for the known Calendars.
+=item * unixepoch
-=item method formatter is rw
+=item * tai
-The default formatter object used for DateTime objects in this
-calendar.
-
=back
-=head2 Calendar::TimeZoneObservant
+If the time system you want is not up on the list, you are at the mercy of the
implementation (which can, of course, add in rarer time systems) and/or
available libraries and other addons. A shortcut to the time (in the default as
defined by $*CLOCK) is through the $*TIME variable.
-This is a generic role used to identify all calendars that observe the
-time zones. Not all calendars are time-zone observants. One way or
-another, two multi subs will be available that depend on a time-zone
-observant calendar. They will fail if you try to call them with a
-non-tz calendar.
+=item Time.convert($convertto = $*CLOCK)
-This role also implies that the calendartime method might receive a
-time-zone named parameter.
+returns the time converted to the time system specified in $convertto. If you
were to call convert(), then it would default to what's in $*CLOCK
-=over
+=item Time.format($formatto)
-=item method gmtime($epoch = time(), *%options )
+returns the time formatted to the way specified in $formatto. If the time has
no options for formatting (for example hextime can be either 3_A0_9 or .3A
