File: README.md

package info (click to toggle)
libdatetime-format-iso8601-perl 0.15-1
  • links: PTS, VCS
  • area: main
  • in suites: bullseye, sid
  • size: 380 kB
  • sloc: perl: 1,063; makefile: 2
file content (410 lines) | stat: -rw-r--r-- 9,673 bytes parent folder | download
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
# NAME

DateTime::Format::ISO8601 - Parses ISO8601 formats

# VERSION

version 0.15

# SYNOPSIS

    use DateTime::Format::ISO8601;

    my $datetime_str = '2020-07-25T11:32:31';
    my $dt       = DateTime::Format::ISO8601->parse_datetime($datetime_str);
    say $dt;

    # This format is ambiguous and could be either a date or time, so use the
    # parse_time method.
    my $time_str = '113231';
    $dt = DateTime::Format::ISO8601->parse_time($time_str);
    say $dt;

    # or

    my $iso8601 = DateTime::Format::ISO8601->new;
    $dt = $iso8601->parse_datetime($datetime_str);
    say $dt;

    $dt = $iso8601->parse_time($time_str);
    say $dt;

    say DateTime::Format::ISO8601->format_datetime($dt);

# DESCRIPTION

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

# METHODS

This class provides the following methods:

## Constructors

### DateTime::Format::ISO8601->new( ... )

Accepts an optional hash.

    my $iso8601 = DateTime::Format::ISO8601->new(
        base_datetime => $dt,
        cut_off_year  => 42,
        legacy_year   => 1,
    );

- base\_datetime

    A `DateTime` object that will be used to fill in missing information from
    incomplete date/time formats.

    This key is optional.

- cut\_off\_year

    A integer representing the cut-off point between interpreting 2-digits years
    as 19xx or 20xx.

        2-digit years <  cut_off_year will be interpreted as 20xx
        2-digit years >= cut_off_year will be untreated as 19xx

    This key defaults to the value of `DefaultCutOffYear`.

- legacy\_year

    A boolean value controlling if a 2-digit year is interpreted as being in the
    current century (unless a `base_datetime` is set) or if `cut_off_year`
    should be used to place the year in either 20xx or 19xx.

    If this is true, then the `cut_off_year` is used. If this is false, then the
    year is always interpreted as being in the current century.

    This key defaults to the value of `DefaultLegacyYear`.

### $iso8601->clone

Returns a replica of the given object.

## Object Methods

### $iso8601->base\_datetime

Returns a `DateTime` object if a `base_datetime` has been set.

### $iso8601->set\_base\_datetime( object => $object )

Accepts a `DateTime` object that will be used to fill in missing information
from incomplete date/time formats.

### $iso8601->cut\_off\_year

Returns a integer representing the cut-off point between interpreting
2-digits years as 19xx or 20xx.

### $iso8601->set\_cut\_off\_year($int)

Accepts a integer representing the cut-off point between interpreting
2-digits years as 19xx or 20xx.

    2-digit years <  legacy_year will be interpreted as 20xx
    2-digit years >= legacy_year will be interpreted as 19xx

### $iso8601->legacy\_year

Returns a boolean value indicating the 2-digit year handling behavior.

### $iso8601->set\_legacy\_year($bool)

Accepts a boolean value controlling if a 2-digit year is interpreted as being
in the current century (unless a `base_datetime` is set) or if
`cut_off_year` should be used to place the year in either 20xx or 19xx.

## Class Methods

### DateTime::Format::ISO8601->DefaultCutOffYear($int)

Accepts a integer representing the cut-off point for 2-digit years when
calling `parse_*` as class methods and the default value for `cut_off_year`
when creating objects. If called with no parameters this method will return
the default value for `cut_off_year`.

### DateTime::Format::ISO8601->DefaultLegacyYear($bool)

Accepts a boolean value controlling the legacy year behavior when calling
`parse_*` as class methods and the default value for `legacy_year` when
creating objects. If called with no parameters this method will return the
default value for `legacy_year`.

## Parser(s)

