DateTime::Format::ISO8601(3pm)

1DateTime::Format::ISO86U0s1e(r3)Contributed Perl DocumenDtaatteiToinme::Format::ISO8601(3)
2
3
4

NAME

6       DateTime::Format::ISO8601 - Parses ISO8601 formats
7

SYNOPSIS

9           use DateTime::Format::ISO8601;
10
11           my $dt = DateTime::Format::ISO8601->parse_datetime( $str );
12           my $dt = DateTime::Format::ISO8601->parse_time( $str );
13
14           or
15
16           my $iso8601 = DateTime::Format::ISO8601->new;
17           my $dt = $iso8601->parse_datetime( $str );
18           my $dt = $iso8601->parse_time( $str );
19

DESCRIPTION

21       Parses almost all ISO8601 date and time formats.  ISO8601 time-
22       intervals will be supported in a later release.
23

USAGE

25   Import Parameters
26       This module accepts no arguments to it's "import" method.
27
28   Methods
29       Constructors
30
31       ·   new( ... )
32
33           Accepts an optional hash.
34
35               my $iso8601 = DateTime::Format::ISO8601->new(
36                               base_datetime => $dt,
37                               cut_off_year  => 42,
38                               legacy_year   => 1,
39                           );
40
41           ·   base_datetime
42
43               A "DateTime" object that will be used to fill in missing
44               information from incomplete date/time formats.
45
46               This key is optional.
47
48           ·   cut_off_year
49
50               A integer representing the cut-off point between interpreting
51               2-digits years as 19xx or 20xx.
52
53                   2-digit years <  legacy_year will be interpreted as 20xx
54                   2-digit years >= legacy_year will be untreated as 19xx
55
56               This key defaults to the value of "DefaultCutOffYear".
57
58           ·   legacy_year
59
60               A boolean value controlling if a 2-digit year is interpreted as
61               being in the current century (unless a "base_datetime" is set)
62               or if "cut_off_year" should be used to place the year in either
63               20xx or 19xx.
64
65               This key defaults to the value of "DefaultLegacyYear".
66
67       ·   clone
68
69           Returns a replica of the given object.
70
71       Object Methods
72
73       ·   base_datetime
74
75           Returns a "DateTime" object if a "base_datetime" has been set.
76
77       ·   set_base_datetime( object => $object )
78
79           Accepts a "DateTime" object that will be used to fill in missing
80           information from incomplete date/time formats.
81
82       ·   cut_off_year
83
84           Returns a integer representing the cut-off point between
85           interpreting 2-digits years as 19xx or 20xx.
86
87       ·   set_cut_off_year( $int )
88
89           Accepts a integer representing the cut-off point between
90           interpreting 2-digits years as 19xx or 20xx.
91
92               2-digit years <  legacy_year will be interpreted as 20xx
93               2-digit years >= legacy_year will be interpreted as 19xx
94
95       ·   legacy_year
96
97           Returns a boolean value indicating the 2-digit year handling
98           behavior.
99
100       ·   set_legacy_year( $bool )
101
102           Accepts a boolean value controlling if a 2-digit year is
103           interpreted as being in the current century (unless a
104           "base_datetime" is set) or if "cut_off_year" should be used to
105           place the year in either 20xx or 19xx.
106
107       Class Methods
108
109       ·   DefaultCutOffYear( $int )
110
111           Accepts a integer representing the cut-off point for 2-digit years
112           when calling "parse_*" as class methods and the default value for
113           "cut_off_year" when creating objects.  If called with no parameters
114           this method will return the default value for "cut_off_year".
115
116       ·   DefaultLegacyYear( $bool )
117
118           Accepts a boolean value controlling the legacy year behavior when
119           calling "parse_*" as class methods and the default value for
120           "legacy_year" when creating objects.  If called with no parameters
121           this method will return the default value for "legacy_year".
122
123       Parser(s)
124
125       These may be called as either class or object methods.
126
127       ·   parse_datetime
128
129       ·   parse_time
130
131           Please see the "FORMATS" section.
132

FORMATS

