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

VERSION

9       version 0.16
10

SYNOPSIS

12           use DateTime::Format::ISO8601;
13
14           my $datetime_str = '2020-07-25T11:32:31';
15           my $dt = DateTime::Format::ISO8601->parse_datetime($datetime_str);
16           say $dt;
17
18           # This format is ambiguous and could be either a date or time, so use the
19           # parse_time method.
20           my $time_str = '113231';
21           $dt = DateTime::Format::ISO8601->parse_time($time_str);
22           say $dt;
23
24           # or
25
26           my $iso8601 = DateTime::Format::ISO8601->new;
27           $dt = $iso8601->parse_datetime($datetime_str);
28           say $dt;
29
30           $dt = $iso8601->parse_time($time_str);
31           say $dt;
32
33           say DateTime::Format::ISO8601->format_datetime($dt);
34

DESCRIPTION

36       Parses almost all ISO8601 date and time formats. ISO8601 time-intervals
37       will be supported in a later release.
38

METHODS

40       This class provides the following methods:
41
42   Constructors
43       DateTime::Format::ISO8601->new( ... )
44
45       Accepts an optional hash.
46
47           my $iso8601 = DateTime::Format::ISO8601->new(
48               base_datetime => $dt,
49               cut_off_year  => 42,
50               legacy_year   => 1,
51           );
52
53       •   base_datetime
54
55           A "DateTime" object that will be used to fill in missing
56           information from incomplete date/time formats.
57
58           This key is optional.
59
60       •   cut_off_year
61
62           A integer representing the cut-off point between interpreting
63           2-digits years as 19xx or 20xx.
64
65               2-digit years <  cut_off_year will be interpreted as 20xx
66               2-digit years >= cut_off_year will be untreated as 19xx
67
68           This key defaults to the value of "DefaultCutOffYear".
69
70       •   legacy_year
71
72           A boolean value controlling if a 2-digit year is interpreted as
73           being in the current century (unless a "base_datetime" is set) or
74           if "cut_off_year" should be used to place the year in either 20xx
75           or 19xx.
76
77           If this is true, then the "cut_off_year" is used. If this is false,
78           then the year is always interpreted as being in the current
79           century.
80
81           This key defaults to the value of "DefaultLegacyYear".
82
83       $iso8601->clone
84
85       Returns a replica of the given object.
86
87   Object Methods
88       $iso8601->base_datetime
89
90       Returns a "DateTime" object if a "base_datetime" has been set.
91
92       $iso8601->set_base_datetime( object => $object )
93
94       Accepts a "DateTime" object that will be used to fill in missing
95       information from incomplete date/time formats.
96
97       $iso8601->cut_off_year
98
99       Returns a integer representing the cut-off point between interpreting
100       2-digits years as 19xx or 20xx.
101
102       $iso8601->set_cut_off_year($int)
103
104       Accepts a integer representing the cut-off point between interpreting
105       2-digits years as 19xx or 20xx.
106
107           2-digit years <  legacy_year will be interpreted as 20xx
108           2-digit years >= legacy_year will be interpreted as 19xx
109
110       $iso8601->legacy_year
111
112       Returns a boolean value indicating the 2-digit year handling behavior.
113
114       $iso8601->set_legacy_year($bool)
115
116       Accepts a boolean value controlling if a 2-digit year is interpreted as
117       being in the current century (unless a "base_datetime" is set) or if
118       "cut_off_year" should be used to place the year in either 20xx or 19xx.
119
120   Class Methods
121       DateTime::Format::ISO8601->DefaultCutOffYear($int)
122
123       Accepts a integer representing the cut-off point for 2-digit years when
124       calling "parse_*" as class methods and the default value for
125       "cut_off_year" when creating objects. If called with no parameters this
126       method will return the default value for "cut_off_year".
127
128       DateTime::Format::ISO8601->DefaultLegacyYear($bool)
129
130       Accepts a boolean value controlling the legacy year behavior when
131       calling "parse_*" as class methods and the default value for
132       "legacy_year" when creating objects. If called with no parameters this
133       method will return the default value for "legacy_year".
134
135   Parser(s)
136       These methods may be called as either class or object methods.
137
138       parse_datetime
139
140       parse_time
141
142       Please see the "FORMATS" section.
143
144   Formatter
145       This may be called as either class or object method.
146
147       format_datetime($dt)
148
149       Formats the datetime in an ISO8601-compatible format. This differs from
150       "iso8601" in DateTime by including nanoseconds/milliseconds and the
151       correct timezone offset.
152

FORMATS

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

STANDARDS DOCUMENT

358   Title
359           ISO8601:2000(E)
360           Data elements and interchange formats - information exchange -
361           Representation of dates and times
362           Second edition 2000-12-15
363
364   Reference Number
365           ISO/TC 154 N 362
366

CREDITS

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

SUPPORT

392       Bugs may be submitted at
393       <https://github.com/houseabsolute/DateTime-Format-ISO8601/issues>.
394
395       I am also usually active on IRC as 'autarch' on "irc://irc.perl.org".
396

SOURCE

398       The source code repository for DateTime-Format-ISO8601 can be found at
399       <https://github.com/houseabsolute/DateTime-Format-ISO8601>.
400

AUTHORS

402       •   Joshua Hoblitt <josh@hoblitt.com>
403
404       •   Dave Rolsky <autarch@urth.org>
405

CONTRIBUTORS

407       •   Doug Bell <doug@preaction.me>
408
409       •   joe <draxil@gmail.com>
410
411       •   Liam Widdowson <lbw@telstra.com>
412
413       •   Thomas Klausner <domm@plix.at>
414

COPYRIGHT AND LICENSE

416       This software is copyright (c) 2021 by Joshua Hoblitt.
417
418       This is free software; you can redistribute it and/or modify it under
419       the same terms as the Perl 5 programming language system itself.
420
421       The full text of the license can be found in the LICENSE file included
422       with this distribution.
423
424
425
426perl v5.38.0                      2023-07-20      DateTime::Format::ISO8601(3)