NAME
    DateTime::Format::ISO8601::Format - Format DateTime as ISO8601 date/time
    string

VERSION
    This document describes version 0.001 of
    DateTime::Format::ISO8601::Format (from Perl distribution
    DateTime-Format-ISO8601-Format), released on 2018-06-23.

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.555
     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
    supplies the formatting functionality "missing from"
    DateTime::Format::ISO8601. I have suggested that the formatting
    functionality is included in the latter module (see
    <https://rt.cpan.org/Ticket/Display.html?id=125660>).

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(C<%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-ISO86
    01-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

    DateTime::Format::Duration::ISO8601 to parse and format ISO8601
    durations.

AUTHOR
    perlancar <perlancar@cpan.org>

COPYRIGHT AND LICENSE
    This software is copyright (c) 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.

