.\" -*- mode: troff; coding: utf-8 -*- .\" Automatically generated by Pod::Man 5.01 (Pod::Simple 3.43) .\" .\" Standard preamble: .\" ======================================================================== .de Sp \" Vertical space (when we can't use .PP) .if t .sp .5v .if n .sp .. .de Vb \" Begin verbatim text .ft CW .nf .ne \\$1 .. .de Ve \" End verbatim text .ft R .fi .. .\" \*(C` and \*(C' are quotes in nroff, nothing in troff, for use with C<>. .ie n \{\ . ds C` "" . ds C' "" 'br\} .el\{\ . ds C` . ds C' 'br\} .\" .\" Escape single quotes in literal strings from groff's Unicode transform. .ie \n(.g .ds Aq \(aq .el .ds Aq ' .\" .\" If the F register is >0, we'll generate index entries on stderr for .\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index .\" entries marked with X<> in POD. Of course, you'll have to process the .\" output yourself in some meaningful fashion. .\" .\" Avoid warning from groff about undefined register 'F'. .de IX .. .nr rF 0 .if \n(.g .if rF .nr rF 1 .if (\n(rF:(\n(.g==0)) \{\ . if \nF \{\ . de IX . tm Index:\\$1\t\\n%\t"\\$2" .. . if !\nF==2 \{\ . nr % 0 . nr F 2 . \} . \} .\} .rr rF .\" ======================================================================== .\" .IX Title "DateTime::Format::ISO8601 3" .TH DateTime::Format::ISO8601 3 2024-07-13 "perl v5.38.2" "User Contributed Perl Documentation" .\" For nroff, turn off justification. Always turn off hyphenation; it makes .\" way too many mistakes in technical documents. .if n .ad l .nh .SH NAME DateTime::Format::ISO8601 \- Parses ISO8601 formats .SH VERSION .IX Header "VERSION" version 0.16 .SH SYNOPSIS .IX Header "SYNOPSIS" .Vb 1 \& use DateTime::Format::ISO8601; \& \& my $datetime_str = \*(Aq2020\-07\-25T11:32:31\*(Aq; \& 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 = \*(Aq113231\*(Aq; \& $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); .Ve .SH DESCRIPTION .IX Header "DESCRIPTION" Parses almost all ISO8601 date and time formats. ISO8601 time-intervals will be supported in a later release. .SH METHODS .IX Header "METHODS" This class provides the following methods: .SS Constructors .IX Subsection "Constructors" \fIDateTime::Format::ISO8601\->new( ... )\fR .IX Subsection "DateTime::Format::ISO8601->new( ... )" .PP Accepts an optional hash. .PP .Vb 5 \& my $iso8601 = DateTime::Format::ISO8601\->new( \& base_datetime => $dt, \& cut_off_year => 42, \& legacy_year => 1, \& ); .Ve .IP \(bu 4 base_datetime .Sp A \f(CW\*(C`DateTime\*(C'\fR object that will be used to fill in missing information from incomplete date/time formats. .Sp This key is optional. .IP \(bu 4 cut_off_year .Sp A integer representing the cut-off point between interpreting 2\-digits years as 19xx or 20xx. .Sp .Vb 2 \& 2\-digit years < cut_off_year will be interpreted as 20xx \& 2\-digit years >= cut_off_year will be untreated as 19xx .Ve .Sp This key defaults to the value of \f(CW\*(C`DefaultCutOffYear\*(C'\fR. .IP \(bu 4 legacy_year .Sp A boolean value controlling if a 2\-digit year is interpreted as being in the current century (unless a \f(CW\*(C`base_datetime\*(C'\fR is set) or if \f(CW\*(C`cut_off_year\*(C'\fR should be used to place the year in either 20xx or 19xx. .Sp If this is true, then the \f(CW\*(C`cut_off_year\*(C'\fR is used. If this is false, then the year is always interpreted as being in the current century. .Sp This key defaults to the value of \f(CW\*(C`DefaultLegacyYear\*(C'\fR. .PP \fR\f(CI$iso8601\fR\fI\->clone\fR .IX Subsection "$iso8601->clone" .PP Returns a replica of the given object. .SS "Object Methods" .IX Subsection "Object Methods" \fR\f(CI$iso8601\fR\fI\->base_datetime\fR .IX Subsection "$iso8601->base_datetime" .PP Returns a \f(CW\*(C`DateTime\*(C'\fR object if a \f(CW\*(C`base_datetime\*(C'\fR has been set. .PP \fR\f(CI$iso8601\fR\fI\->set_base_datetime( object => \fR\f(CI$object\fR\fI )\fR .IX Subsection "$iso8601->set_base_datetime( object => $object )" .PP Accepts a \f(CW\*(C`DateTime\*(C'\fR object that will be used to fill in missing information from incomplete date/time formats. .PP \fR\f(CI$iso8601\fR\fI\->cut_off_year\fR .IX Subsection "$iso8601->cut_off_year" .PP Returns a integer representing the cut-off point between interpreting 2\-digits years as 19xx or 20xx. .PP \fR\f(CI$iso8601\fR\fI\->set_cut_off_year($int)\fR .IX Subsection "$iso8601->set_cut_off_year($int)" .PP Accepts a integer representing the cut-off point between interpreting 2\-digits years as 19xx or 20xx. .PP .Vb 2 \& 2\-digit years < legacy_year will be interpreted as 20xx \& 2\-digit years >= legacy_year will be interpreted as 19xx .Ve .PP \fR\f(CI$iso8601\fR\fI\->legacy_year\fR .IX Subsection "$iso8601->legacy_year" .PP Returns a boolean value indicating the 2\-digit year handling behavior. .PP \fR\f(CI$iso8601\fR\fI\->set_legacy_year($bool)\fR .IX Subsection "$iso8601->set_legacy_year($bool)" .PP Accepts a boolean value controlling if a 2\-digit year is interpreted as being in the current century (unless a \f(CW\*(C`base_datetime\*(C'\fR is set) or if \f(CW\*(C`cut_off_year\*(C'\fR should be used to place the year in either 20xx or 19xx. .SS "Class Methods" .IX Subsection "Class Methods" \fIDateTime::Format::ISO8601\->DefaultCutOffYear($int)\fR .IX Subsection "DateTime::Format::ISO8601->DefaultCutOffYear($int)" .PP Accepts a integer representing the cut-off point for 2\-digit years when calling \&\f(CW\*(C`parse_*\*(C'\fR as class methods and the default value for \f(CW\*(C`cut_off_year\*(C'\fR when creating objects. If called with no parameters this method will return the default value for \f(CW\*(C`cut_off_year\*(C'\fR. .PP \fIDateTime::Format::ISO8601\->DefaultLegacyYear($bool)\fR .IX Subsection "DateTime::Format::ISO8601->DefaultLegacyYear($bool)" .PP Accepts a boolean value controlling the legacy year behavior when calling \&\f(CW\*(C`parse_*\*(C'\fR as class methods and the default value for \f(CW\*(C`legacy_year\*(C'\fR when creating objects. If called with no parameters this method will return the default value for \f(CW\*(C`legacy_year\*(C'\fR. .SS Parser(s) .IX Subsection "Parser(s)" These methods may be called as either class or object methods. .PP \fIparse_datetime\fR .IX Subsection "parse_datetime" .PP \fIparse_time\fR .IX Subsection "parse_time" .PP Please see the "FORMATS" section. .SS Formatter .IX Subsection "Formatter" This may be called as either class or object method. .PP \fIformat_datetime($dt)\fR .IX Subsection "format_datetime($dt)" .PP Formats the datetime in an ISO8601\-compatible format. This differs from "iso8601" in DateTime by including nanoseconds/milliseconds and the correct timezone offset. .SH FORMATS .IX Header "FORMATS" There are 6 strings that can match against date only or time only formats. The \&\f(CW\*(C`parse_datetime\*(C'\fR method will attempt to match these ambiguous strings against date only formats. If you want to match against the time only formats use the \&\f(CW\*(C`parse_time\*(C'\fR method. .SS Conventions .IX Subsection "Conventions" .IP \(bu 4 Expanded ISO8601 .Sp These formats are supported with exactly 6 digits for the year. Support for a variable number of digits will be in a later release. .IP \(bu 4 Precision .Sp 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 \f(CW\*(C`base_datetime\*(C'\fR object. .IP \(bu 4 Fractional time .Sp There is no limit on the expressed precision. .SS "Supported via parse_datetime" .IX Subsection "Supported via parse_datetime" The supported formats are listed by the section of ISO 8601:2000(E) in which they appear. .PP \fI5.2 Dates\fR .IX Subsection "5.2 Dates" .IP \(bu 4 5.2.1.1 .RS 4 .IP YYYYMMDD 8 .IX Item "YYYYMMDD" .PD 0 .IP YYYY-MM-DD 8 .IX Item "YYYY-MM-DD" .RE .RS 4 .RE .IP \(bu 4 .PD 5.2.1.2 .RS 4 .IP YYYY-MM 8 .IX Item "YYYY-MM" .PD 0 .IP YYYY 8 .IX Item "YYYY" .IP YY 8 .IX Item "YY" .RE .RS 4 .RE .IP \(bu 4 .PD 5.2.1.3 .RS 4 .IP YYMMDD 8 .IX Item "YYMMDD" .PD 0 .IP YY-MM-DD 8 .IX Item "YY-MM-DD" .IP \-YYMM 8 .IX Item "-YYMM" .IP \-YY\-MM 8 .IX Item "-YY-MM" .IP \-YY 8 .IX Item "-YY" .IP \-\-MMDD 8 .IX Item "--MMDD" .IP \-\-MM\-DD 8 .IX Item "--MM-DD" .IP \-\-MM 8 .IX Item "--MM" .IP \-\-\-DD 8 .IX Item "---DD" .RE .RS 4 .RE .IP \(bu 4 .PD 5.2.1.4 .RS 4 .IP +[YY]YYYYMMDD 8 .IX Item "+[YY]YYYYMMDD" .PD 0 .IP +[YY]YYYY\-MM\-DD 8 .IX Item "+[YY]YYYY-MM-DD" .IP +[YY]YYYY\-MM 8 .IX Item "+[YY]YYYY-MM" .IP +[YY]YYYY 8 .IX Item "+[YY]YYYY" .IP +[YY]YY 8 .IX Item "+[YY]YY" .RE .RS 4 .RE .IP \(bu 4 .PD 5.2.2.1 .RS 4 .IP YYYYDDD 8 .IX Item "YYYYDDD" .PD 0 .IP YYYY-DDD 8 .IX Item "YYYY-DDD" .RE .RS 4 .RE .IP \(bu 4 .PD 5.2.2.2 .RS 4 .IP YYDDD 8 .IX Item "YYDDD" .PD 0 .IP YY-DDD 8 .IX Item "YY-DDD" .IP \-DDD 8 .IX Item "-DDD" .RE .RS 4 .RE .IP \(bu 4 .PD 5.2.2.3 .RS 4 .IP +[YY]YYYYDDD 8 .IX Item "+[YY]YYYYDDD" .PD 0 .IP +[YY]YYYY\-DDD 8 .IX Item "+[YY]YYYY-DDD" .RE .RS 4 .RE .IP \(bu 4 .PD 5.2.3.1 .RS 4 .IP YYYYWwwD 8 .IX Item "YYYYWwwD" .PD 0 .IP YYYY-Www-D 8 .IX Item "YYYY-Www-D" .RE .RS 4 .RE .IP \(bu 4 .PD 5.2.3.2 .RS 4 .IP YYYYWww 8 .IX Item "YYYYWww" .PD 0 .IP YYYY-Www 8 .IX Item "YYYY-Www" .IP YYWwwD 8 .IX Item "YYWwwD" .IP YY-Www-D 8 .IX Item "YY-Www-D" .IP YYWww 8 .IX Item "YYWww" .IP YY-Www 8 .IX Item "YY-Www" .IP \-YWwwD 8 .IX Item "-YWwwD" .IP \-Y\-Www\-D 8 .IX Item "-Y-Www-D" .IP \-YWww 8 .IX Item "-YWww" .IP \-Y\-Www 8 .IX Item "-Y-Www" .IP \-WwwD 8 .IX Item "-WwwD" .IP \-Www\-D 8 .IX Item "-Www-D" .IP \-Www 8 .IX Item "-Www" .IP \-W\-D 8 .IX Item "-W-D" .RE .RS 4 .RE .IP \(bu 4 .PD 5.2.3.4 .RS 4 .IP +[YY]YYYYWwwD 8 .IX Item "+[YY]YYYYWwwD" .PD 0 .IP +[YY]YYYY\-Www\-D 8 .IX Item "+[YY]YYYY-Www-D" .IP +[YY]YYYYWww 8 .IX Item "+[YY]YYYYWww" .IP +[YY]YYYY\-Www 8 .IX Item "+[YY]YYYY-Www" .RE .RS 4 .RE .PD .PP \fI5.3 Time of Day\fR .IX Subsection "5.3 Time of Day" .IP \(bu 4 5.3.1.1 \- 5.3.1.3 .Sp Values can optionally be prefixed with 'T'. .IP \(bu 4 5.3.1.1 .RS 4 .IP hh:mm:ss 8 .IX Item "hh:mm:ss" .RE .RS 4 .RE .PD 0 .IP \(bu 4 .PD 5.3.1.2 .RS 4 .IP hh:mm 8 .IX Item "hh:mm" .RE .RS 4 .RE .PD 0 .IP \(bu 4 .PD 5.3.1.3 \- 5.3.1.4 .Sp fractional (decimal) separator maybe either ',' or '.' .IP \(bu 4 5.3.1.3 .RS 4 .IP hhmmss,ss 8 .IX Item "hhmmss,ss" .PD 0 .IP hh:mm:ss,ss 8 .IX Item "hh:mm:ss,ss" .IP hhmm,mm 8 .IX Item "hhmm,mm" .IP hh:mm,mm 8 .IX Item "hh:mm,mm" .IP hh,hh 8 .IX Item "hh,hh" .RE .RS 4 .RE .IP \(bu 4 .PD 5.3.1.4 .RS 4 .IP \-mm:ss 8 .IX Item "-mm:ss" .PD 0 .IP \-mmss,s 8 .IX Item "-mmss,s" .IP \-mm:ss,s 8 .IX Item "-mm:ss,s" .IP \-mm,m 8 .IX Item "-mm,m" .IP \-\-ss,s 8 .IX Item "--ss,s" .RE .RS 4 .RE .IP \(bu 4 .PD 5.3.3 \- 5.3.4.2 .Sp Values can optionally be prefixed with 'T'. .IP \(bu 4 5.3.3 .RS 4 .IP hhmmssZ 8 .IX Item "hhmmssZ" .PD 0 .IP hh:mm:ssZ 8 .IX Item "hh:mm:ssZ" .IP hhmmZ 8 .IX Item "hhmmZ" .IP hh:mmZ 8 .IX Item "hh:mmZ" .IP hhZ 8 .IX Item "hhZ" .IP hhmmss.ssZ 8 .IX Item "hhmmss.ssZ" .IP hh:mm:ss.ssZ 8 .IX Item "hh:mm:ss.ssZ" .RE .RS 4 .RE .IP \(bu 4 .PD 5.3.4.2 .RS 4 .IP hhmmss[+\-]hhmm 8 .IX Item "hhmmss[+-]hhmm" .PD 0 .IP hh:mm:ss[+\-]hh:mm 8 .IX Item "hh:mm:ss[+-]hh:mm" .IP hhmmss[+\-]hh 8 .IX Item "hhmmss[+-]hh" .IP hh:mm:ss[+\-]hh 8 .IX Item "hh:mm:ss[+-]hh" .IP hhmmss.ss[+\-]hhmm 8 .IX Item "hhmmss.ss[+-]hhmm" .IP hh:mm:ss.ss[+\-]hh:mm 8 .IX Item "hh:mm:ss.ss[+-]hh:mm" .RE .RS 4 .RE .PD .PP \fI5.4 Combinations of date and time of day\fR .IX Subsection "5.4 Combinations of date and time of day" .IP \(bu 4 5.4.1 .RS 4 .IP YYYYMMDDThhmmss 8 .IX Item "YYYYMMDDThhmmss" .PD 0 .IP YYYY\-MM\-DDThh:mm:ss 8 .IX Item "YYYY-MM-DDThh:mm:ss" .IP YYYYMMDDThhmmssZ 8 .IX Item "YYYYMMDDThhmmssZ" .IP YYYY\-MM\-DDThh:mm:ssZ 8 .IX Item "YYYY-MM-DDThh:mm:ssZ" .IP YYYYMMDDThhmmss[+\-]hhmm 8 .IX Item "YYYYMMDDThhmmss[+-]hhmm" .IP YYYY\-MM\-DDThh:mm:ss[+\-]hh:mm 8 .IX Item "YYYY-MM-DDThh:mm:ss[+-]hh:mm" .IP YYYYMMDDThhmmss[+\-]hh 8 .IX Item "YYYYMMDDThhmmss[+-]hh" .IP YYYY\-MM\-DDThh:mm:ss[+\-]hh 8 .IX Item "YYYY-MM-DDThh:mm:ss[+-]hh" .RE .RS 4 .RE .IP \(bu 4 .PD 5.4.2 .RS 4 .IP YYYYMMDDThhmmss.ss 8 .IX Item "YYYYMMDDThhmmss.ss" .PD 0 .IP YYYY\-MM\-DDThh:mm:ss.ss 8 .IX Item "YYYY-MM-DDThh:mm:ss.ss" .IP YYYYMMDDThhmmss.ss[+\-]hh 8 .IX Item "YYYYMMDDThhmmss.ss[+-]hh" .IP YYYY\-MM\-DDThh:mm:ss.ss[+\-]hh 8 .IX Item "YYYY-MM-DDThh:mm:ss.ss[+-]hh" .IP YYYYMMDDThhmmss.ss[+\-]hhmm 8 .IX Item "YYYYMMDDThhmmss.ss[+-]hhmm" .IP YYYY\-MM\-DDThh:mm:ss.ss[+\-]hh:mm 8 .IX Item "YYYY-MM-DDThh:mm:ss.ss[+-]hh:mm" .RE .RS 4 .RE .IP \(bu 4 .PD 5.4.3 .Sp Support for this section is not complete. .RS 4 .IP YYYYMMDDThhmm 8 .IX Item "YYYYMMDDThhmm" .PD 0 .IP YYYY\-MM\-DDThh:mm 8 .IX Item "YYYY-MM-DDThh:mm" .IP YYYYMMDDThhmmZ 8 .IX Item "YYYYMMDDThhmmZ" .IP YYYY\-MM\-DDThh:mmZ 8 .IX Item "YYYY-MM-DDThh:mmZ" .IP YYYYDDDThhmm 8 .IX Item "YYYYDDDThhmm" .IP YYYY\-DDDThh:mm 8 .IX Item "YYYY-DDDThh:mm" .IP YYYYDDDThhmmZ 8 .IX Item "YYYYDDDThhmmZ" .IP YYYY\-DDDThh:mmZ 8 .IX Item "YYYY-DDDThh:mmZ" .IP YYYYWwwDThhmm[+\-]hhmm 8 .IX Item "YYYYWwwDThhmm[+-]hhmm" .IP YYYY\-Www\-DThh:mm[+\-]hh 8 .IX Item "YYYY-Www-DThh:mm[+-]hh" .RE .RS 4 .RE .PD .PP \fI5.5 Time-Intervals\fR .IX Subsection "5.5 Time-Intervals" .PP These are not currently supported .SS "Supported via parse_time" .IX Subsection "Supported via parse_time" \fI5.3.1.1 \- 5.3.1.3\fR .IX Subsection "5.3.1.1 - 5.3.1.3" .PP Values can optionally be prefixed with 'T'. .IP \(bu 4 5.3.1.1 .RS 4 .IP hhmmss 8 .IX Item "hhmmss" .RE .RS 4 .RE .PD 0 .IP \(bu 4 .PD 5.3.1.2 .RS 4 .IP hhmm 8 .IX Item "hhmm" .PD 0 .IP hh 8 .IX Item "hh" .RE .RS 4 .RE .IP \(bu 4 .PD 5.3.1.4 .RS 4 .IP \-mmss 8 .IX Item "-mmss" .PD 0 .IP \-mm 8 .IX Item "-mm" .IP \-\-ss 8 .IX Item "--ss" .RE .RS 4 .RE .PD .SH "STANDARDS DOCUMENT" .IX Header "STANDARDS DOCUMENT" .SS Title .IX Subsection "Title" .Vb 4 \& ISO8601:2000(E) \& Data elements and interchange formats \- information exchange \- \& Representation of dates and times \& Second edition 2000\-12\-15 .Ve .SS "Reference Number" .IX Subsection "Reference Number" .Vb 1 \& ISO/TC 154 N 362 .Ve .SH CREDITS .IX Header "CREDITS" Iain 'Spoon' Truskett (SPOON) who wrote DateTime::Format::Builder. That has grown into \fIThe Vacuum Energy Powered \fR\f(CI\*(C`Swiss Army\*(C'\fR\fI Katana\fR of date and time parsing. This module was inspired by and conceived in honor of Iain's work. .PP 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 \f(CW\*(C`Zendo\*(C'\fR. .PP Jonathan Leffler (JOHNL) for reporting a test bug. .PP Kelly McCauley for a patch to add 8 missing formats. .PP Alasdair Allan (AALLAN) for complaining about excessive test execution time. .PP Everyone at the DateTime \f(CW\*(C`Asylum\*(C'\fR. .SH "SEE ALSO" .IX Header "SEE ALSO" .IP \(bu 4 DateTime .IP \(bu 4 DateTime::Format::Builder .SH SUPPORT .IX Header "SUPPORT" Bugs may be submitted at . .PP I am also usually active on IRC as 'autarch' on \f(CW\*(C`irc://irc.perl.org\*(C'\fR. .SH SOURCE .IX Header "SOURCE" The source code repository for DateTime\-Format\-ISO8601 can be found at . .SH AUTHORS .IX Header "AUTHORS" .IP \(bu 4 Joshua Hoblitt .IP \(bu 4 Dave Rolsky .SH CONTRIBUTORS .IX Header "CONTRIBUTORS" .IP \(bu 4 Doug Bell .IP \(bu 4 joe .IP \(bu 4 Liam Widdowson .IP \(bu 4 Thomas Klausner .SH "COPYRIGHT AND LICENSE" .IX Header "COPYRIGHT AND LICENSE" This software is copyright (c) 2021 by Joshua Hoblitt. .PP This is free software; you can redistribute it and/or modify it under the same terms as the Perl 5 programming language system itself. .PP The full text of the license can be found in the \&\fILICENSE\fR file included with this distribution.