134       There are 6 string that can match against date only or time only
135       formats.  The "parse_datetime" method will attempt to match these
136       ambiguous strings against date only formats.  If you want to match
137       against the time only formats see the "parse_time" method.
138
139   Conventions
140       ·   Expanded ISO8601
141
142           These formats are supported with exactly 6 digits for the year.
143           Support for a variable number of digits will be in a later release.
144
145       ·   Precision
146
147           If a format doesn't include a year all larger time unit up to and
148           including the year are filled in using the current date/time or [if
149           set] the "base_datetime" object.
150
151       ·   Fractional time
152
153           There is no limit on the expressed precision.
154
155   Supported via parse_datetime
156       The supported formats are listed by the section of ISO 8601:2000(E) in
157       which they appear.
158
159       5.2 Dates
160
161       5.2.1.1
162
163           YYYYMMDD
164           YYYY-MM-DD
165
166       5.2.1.2
167
168           YYYY-MM
169           YYYY
170           YY
171
172       5.2.1.3
173
174           YYMMDD
175           YY-MM-DD
176           -YYMM
177           -YY-MM
178           -YY
179           --MMDD
180           --MM-DD
181           --MM
182           ---DD
183
184       5.2.1.4
185
186           +[YY]YYYYMMDD
187           +[YY]YYYY-MM-DD
188           +[YY]YYYY-MM
189           +[YY]YYYY
190           +[YY]YY
191
192       5.2.2.1
193
194           YYYYDDD
195           YYYY-DDD
196
197       5.2.2.2
198
199           YYDDD
200           YY-DDD
201           -DDD
202
203       5.2.2.3
204
205           +[YY]YYYYDDD
206           +[YY]YYYY-DDD
207
208       5.3.2.1
209
210           YYYYWwwD
211           YYYY-Www-D
212
213       5.2.3.2
214
215           YYYYWww
216           YYYY-Www
217           YYWwwD
218           YY-Www-D
219           YYWww
220           YY-Www
221           -YWwwD
222           -Y-Www-D
223           -YWww
224           -Y-Www
225           -WwwD
226           -Www-D
227           -Www
228           -W-D
229
230       5.2.3.4
231
232           +[YY]YYYYWwwD
233           +[YY]YYYY-Www-D
234           +[YY]YYYYWww
235           +[YY]YYYY-Www
236
237       5.3 Time of Day
238
239       5.3.1.1 - 5.3.1.3
240
241       optionally prefixed with 'T'
242
243       5.3.1.1
244
245           hh:mm:ss
246
247       5.3.1.2
248
249           hh:mm
250
251       5.3.1.3 - 5.3.1.4
252
253       fractional (decimal) separator maybe either ',' or '.'
254
255       5.3.1.3
256
257           hhmmss,ss
258           hh:mm:ss,ss
259           hhmm,mm
260           hh:mm,mm
261           hh,hh
262
263       5.3.1.4
264
265           -mm:ss
266           -mmss,s
267           -mm:ss,s
268           -mm,m
269           --ss,s
270
271       5.3.3 - 5.3.4.2
272
273       optionally prefixed with 'T'
274
275       5.3.3
276
277           hhmmssZ
278           hh:mm:ssZ
279           hhmmZ
280           hh:mmZ
281           hhZ
282           hhmmss.ssZ
283           hh:mm:ss.ssZ
284
285       5.3.4.2
286
287           hhmmss[+-]hhmm
288           hh:mm:ss[+-]hh:mm
289           hhmmss[+-]hh
290           hh:mm:ss[+-]hh
291           hhmmss.ss[+-]hhmm
292           hh:mm:ss.ss[+-]hh:mm
293
294       5.4 Combinations of date and time of day
295
296       5.4.1
297
298           YYYYMMDDThhmmss
299           YYYY-MM-DDThh:mm:ss
300           YYYYMMDDThhmmssZ
301           YYYY-MM-DDThh:mm:ssZ
302           YYYYMMDDThhmmss[+-]hhmm
303           YYYY-MM-DDThh:mm:ss[+-]hh:mm
304           YYYYMMDDThhmmss[+-]hh
305           YYYY-MM-DDThh:mm:ss[+-]hh
306
307       5.4.2
308
309          YYYYMMDDThhmmss.ss
310          YYYY-MM-DDThh:mm:ss.ss
311          YYYYMMDDThhmmss.ss[+-]hhmm
312          YYYY-MM-DDThh:mm:ss.ss[+-]hh:mm
313
314       Support for this section is not complete.
315
316           YYYYMMDDThhmm
317           YYYY-MM-DDThh:mm
318           YYYYDDDThhmmZ
319           YYYY-DDDThh:mmZ
320           YYYYWwwDThhmm[+-]hhmm
321           YYYY-Www-DThh:mm[+-]hh
322
323       5.5 Time-Intervals
324
325       Will be supported in a later release.
326
327   Supported via parse_time
328       5.3.1.1 - 5.3.1.3
329
330       optionally prefixed with 'T'
331
332       5.3.1.1
333
334           hhmmss
335
336       5.3.1.2
337
338           hhmm
339           hh
340
341       5.3.1.4
342
343           -mmss
344           -mm
345           --ss
346

STANDARDS DOCUMENT

348   Title
349           ISO8601:2000(E)
350           Data elements and interchange formats - information exchange -
351           Representation of dates and times
352           Second edition 2000-12-15
353
354   Reference Number
355           ISO/TC 154 N 362
356

CREDITS

358       Iain 'Spoon' Truskett (SPOON) who wrote DateTime::Format::Builder.
359       That has grown into The Vacuum Energy Powered "Swiss Army" Katana of
360       date and time parsing.  This module was inspired by and conceived in
361       honor of Iain's work.
362
363       Tom Phoenix (PHOENIX) and PDX.pm for helping me solve the ISO week
364       conversion bug.  Not by fixing the code but motivation me to fix it so
365       I could participate in a game of "Zendo".
366
367       Jonathan Leffler (JOHNL) for reporting a test bug.
368
369       Kelly McCauley for a patch to add 8 missing formats.
370
371       Alasdair Allan (AALLAN) for complaining about excessive test execution
372       time.
373
374       Everyone at the DateTime "Asylum".
375

SUPPORT

377       Support for this module is provided via the <datetime@perl.org> email
378       list.  See <http://lists.perl.org/> for more details.
379

AUTHOR

381       Joshua Hoblitt <jhoblitt@cpan.org>
382

COPYRIGHT

384       Copyright (c) 2003-2005  Joshua Hoblitt. All rights reserved. This
385       program is free software; you can redistribute it and/or modify it
386       under the same terms as Perl itself.
387
388       The full text of the licenses can be found in the LICENSE file included
389       with this module, or in perlartistic and perlgpl as supplied with Perl
390       5.8.1 and later.
391