DateTim...:ISO8601(3)

💅 NAME

Okay so bestie, let me introduce you to DateTime::Format::ISO8601 — the manual page here is DateTim...:ISO8601(3) from the User Contributed Perl Documentation crew — and it parses ISO8601 formats. That's the whole vibe. ✨

---

🎀 VERSION

version 0.19 — iconic, current, slaying.

---

🦋 SYNOPSIS

Here's the whole mood in code, no notes:

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);

Like… you can go class-method mode or you can build an object first, both are valid, we don't gatekeep. 🫶

---

🌸 DESCRIPTION

It parses almost all ISO8601 date and time formats. almost — because ISO8601 time-intervals are gonna be supported in a later release, so hold that thought, it's giving "coming soon to a CPAN near you". 💀

---

⭐ METHODS

This class provides the following methods:

🌱 Constructors

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

Accepts an optional hash. Optional! Chill! 😌

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

• base_datetime — a DateTime object that gets used to fill in the missing info when your date/time format is incomplete. (Picture it as the backup dancer who steps in when someone doesn't show. 💃) This key is optional.
• cut_off_year — an integer that's the cut-off point for deciding whether a 2-digit year means 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 controlling whether a 2-digit year gets interpreted as being in the current century (unless a base_datetime is set), or whether 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. Same girly, different instance. 👯‍♀️

🔮 Object Methods

$iso8601->base_datetime

Returns a DateTime object if a base_datetime has been set. If not? You get nothing, respectfully.

$iso8601->set_base_datetime( object => $object )

Accepts a DateTime object that will be used to fill in missing information from incomplete date/time formats. Same job as the constructor key, just doing it live. ✨

$iso8601->cut_off_year

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

$iso8601->set_cut_off_year($int)

Accepts an integer representing the cut-off point between interpreting 2-digit years as 19xx or 20xx. And yes, the original doc literally says this:

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

(not me noticing it says legacy_year in there — I'm just the messenger, copying it exactly, don't come for me 🙈)

$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 an 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 you call it with no parameters, this method returns the default value for cut_off_year. Bestie gives and receives. 💅

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. Call it with no parameters and it returns 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 section for the whole menu, okay?

🎀 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 by including nanoseconds/milliseconds and the correct timezone offset. So it's like that method's glow-up. 🔥

---

🌈 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. Choose your fighter. 🥊

🪞 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. (Six. Digits. Periodt.)
• Precision — If a format doesn't include a year, all larger time units 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.

Note: sub-nanosecond times are truncated. 😭

🌸 Supported via parse_datetime

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

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'. (Optional! We love a flexible queen.)
• 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. (Being upfront about it, love that for us.)

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. 💀 (Future us will eat, current us does not.)

🦋 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. 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. 🗡️✨ (the katana thing is a direct quote, I would never make that up)
• Tom Phoenix (PHOENIX) and PDX.pm for helping 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". (The lore is immaculate.)
• 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. (Valid complaint, honestly.)
• Everyone at the DateTime "Asylum". 🏥🫶

---

🌟 SEE ALSO

• DateTime
• DateTime::Format::Builder

---

🫶 SUPPORT

Bugs may be submitted at <https://github.com/houseabsolute/DateTime-Format-ISO8601/issues>. Found a bug? Report it, bestie, that's self-care. 🐛

---

💖 SOURCE

The source code repository for DateTime-Format-ISO8601 can be found at <https://github.com/houseabsolute/DateTime-Format-ISO8601>. Go snoop, it's fine.

---

🧚 AUTHORS

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

---

🍓 CONTRIBUTORS

• Doug Bell <doug@preaction.me>
• joe <draxil@gmail.com>
• Liam Widdowson <lbw@telstra.com>
• Thomas Klausner <domm@plix.at>
• Timothy Legge <timlegge@gmail.com>
• William Ricker <bill.n1vux@gmail.com>

Look at that roster. The group chat is thriving. 👑

---

💀 COPYRIGHT AND LICENSE

This software is copyright (c) 2026 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. 📄

---

and that's the whole page, bestie — perl v5.42.2, dated 2026-03-15, from the DateTim...:ISO8601(3) manual, delivered fresh with love 💅💖✨ go parse something iconic 🦋🌸