Time::Str
Parse and format date/time strings in multiple standard formats.
use Time::Str qw(str2time str2date time2str);
# Parse to Unix timestamp
my $time = str2time('2024-12-24T15:30:45Z');
# 1735052445
my $time = str2time('Mon, 24 Dec 2012 15:30:45 +0100', format => 'RFC2822');
# Parse to components
my %date = str2date('2024-12-24T15:30:45.500+01:00');
# (year => 2024, month => 12, day => 24, hour => 15,
# minute => 30, second => 45, nanosecond => 500000000,
# tz_offset => 60)
# Format Unix timestamp
my $str = time2str(1735052445);
# '2024-12-24T15:30:45Z'
my $str = time2str(1735052445, format => 'RFC2822', offset => 60);
# 'Tue, 24 Dec 2024 16:30:45 +0100'
Supported Formats
Profiles of ISO 8601
| Format | Example |
|-----------------------------------------------------------------|------------------------------|
| ISO8601 | 20241224T153045.500+0100 |
| RFC4287 | 2024-12-24T15:30:45Z |
| W3CDTF | 2024-12-24T15:30:45+01:00 |
| RFC5545 | 20241224T153045Z |
Based on ISO 8601
| Format | Example |
|-----------------------------------------------------------------|-------------------------------------------|
| RFC3339 | 2024-12-24 15:30:45+01:00 |
| RFC9557 | 2024-12-24 15:30:45+01:00[Europe/Paris] |
| ISO9075 | 2024-12-24 15:30:45 +01:00 |
| ASN1GT | 20241224153045Z |
| ASN1UT | 241224153045Z |
| RFC5280 | 241224153045Z |
RFC / IMF / HTTP / IMAP
| Format | Example |
|-----------------------------------------------------------------|--------------------------------------|
| RFC2822 | Tue, 24 Dec 2024 15:30:45 +0100 |
| RFC2616 | Tue, 24 Dec 2024 15:30:45 GMT |
| RFC3501 | 24-Dec-2024 15:30:45 +0100 |
Unix / C Library
| Format | Example |
|-----------------------------------------------------------------|--------------------------------------|
| ANSIC | Tue Dec 24 15:30:45 2024 |
| UnixDate | Tue Dec 24 15:30:45 UTC 2024 |
| UnixStamp | Tue Dec 24 15:30:45.500 2024 UTC |
| GitDate | Tue Dec 24 15:30:45 2024 +0100 |
| RubyDate | Tue Dec 24 15:30:45 +0100 2024 |
UnixStamp is a superset of ANSIC, GitDate, RubyDate, and UnixDate.
Other
| Format | Example |
|------------------------------------------------------------------|--------------------------------------|
| ECMAScript | Tue Dec 24 2024 15:30:45 GMT+0100 |
| CLF | 24/Dec/2024:15:30:45 +0100 |
| DateTime | (permissive, multi-format parser) |
DateTime can parse ISO8601 (extended format), RFC3339, RFC9557,
RFC4287, W3CDTF, ISO9075, RFC2822, RFC2616, RFC3501, and
ECMAScript formats.
Each format is implemented according to its specification. Optional fields are optional. Constrained fields are validated. Day names, when present, are verified against the actual date.
The DateTime Format
The DateTime format is a permissive parser for real-world dates that does
not use heuristics. If it cannot parse the input unambiguously, it croaks.
str2date('Monday, 24th December 2024 at 3:30 PM UTC+01:00',
format => 'DateTime');
str2date('2024-12-24T15:30:45+01:00[Europe/Stockholm]',
format => 'DateTime');
str2date('24.XII.2024', format => 'DateTime');
Numeric dates must be in year-month-day order. Ordinal suffixes must match the day number. Four-digit years are required.
See DATETIME FORMAT PARSING in the documentation.
Installation
cpanm Time::Str
Requires Perl 5.10.1 or later. Runtime dependencies are Carp and
Exporter, both core modules.
Optional C/XS
The XS backend (C99) is loaded when a compiler is available; otherwise it
falls back to Pure Perl. The TIME_STR_PP environment variable forces the
Pure Perl path.
say Time::Str::IMPLEMENTATION; # "XS" or "PP"
The XS backend includes native C parsers (generated by Ragel) for ASN.1
GeneralizedTime, ECMAScript, ISO 8601, ISO 9075, RFC 2822, RFC 3339,
RFC 4287, RFC 9557 and W3CDTF formats. When available, these are
tried first; otherwise parsing falls back to the precompiled regexps from
Time::Str::Regexp. Both paths produce identical results.
Related Modules
- Time::Str::Regexp - Precompiled regexps with named captures for all formats
- Time::Str::Token - Token parsers (month names, day names, timezone offsets)
- Time::Str::Calendar - Gregorian calendar utilities (leap year, day-of-week, RDN conversion)
Documentation
Full documentation is available on MetaCPAN or via perldoc Time::Str after installation.
Standards
- ISO 8601:2019
- RFC 3339
- RFC 2822 / RFC 5322
- RFC 2616 / RFC 7231
- RFC 3501 / RFC 9051
- RFC 4287
- RFC 5280
- RFC 5545
- RFC 9557
- ISO 9075
- ITU-T X.680 / ISO/IEC 8824-1 (ASN.1)
- W3C Date and Time Formats
- ECMAScript Date.prototype.toString
Author
Christian Hansen
License
This library is free software; you can redistribute it and/or modify it under the same terms as Perl itself.