These methods may be called as either class or object methods.

### parse\_datetime

### parse\_time

Please see the ["FORMATS"](#formats) section.

## Formatter

This may be called as either class or object method.

### format\_datetime($dt)

Formats the datetime in an ISO8601-compatible format. This differs from
["iso8601" in DateTime](https://metacpan.org/pod/DateTime#iso8601) by including nanoseconds/milliseconds and the correct
timezone offset.

# FORMATS

There are 6 strings that can match against date only or time only formats.
The `parse_datetime` method will attempt to match these ambiguous strings
against date only formats. If you want to match against the time only formats
use the `parse_time` method.

## Conventions

- Expanded ISO8601

    These formats are supported with exactly 6 digits for the year.
    Support for a variable number of digits will be in a later release.

- Precision

    If a format doesn't include a year all larger time unit up to and including
    the year are filled in using the current date/time or \[if set\] the
    `base_datetime` object.

- Fractional time

    There is no limit on the expressed precision.

## Supported via parse\_datetime

The supported formats are listed by the section of ISO 8601:2000(E) in
which they appear.

### 5.2 Dates

- 5.2.1.1
    - YYYYMMDD
    - YYYY-MM-DD
- 5.2.1.2
    - YYYY-MM
    - YYYY
    - YY
- 5.2.1.3
    - YYMMDD
    - YY-MM-DD
    - -YYMM
    - -YY-MM
    - -YY
    - --MMDD
    - --MM-DD
    - --MM
    - ---DD
- 5.2.1.4
    - +\[YY\]YYYYMMDD
    - +\[YY\]YYYY-MM-DD
    - +\[YY\]YYYY-MM
    - +\[YY\]YYYY
    - +\[YY\]YY
- 5.2.2.1
    - YYYYDDD
    - YYYY-DDD
- 5.2.2.2
    - YYDDD
    - YY-DDD
    - -DDD
- 5.2.2.3
    - +\[YY\]YYYYDDD
    - +\[YY\]YYYY-DDD
- 5.2.3.1
    - YYYYWwwD
    - YYYY-Www-D
- 5.2.3.2
    - YYYYWww
    - YYYY-Www
    - YYWwwD
    - YY-Www-D
    - YYWww
    - YY-Www
    - -YWwwD
    - -Y-Www-D
    - -YWww
    - -Y-Www
    - -WwwD
    - -Www-D
    - -Www
    - -W-D
- 5.2.3.4
    - +\[YY\]YYYYWwwD
    - +\[YY\]YYYY-Www-D
    - +\[YY\]YYYYWww
    - +\[YY\]YYYY-Www

### 5.3 Time of Day

- 5.3.1.1 - 5.3.1.3

    Values can optionally be prefixed with 'T'.

- 5.3.1.1
    - hh:mm:ss
- 5.3.1.2
    - hh:mm
- 5.3.1.3 - 5.3.1.4

    fractional (decimal) separator maybe either ',' or '.'

- 5.3.1.3
    - hhmmss,ss
    - hh:mm:ss,ss
    - hhmm,mm
    - hh:mm,mm
    - hh,hh
- 5.3.1.4
    - -mm:ss
    - -mmss,s
    - -mm:ss,s
    - -mm,m
    - --ss,s
- 5.3.3 - 5.3.4.2

    Values can optionally be prefixed with 'T'.

- 5.3.3
    - hhmmssZ
    - hh:mm:ssZ
    - hhmmZ
    - hh:mmZ
    - hhZ
    - hhmmss.ssZ
    - hh:mm:ss.ssZ
- 5.3.4.2
    - hhmmss\[+-\]hhmm
    - hh:mm:ss\[+-\]hh:mm
    - hhmmss\[+-\]hh
    - hh:mm:ss\[+-\]hh
    - hhmmss.ss\[+-\]hhmm
    - hh:mm:ss.ss\[+-\]hh:mm

### 5.4 Combinations of date and time of day

- 5.4.1
    - YYYYMMDDThhmmss
    - YYYY-MM-DDThh:mm:ss
    - YYYYMMDDThhmmssZ
    - YYYY-MM-DDThh:mm:ssZ
    - YYYYMMDDThhmmss\[+-\]hhmm
    - YYYY-MM-DDThh:mm:ss\[+-\]hh:mm
    - YYYYMMDDThhmmss\[+-\]hh
    - YYYY-MM-DDThh:mm:ss\[+-\]hh
- 5.4.2
    - YYYYMMDDThhmmss.ss
    - YYYY-MM-DDThh:mm:ss.ss
    - YYYYMMDDThhmmss.ss\[+-\]hh
    - YYYY-MM-DDThh:mm:ss.ss\[+-\]hh
    - YYYYMMDDThhmmss.ss\[+-\]hhmm
    - YYYY-MM-DDThh:mm:ss.ss\[+-\]hh:mm
- 5.4.3

    Support for this section is not complete.

    - YYYYMMDDThhmm
    - YYYY-MM-DDThh:mm
    - YYYYMMDDThhmmZ
    - YYYY-MM-DDThh:mmZ
    - YYYYDDDThhmm
    - YYYY-DDDThh:mm
    - YYYYDDDThhmmZ
    - YYYY-DDDThh:mmZ
    - YYYYWwwDThhmm\[+-\]hhmm
    - YYYY-Www-DThh:mm\[+-\]hh

### 5.5 Time-Intervals

These are not currently supported

## Supported via parse\_time

### 5.3.1.1 - 5.3.1.3

Values can optionally be prefixed with 'T'.

- 5.3.1.1
    - hhmmss
- 5.3.1.2
    - hhmm
    - hh
- 5.3.1.4
    - -mmss
    - -mm
    - --ss

# STANDARDS DOCUMENT

## Title

    ISO8601:2000(E)
    Data elements and interchange formats - information exchange -
    Representation of dates and times
    Second edition 2000-12-15

## Reference Number

    ISO/TC 154 N 362

# CREDITS

Iain 'Spoon' Truskett (SPOON) who wrote [DateTime::Format::Builder](https://metacpan.org/pod/DateTime%3A%3AFormat%3A%3ABuilder).
That has grown into _The Vacuum Energy Powered `Swiss Army` Katana_
of date and time parsing. This module was inspired by and conceived
in honor of Iain's work.

Tom Phoenix (PHOENIX) and PDX.pm for helping me solve the ISO week conversion
bug. Not by fixing the code but motivation me to fix it so I could
participate in a game of `Zendo`.

Jonathan Leffler (JOHNL) for reporting a test bug.

Kelly McCauley for a patch to add 8 missing formats.

Alasdair Allan (AALLAN) for complaining about excessive test execution time.

Everyone at the DateTime `Asylum`.

# SEE ALSO

- [DateTime](https://metacpan.org/pod/DateTime)
- [DateTime::Format::Builder](https://metacpan.org/pod/DateTime%3A%3AFormat%3A%3ABuilder)

# SUPPORT

Bugs may be submitted at [https://github.com/houseabsolute/DateTime-Format-ISO8601/issues](https://github.com/houseabsolute/DateTime-Format-ISO8601/issues).

I am also usually active on IRC as 'autarch' on `irc://irc.perl.org`.

# SOURCE

The source code repository for DateTime-Format-ISO8601 can be found at [https://github.com/houseabsolute/DateTime-Format-ISO8601](https://github.com/houseabsolute/DateTime-Format-ISO8601).

# AUTHORS

- Joshua Hoblitt <josh@hoblitt.com>
- Dave Rolsky <autarch@urth.org>

# CONTRIBUTORS

- Doug Bell <doug@preaction.me>
- joe <draxil@gmail.com>
- Thomas Klausner <domm@plix.at>

# COPYRIGHT AND LICENSE

This software is copyright (c) 2020 by Joshua Hoblitt.

This is free software; you can redistribute it and/or modify it under
the same terms as the Perl 5 programming language system itself.

The full text of the license can be found in the
`LICENSE` file included with this distribution.