Skip to content

HTTPS clone URL

Subversion checkout URL

You can clone with HTTPS or Subversion.

Download ZIP
Newer
Older
100644 308 lines (185 sloc) 7.881 kb
32aa64d S16: Added a few attributes to trees
wayland authored
1
2 =encoding utf8
3
9b3e978 [Spec] treat all authors equally
lwall authored
4 =head1 TITLE
32aa64d S16: Added a few attributes to trees
wayland authored
5
929419d S16/S32: Moved Temporal and Tree stuff from S16 to S32
wayland authored
6 DRAFT: Synopsis 32: Setting Library - Temporal
32aa64d S16: Added a few attributes to trees
wayland authored
7
9b3e978 [Spec] treat all authors equally
lwall authored
8 =head1 AUTHORS
9
10 The authors of the related Perl 5 docs
11 Rod Adams <rod@rodadams.net>
12 Larry Wall <larry@wall.org>
13 Aaron Sherman <ajs@ajs.com>
14 Mark Stosberg <mark@summersault.com>
15 Carl Mäsak <cmasak@gmail.com>
16 Moritz Lenz <moritz@faui2k3.org>
17 Tim Nelson <wayland@wayland.id.au>
18 Daniel Ruoso <daniel@ruoso.com>
19 Dave Rolsky <autarch@urth.org>
20
21 =head1 VERSION
22
23 Created: 19 Mar 2009 extracted from S29-functions.pod and S16-IO.pod
0af27be @masak forcibly brought all files up-to-date with upstream
authored
24 Last Modified: 9 Sep 2009
eb5c3cc @masak various tidying-up
authored
25 Version: 4
32aa64d S16: Added a few attributes to trees
wayland authored
26
0af27be @masak forcibly brought all files up-to-date with upstream
authored
27 The document is a draft.
32aa64d S16: Added a few attributes to trees
wayland authored
28
0af27be @masak forcibly brought all files up-to-date with upstream
authored
29 If you read the HTML version, it is generated from the Pod in the pugs
30 repository under /docs/Perl6/Spec/S32-setting-library/Temporal.pod so edit it there in
31 the SVN repository if you would like to make changes.
32
ac5729c @masak various small janitor changes
authored
33 =head1 Classes
0af27be @masak forcibly brought all files up-to-date with upstream
authored
34
35 =head2 Instant
36
37 The epoch used in Perl 6 to represent time instants is the
38 International Atomic Time - TAI - which is independent of calendars,
39 timezones as well as leap seconds. Of course Perl can't go beyond the
40 machine to get a real TAI value, but it should perform any
41 platform-specific transformation to give you the most precise value it
42 can for the TAI.
43
44 our Instant sub time()
45
46 Returns a TAI epoch value for the current time.
47
48 =head2 Duration
49
50 Duration objects describe an amount of time, it's the fundamental type
51 for time math. The base Duration object is only TAI-seconds aware, but
52 if you use its constructor with any other parameters it will delegate
53 to Gregorian::Duration in order to make the most common cases easier.
54
55 The following attribute is declared:
32aa64d S16: Added a few attributes to trees
wayland authored
56
57 =over
58
0af27be @masak forcibly brought all files up-to-date with upstream
authored
59 =item tai
32aa64d S16: Added a few attributes to trees
wayland authored
60
0af27be @masak forcibly brought all files up-to-date with upstream
authored
61 Returns the amount of TAI seconds described in this duration. Note
62 that usually you shouldn't be doing math with the result of .tai for
63 different datetime and duration objects. The result of .tai might also
64 be an estimated value for Duration types that depend on an anchor date
65 (i.e.: 1 month).
32aa64d S16: Added a few attributes to trees
wayland authored
66
0af27be @masak forcibly brought all files up-to-date with upstream
authored
67 =back
68
69 =head2 Calendar
70
71 Every DateTime needs to follow the rules of a given calendar. The
72 default is the Gregorian calendar, but several other calendars exist
73 in the real world.
74
75 The current default calendar is stored in $*CALENDAR.
32aa64d S16: Added a few attributes to trees
wayland authored
76
0af27be @masak forcibly brought all files up-to-date with upstream
authored
77 =over
32aa64d S16: Added a few attributes to trees
wayland authored
78
0af27be @masak forcibly brought all files up-to-date with upstream
authored
79 =item method calendartime($epoch = time(), *%options)
32aa64d S16: Added a few attributes to trees
wayland authored
80
0af27be @masak forcibly brought all files up-to-date with upstream
authored
81 =item multi calendartime($epoch = time(), $calendar = $*CALENDAR, *%options)
32aa64d S16: Added a few attributes to trees
wayland authored
82
0af27be @masak forcibly brought all files up-to-date with upstream
authored
83 Returns a DateTime object in the current calendar for the given TAI
84 epoch time. Each calendar type might accept different options.
32aa64d S16: Added a few attributes to trees
wayland authored
85
0af27be @masak forcibly brought all files up-to-date with upstream
authored
86 Note that simply changing the current calendar is not magically going
87 to make any code portable to different calendars. The code using it
88 should either use only the methods in the generic Calendar and
ac5729c @masak various small janitor changes
authored
89 DateTime classes, or special case for the known Calendars.
32aa64d S16: Added a few attributes to trees
wayland authored
90
0af27be @masak forcibly brought all files up-to-date with upstream
authored
91 =item method formatter is rw
32aa64d S16: Added a few attributes to trees
wayland authored
92
0af27be @masak forcibly brought all files up-to-date with upstream
authored
93 The default formatter object used for DateTime objects in this
94 calendar.
32aa64d S16: Added a few attributes to trees
wayland authored
95
96 =back
97
0af27be @masak forcibly brought all files up-to-date with upstream
authored
98 =head2 Calendar::TimeZoneObservant
99
ac5729c @masak various small janitor changes
authored
100 This is a generic class used to identify all calendars that observe the
101 time zones. Not all calendars are time-zone observant. One way or
0af27be @masak forcibly brought all files up-to-date with upstream
authored
102 another, two multi subs will be available that depend on a time-zone
103 observant calendar. They will fail if you try to call them with a
104 non-tz calendar.
105
ac5729c @masak various small janitor changes
authored
106 This class also implies that the C<calendartime> method might receive a
0af27be @masak forcibly brought all files up-to-date with upstream
authored
107 time-zone named parameter.
108
109 =over
110
111 =item method gmtime($epoch = time(), *%options )
112
113 =item multi gmtime($epoch = time(), $calendar = $*CALENDAR, *%options)
114
ac5729c @masak various small janitor changes
authored
115 Returns a DateTime object in the GMT timezone, considering C<$epoch> to
0af27be @masak forcibly brought all files up-to-date with upstream
authored
116 be TAI. Same as:
117
ac5729c @masak various small janitor changes
authored
118 calendartime($epoch, $calendar, :time-zone<GMT>)
0af27be @masak forcibly brought all files up-to-date with upstream
authored
119
120 =item method localtime($epoch = time(), *%options )
121
122 =item multi localtime($epoch = time(), $calendar = $*CALENDAR, *%options)
123
124 Returns a DateTime object in the local timezone taken from the system,
125 considering $epoch to be TAI. Same as:
126
ac5729c @masak various small janitor changes
authored
127 calendartime($epoch, $calendar, :time-zone<local>)
0af27be @masak forcibly brought all files up-to-date with upstream
authored
128
129 =back
130
131 =head2 DateTime
132
ac5729c @masak various small janitor changes
authored
133 The generic DateTime class specifies the basic operations that should
0af27be @masak forcibly brought all files up-to-date with upstream
authored
134 be possible independent of the Calendar being used, and are,
135 therefore, considerably restricted.
136
137 In order to make it easier to deal with the most common scenario, the
138 contructor of the bare DateTime type will delegate to
139 Gregorian::DateTime.
140
141 It defines the following attributes.
929419d S16/S32: Moved Temporal and Tree stuff from S16 to S32
wayland authored
142
0af27be @masak forcibly brought all files up-to-date with upstream
authored
143 =over
df9343d This is a very drastic revision (hopefully this won't turn into a revert...
autarch authored
144
0af27be @masak forcibly brought all files up-to-date with upstream
authored
145 =item formatter
929419d S16/S32: Moved Temporal and Tree stuff from S16 to S32
wayland authored
146
0af27be @masak forcibly brought all files up-to-date with upstream
authored
147 The object that will stringify this specific object.
929419d S16/S32: Moved Temporal and Tree stuff from S16 to S32
wayland authored
148
0af27be @masak forcibly brought all files up-to-date with upstream
authored
149 =item calendar
df9343d This is a very drastic revision (hopefully this won't turn into a revert...
autarch authored
150
0af27be @masak forcibly brought all files up-to-date with upstream
authored
151 Returns the calendar that governs this datetime.
df9343d This is a very drastic revision (hopefully this won't turn into a revert...
autarch authored
152
0af27be @masak forcibly brought all files up-to-date with upstream
authored
153 =back
df9343d This is a very drastic revision (hopefully this won't turn into a revert...
autarch authored
154
0af27be @masak forcibly brought all files up-to-date with upstream
authored
155 And the following methods
df9343d This is a very drastic revision (hopefully this won't turn into a revert...
autarch authored
156
0af27be @masak forcibly brought all files up-to-date with upstream
authored
157 =over
df9343d This is a very drastic revision (hopefully this won't turn into a revert...
autarch authored
158
0af27be @masak forcibly brought all files up-to-date with upstream
authored
159 =item tai
df9343d This is a very drastic revision (hopefully this won't turn into a revert...
autarch authored
160
0af27be @masak forcibly brought all files up-to-date with upstream
authored
161 Returns the TAI value for this specific datetime, useful for
162 inter-calendar comparison and conversion.
929419d S16/S32: Moved Temporal and Tree stuff from S16 to S32
wayland authored
163
0af27be @masak forcibly brought all files up-to-date with upstream
authored
164 =back
929419d S16/S32: Moved Temporal and Tree stuff from S16 to S32
wayland authored
165
0af27be @masak forcibly brought all files up-to-date with upstream
authored
166 =head2 TimeZone
929419d S16/S32: Moved Temporal and Tree stuff from S16 to S32
wayland authored
167
0af27be @masak forcibly brought all files up-to-date with upstream
authored
168 This is the base for the entire time-zone database with the complete
169 information about daylight-saving-time and other variations that can
170 happen.
929419d S16/S32: Moved Temporal and Tree stuff from S16 to S32
wayland authored
171
0af27be @masak forcibly brought all files up-to-date with upstream
authored
172 This should be a straight port from perl 5 DateTime::TimeZone module.
929419d S16/S32: Moved Temporal and Tree stuff from S16 to S32
wayland authored
173
0af27be @masak forcibly brought all files up-to-date with upstream
authored
174 =head2 Gregorian::Calendar
929419d S16/S32: Moved Temporal and Tree stuff from S16 to S32
wayland authored
175
0af27be @masak forcibly brought all files up-to-date with upstream
authored
176 Also known as the "civil" calendar. This is the calendar used in most
177 of the world, specially in the western countries.
929419d S16/S32: Moved Temporal and Tree stuff from S16 to S32
wayland authored
178
0af27be @masak forcibly brought all files up-to-date with upstream
authored
179 =head2 Gregorian::DateTime
929419d S16/S32: Moved Temporal and Tree stuff from S16 to S32
wayland authored
180
0af27be @masak forcibly brought all files up-to-date with upstream
authored
181 The gregorian DateTime declares the following additional attributes.
182
183 =over
929419d S16/S32: Moved Temporal and Tree stuff from S16 to S32
wayland authored
184
0af27be @masak forcibly brought all files up-to-date with upstream
authored
185 =item year
929419d S16/S32: Moved Temporal and Tree stuff from S16 to S32
wayland authored
186
0af27be @masak forcibly brought all files up-to-date with upstream
authored
187 =item month
929419d S16/S32: Moved Temporal and Tree stuff from S16 to S32
wayland authored
188
0af27be @masak forcibly brought all files up-to-date with upstream
authored
189 =item day
929419d S16/S32: Moved Temporal and Tree stuff from S16 to S32
wayland authored
190
0af27be @masak forcibly brought all files up-to-date with upstream
authored
191 =item minute
192
193 =item second
194
195 =item nanosecond
196
197 =item time-zone
198
199 =back
200
8fc19a3 @masak Added constructor details for Gregorian::DateTime
authored
201 The class provides a constructor which either accepts the attributes as
202 named parameters, or takes a single string value with a date/time
203 value. If both the string and named parameters are passed, the named
204 parameters take precedence. The string value can have any of the following
205 forms, all taken from ISO 8601:
206
207 =over
208
209 =item '2010-04-01 00:00' Separate date and time.
210
211 =item '2010-04-01T00:00' Combined date and time.
212
213 =item '2010-04-01' Just the date. Assumes 00:00.
214
215 =item '2010-04' Just the year and month. Assumes the first of that month.
216
217 =item '2010' Just the year. Assumes January.
218
219 =item '2010-091' Year and three-digit day-of-year.
220
221 =item '01:02:03' Time. Assumes today.
222
223 =item '01:02' Hours and minutes. Assumes 00 seconds.
224
225 =item '01' Just hours.
226
227 =item '01:02:03Z' UTC time. All time designations can end in a 'Z'.
228
229 =back
230
231 The following methods provide additional information:
0af27be @masak forcibly brought all files up-to-date with upstream
authored
232
233 =over
929419d S16/S32: Moved Temporal and Tree stuff from S16 to S32
wayland authored
234
0af27be @masak forcibly brought all files up-to-date with upstream
authored
235 =item day-of-week
236
03f2635 @masak reordered and removed duplicates from G::D attributes
authored
237 =item day-of-year
238
0af27be @masak forcibly brought all files up-to-date with upstream
authored
239 =item week-of-month
240
8fc19a3 @masak Added constructor details for Gregorian::DateTime
authored
241 =item week-of-year
242
0af27be @masak forcibly brought all files up-to-date with upstream
authored
243 =back
244
5703314 @masak various improvements and additions
authored
245 By default, a C<Gregorian::DateTime> object stringifies to something of
246 the form C<'2010-04-01T00:00'>.
247
0af27be @masak forcibly brought all files up-to-date with upstream
authored
248 =head2 Gregorian::Duration
249
250 The gregorian Duration declares the following attributes.
251
252 =over
253
ac5729c @masak various small janitor changes
authored
254 =item years
0af27be @masak forcibly brought all files up-to-date with upstream
authored
255
ac5729c @masak various small janitor changes
authored
256 =item months
0af27be @masak forcibly brought all files up-to-date with upstream
authored
257
ac5729c @masak various small janitor changes
authored
258 =item days
0af27be @masak forcibly brought all files up-to-date with upstream
authored
259
ac5729c @masak various small janitor changes
authored
260 =item minutes
0af27be @masak forcibly brought all files up-to-date with upstream
authored
261
ac5729c @masak various small janitor changes
authored
262 =item seconds
0af27be @masak forcibly brought all files up-to-date with upstream
authored
263
ac5729c @masak various small janitor changes
authored
264 =item nanoseconds
0af27be @masak forcibly brought all files up-to-date with upstream
authored
265
266 =back
929419d S16/S32: Moved Temporal and Tree stuff from S16 to S32
wayland authored
267
7e57a04 @masak constructor for Gregorian::Duration
authored
268 As with C<Gregorian::DateTime>, this class provides a constructor which either
269 accepts the attributes as named parameters, or takes a single string value
270 with a duration value, and here also the named parameters take precedence. The
271 string value can have any of the following forms:
272
273 =over
274
5703314 @masak various improvements and additions
authored
275 =item 'P1Y1M1DT1H1M1S'
276
277 The letters stand for 'period', 'years', 'months',
278 'days', 'time', 'hours', 'minutes', and 'seconds', respectively. The
279 1's stand in for any non-negative integer, which may be arbitrarily large.
280
281 =item The above format with any one of the letter/digit groups omitted.
7e57a04 @masak constructor for Gregorian::Duration
authored
282
5703314 @masak various improvements and additions
authored
283 The omitted groups are assumed to be 0. The following exceptions hold:
284 the 'P' may not be removed. The 'T' may be removed, but keep in mind
285 that it's used to disambiguate between months and minutes.
7e57a04 @masak constructor for Gregorian::Duration
authored
286
5703314 @masak various improvements and additions
authored
287 =item Any of the above with the least significant specified value a fractional value.
7e57a04 @masak constructor for Gregorian::Duration
authored
288
5703314 @masak various improvements and additions
authored
289 'P0.5Y' would mean 'half a year', for example.
290
291 =item A duration on the form 'P2010-04-01T00:00:00'
292
293 Where any number of the least significant values may be omitted.
294 By contrast with the above forms, this form doesn't allow values to exceed
295 their "carry-over point", so a month value may not be '13' and an hour value
296 may not be '25', for example.
7e57a04 @masak constructor for Gregorian::Duration
authored
297
298 =back
929419d S16/S32: Moved Temporal and Tree stuff from S16 to S32
wayland authored
299
5703314 @masak various improvements and additions
authored
300 By default, a C<Gregorian::DateTime> object stringifies to the second format
301 given above, and omits letter/digit groups where the number is 0.
302
32aa64d S16: Added a few attributes to trees
wayland authored
303 =head1 Additions
304
305 Please post errors and feedback to perl6-language. If you are making
306 a general laundry list, please separate messages by topic.
307
Something went wrong with that request. Please try again.