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 https://metacpan.org/release/DateTime-Format-ISO8601-Format.

SOURCE

Source repository is at https://github.com/perlancar/perl-DateTime-Format-ISO8601-Format.

BUGS

Please report any bugs or feature requests on the bugtracker website https://rt.cpan.org/Public/Dist/Display.html?Name=DateTime-Format-ISO8601-Format

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 <perlancar@cpan.org>

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.

cpanm DateTime::Format::ISO8601::Format

perl -MCPAN -e shell
install DateTime::Format::ISO8601::Format