NAME DateTime::Format::ISO8601::Format - Format DateTime object as ISO8601 date/time string VERSION This document describes version 0.005 of DateTime::Format::ISO8601::Format (from Perl distribution DateTime-Format-ISO8601-Format), released on 2020-08-21. SYNOPSIS use DateTime::Format::ISO8601::Format; my $format = DateTime::Format::ISO8601::Format->new( # time_zone => '...', # optional, default is DateTime object's time zone # second_precision => 3, # optional, default is undef ); my $dt_floating = DateTime->new(year=>2018, month=>6, day=>23, hour=>19, minute=>2, second=>3); my $dt_floating_frac = DateTime->new(year=>2018, month=>6, day=>23, hour=>19, minute=>2, second=>3, nanosecond=>0.456e9); my $dt_utc = DateTime->new(year=>2018, month=>6, day=>23, hour=>19, minute=>2, second=>3, time_zone=>'UTC'); my $dt_sometz = DateTime->new(year=>2018, month=>6, day=>23, hour=>19, minute=>2, second=>3, time_zone=>'Asia/Jakarta'); Formatting dates: say $format->format_date($dt_floating); # => 2018-06-23 say $format->format_date($dt_floating_frac); # => 2018-06-23 say $format->format_date($dt_utc); # => 2018-06-23 say $format->format_date($dt_sometz); # => 2018-06-23 # effect of setting time_zone attribute to 'Asia/Jakarta' (which has the offset +07:00): say $format->format_date($dt_floating); # => 2018-06-23 say $format->format_date($dt_floating_frac); # => 2018-06-23 say $format->format_date($dt_utc); # => 2018-06-24 say $format->format_date($dt_sometz); # => 2018-06-23 Formatting times: say $format->format_time($dt_floating); # => 19:02:03 say $format->format_time($dt_floating_frac); # => 19:02:03.456 say $format->format_time($dt_utc); # => 19:02:03Z say $format->format_time($dt_sometz); # => 19:02:03+07:00 # effect of setting time_zone attribute to 'Asia/Jakarta' (which has the offset of +07:00): say $format->format_time($dt_floating); # => 19:02:03+07:00 say $format->format_time($dt_floating_frac); # => 19:02:03.456+07:00 say $format->format_time($dt_utc); # => 02:02:03+07:00 say $format->format_time($dt_sometz); # => 19:02:03+07:00 # effect of setting second_precision to 3 say $format->format_time($dt_floating); # => 19:02:03.000 say $format->format_time($dt_floating_frac); # => 19:02:03.456 say $format->format_time($dt_utc); # => 19:02:03.000Z say $format->format_time($dt_sometz); # => 19:02:03.000+07:00 Formatting date+time: say $format->format_datetime($dt_floating); # => 2018-06-23T19:02:03 say $format->format_datetime($dt_floating_frac); # => 2018-06-23T19:02:03.456 say $format->format_datetime($dt_utc); # => 2018-06-23T19:02:03Z say $format->format_datetime($dt_sometz); # => 2018-06-23T19:02:03+07:00 DESCRIPTION This module formats DateTime objects as ISO8601 date/time strings. It complements DateTime::Format::ISO8601. ATTRIBUTES time_zone Optional. Used to force the time zone of DateTime objects to be formatted. Either string containing time zone name (e.g. "Asia/Jakarta", "UTC") or DateTime::TimeZone object. Will be converted to DateTime::TimeZone internally. The default is to use the DateTime object's time zone. DateTime object with floating time zone will not have the time zone designation in the ISO8601 string, e.g.: 19:02:03 2018-06-23T19:02:03 DateTime object with UTC time zone will have the "Z" time zone designation: 19:02:03Z 2018-06-23T19:02:03Z DateTime object with other time zones will have the "+hh:mm" time zone designation: 19:02:03+07:00 2018-06-23T19:02:03+07:00 second_precision Optional. A non-negative integer. Used to control formatting (number of decimals) of the second fraction. The default is to only show fraction when they exist, with whatever precision "sprintf("%s")" outputs. METHODS new Usage: DateTime::Format::ISO8601::Format->new(%attrs) => obj format_date Usage: $format->format_date($dt) => str format_time Usage: $format->format_time($dt) => str format_datetime Usage: $format->format_datetime($dt) => str HOMEPAGE Please visit the project's homepage at . SOURCE Source repository is at . BUGS Please report any bugs or feature requests on the bugtracker website When submitting a bug or request, please include a test-file or a patch to an existing test-file that illustrates the bug or desired feature. SEE ALSO DateTime::Format::ISO8601. Before v0.12, DateTime::Format::ISO8601 does not feature a "format_datetime()" method, so DateTime::Format::ISO8601::Format supplies that functionality. After v0.12, DateTime::Format::ISO8601 already has "format_datetime()", but currently DateTime::Format::ISO8601::Format's version is faster (see Bencher::Scenario::FormattingISO8601DateTime) and there are "format_date" and "format_time" as well. So I'm keeping this module for now. DateTime::Format::Duration::ISO8601 to parse and format ISO8601 durations. AUTHOR perlancar COPYRIGHT AND LICENSE This software is copyright (c) 2020, 2018 by perlancar@cpan.org. This is free software; you can redistribute it and/or modify it under the same terms as the Perl 5 programming language system itself.