DateTime::Format::ISO8601 - Parses ISO8601 formats
version 0.16
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);
Parses almost all ISO8601 date and time formats. ISO8601 time-intervals will be
supported in a later release.
This class provides the following methods:
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.
Returns a replica of the given object.
Returns a DateTime object if a base_datetime has been set.
Accepts a DateTime object that will be used to fill in missing information
from incomplete date/time formats.
Returns a integer representing the cut-off point between interpreting 2-digits
years as 19xx or 20xx.
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
Returns a boolean value indicating the 2-digit year handling behavior.
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.
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.
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.
These methods may be called as either class or object methods.
Please see the FORMATS section.
This may be called as either class or object method.
Formats the datetime in an ISO8601-compatible format. This differs from
DateTime/iso8601 by including nanoseconds/milliseconds and the correct
timezone offset.
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.
- 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.
The supported formats are listed by the section of ISO 8601:2000(E) in which
they appear.
- 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
-
These are not currently supported
Values can optionally be prefixed with 'T'.
ISO8601:2000(E)
Data elements and interchange formats - information exchange -
Representation of dates and times
Second edition 2000-12-15
ISO/TC 154 N 362
Iain 'Spoon' Truskett (SPOON) who wrote the DateTime::Format::Builder manpage. 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.
Bugs may be submitted at https://github.com/houseabsolute/DateTime-Format-ISO8601/issues.
I am also usually active on IRC as 'autarch' on irc://irc.perl.org.
The source code repository for DateTime-Format-ISO8601 can be found at https://github.com/houseabsolute/DateTime-Format-ISO8601.
This software is copyright (c) 2021 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.
|