.\" Automatically generated by Pod::Man 2.22 (Pod::Simple 3.13)
.\"
.\" Standard preamble:
.\" ========================================================================
.de Sp \" Vertical space (when we can't use .PP)
.if t .sp .5v
.if n .sp
..
.de Vb \" Begin verbatim text
.ft CW
.nf
.ne \\$1
..
.de Ve \" End verbatim text
.ft R
.fi
..
.\" Set up some character translations and predefined strings.  \*(-- will
.\" give an unbreakable dash, \*(PI will give pi, \*(L" will give a left
.\" double quote, and \*(R" will give a right double quote.  \*(C+ will
.\" give a nicer C++.  Capital omega is used to do unbreakable dashes and
.\" therefore won't be available.  \*(C` and \*(C' expand to `' in nroff,
.\" nothing in troff, for use with C<>.
.tr \(*W-
.ds C+ C\v'-.1v'\h'-1p'\s-2+\h'-1p'+\s0\v'.1v'\h'-1p'
.ie n \{\
.    ds -- \(*W-
.    ds PI pi
.    if (\n(.H=4u)&(1m=24u) .ds -- \(*W\h'-12u'\(*W\h'-12u'-\" diablo 10 pitch
.    if (\n(.H=4u)&(1m=20u) .ds -- \(*W\h'-12u'\(*W\h'-8u'-\"  diablo 12 pitch
.    ds L" ""
.    ds R" ""
.    ds C` ""
.    ds C' ""
'br\}
.el\{\
.    ds -- \|\(em\|
.    ds PI \(*p
.    ds L" ``
.    ds R" ''
'br\}
.\"
.\" Escape single quotes in literal strings from groff's Unicode transform.
.ie \n(.g .ds Aq \(aq
.el       .ds Aq '
.\"
.\" If the F register is turned on, we'll generate index entries on stderr for
.\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index
.\" entries marked with X<> in POD.  Of course, you'll have to process the
.\" output yourself in some meaningful fashion.
.ie \nF \{\
.    de IX
.    tm Index:\\$1\t\\n%\t"\\$2"
..
.    nr % 0
.    rr F
.\}
.el \{\
.    de IX
..
.\}
.\" ========================================================================
.\"
.IX Title "DateTime::Format::Unicode 3"
.TH DateTime::Format::Unicode 3 "2025-01-05" "perl v5.10.1" "User Contributed Perl Documentation"
.\" For nroff, turn off justification.  Always turn off hyphenation; it makes
.\" way too many mistakes in technical documents.
.if n .ad l
.nh
.SH "NAME"
DateTime::Format::Unicode \- Unicode CLDR Formatter for DateTime
.SH "SYNOPSIS"
.IX Header "SYNOPSIS"
.Vb 11
\&    use DateTime::Format::Unicode;
\&    my $fmt = DateTime::Format::Unicode\->new(
\&        locale      => \*(Aqja\-Kana\-JP\*(Aq,
\&        # optional, defaults to the locale medium size date formatting
\&        # See: DateTime::Locale::FromCLDR for more information
\&        pattern     => \*(AqHH:mm:ss\*(Aq,
\&        # optional
\&        time_zone   => \*(AqAsia/Tokyo\*(Aq,
\&        # will make error become fatal and have this API die instead of setting an exception object
\&        on_error    => \*(Aqfatal\*(Aq,
\&    ) || die( DateTime::Format::Unicode\->error );
.Ve
.PP
or, maybe, just:
.PP
.Vb 1
\&    my $fmt = DateTime::Format::Unicode\->new;
.Ve
.PP
which, will default to \f(CW\*(C`locale\*(C'\fR \f(CW\*(C`en\*(C'\fR with date medium-size format pattern \f(CW\*(C`MMM d, y\*(C'\fR
.PP
If you specify a \f(CW\*(C`locale\*(C'\fR that uses a different number system than \f(CW\*(C`latn\*(C'\fR (which is 0 to 9), then \f(CW\*(C`DateTime::Format::Unicode\*(C'\fR will honour it. For example:
.PP
.Vb 5
\&    my $fmt = DateTime::Format::Unicode\->new(
\&        locale => \*(Aqar\-SA\*(Aq,
\&        pattern => \*(Aqd/M/y\*(Aq,
\&    ) || die( DateTime::Format::Unicode\->error );
\&    say $fmt\->format; # ١٠/٩/٢٠٢٤
.Ve
.PP
You can also override the \f(CW\*(C`locale\*(C'\fR's default number system, by another one, as long as it is supported by that \f(CW\*(C`locale\*(C'\fR. For example:
.PP
.Vb 5
\&    my $fmt = DateTime::Format::Unicode\->new(
\&        locale => \*(Aqar\-SA\-u\-nu\-latn\*(Aq,
\&        pattern => \*(Aqd/M/y\*(Aq,
\&    ) || die( DateTime::Format::Unicode\->error );
\&    say $fmt\->format; # ١٠/٩/٢٠٢٤
.Ve
.SH "VERSION"
.IX Header "VERSION"
.Vb 1
\&    v0.1.6
.Ve
.SH "DESCRIPTION"
.IX Header "DESCRIPTION"
This is a Unicode <\s-1CLDR\s0> (Common Locale Data Repository) formatter for DateTime
.PP
It differs from the default formatter used in DateTime with its method format_cldr in several aspects:
.IP "1. It uses DateTime::Locale::FromCLDR" 4
.IX Item "1. It uses DateTime::Locale::FromCLDR"
A much more comprehensive and accurate \s-1API\s0 to dynamically access the Unicode \f(CW\*(C`CLDR\*(C'\fR data whereas the module DateTime relies on, DateTime::Locale, which uses static data from over 1,000 pre-generated modules.
.ie n .IP "2. It allows for any ""locale""" 4
.el .IP "2. It allows for any \f(CWlocale\fR" 4
.IX Item "2. It allows for any locale"
Since, it uses dynamic data, you can use any \f(CW\*(C`locale\*(C'\fR, from the simple \f(CW\*(C`en\*(C'\fR to more complex \f(CW\*(C`es\-001\-valencia\*(C'\fR, or even \f(CW\*(C`ja\-t\-de\-t0\-und\-x0\-medical\*(C'\fR
.IP "3. It allows formatting of datetime intervals" 4
.IX Item "3. It allows formatting of datetime intervals"
Datetime intervals are very important, and unfortunately unsupported by DateTime as of July 2024.
.IP "4. It supports more pattern tokens" 4
.IX Item "4. It supports more pattern tokens"
DateTime format_cldr does not support all of the <\s-1CLDR\s0 pattern tokens>, but DateTime::Format::Unicode does.
.Sp
Known pattern tokens unsupported by DateTime are:
.RS 4
.IP "\(bu" 8
\&\f(CW\*(C`b\*(C'\fR
.Sp
Period of the day, such as \f(CW\*(C`am\*(C'\fR, \f(CW\*(C`pm\*(C'\fR, \f(CW\*(C`noon\*(C'\fR, \f(CW\*(C`midnight\*(C'\fR
.Sp
See \*(L"calendar_term\*(R" in Locale::Unicode::Data and its corollary \*(L"day_period\*(R" in Locale::Unicode::Data
.IP "\(bu" 8
\&\f(CW\*(C`B\*(C'\fR
.Sp
Flexible day periods, such as \f(CW\*(C`at night\*(C'\fR
.Sp
See \*(L"calendar_term\*(R" in Locale::Unicode::Data and its corollary \*(L"day_period\*(R" in Locale::Unicode::Data
.IP "\(bu" 8
\&\f(CW\*(C`O\*(C'\fR
.Sp
Zone, such as \f(CW\*(C`O\*(C'\fR to get the short localized \s-1GMT\s0 format \f(CW\*(C`GMT\-8\*(C'\fR, or \f(CW\*(C`OOOO\*(C'\fR to get the long localized \s-1GMT\s0 format \f(CW\*(C`GMT\-08:00\*(C'\fR
.IP "\(bu" 8
\&\f(CW\*(C`r\*(C'\fR
.Sp
Related Gregorian year (numeric).
.Sp
The documentation states that \*(L"For the Gregorian calendar, the ‘r’ year is the same as the ‘u’ year.\*(R"
.IP "\(bu" 8
\&\f(CW\*(C`U\*(C'\fR
.Sp
Cyclic year name. However, since this is for non gregorian calendars, like Chinese or Hindu calendars, and since DateTime only supports gregorian calendar, we do not support it either.
.IP "\(bu" 8
\&\f(CW\*(C`x\*(C'\fR
.Sp
Timezone, such as \f(CW\*(C`x\*(C'\fR would be \f(CW\*(C`\-08\*(C'\fR, \f(CW\*(C`xx\*(C'\fR \f(CW\*(C`\-0800\*(C'\fR or \f(CW+0800\fR, \f(CW\*(C`xxx\*(C'\fR would be \f(CW\*(C`\-08:00\*(C'\fR or \f(CW\*(C`+08:00\*(C'\fR, \f(CW\*(C`xxxx\*(C'\fR would be \f(CW\*(C`\-0800\*(C'\fR or \f(CW+0000\fR and \f(CW\*(C`xxxxx\*(C'\fR would be \f(CW\*(C`\-08:00\*(C'\fR, or \f(CW\*(C`\-07:52:58\*(C'\fR or \f(CW\*(C`+00:00\*(C'\fR
.IP "\(bu" 8
\&\f(CW\*(C`X\*(C'\fR
.Sp
Timezone, such as \f(CW\*(C`X\*(C'\fR (\f(CW\*(C`\-08\*(C'\fR or \f(CW+0530\fR or \f(CW\*(C`Z\*(C'\fR), \f(CW\*(C`XX\*(C'\fR (\f(CW\*(C`\-0800\*(C'\fR or \f(CW\*(C`Z\*(C'\fR), \f(CW\*(C`XXX\*(C'\fR (\f(CW\*(C`\-08:00\*(C'\fR), \f(CW\*(C`XXXX\*(C'\fR (\f(CW\*(C`\-0800\*(C'\fR or \f(CW\*(C`\-075258\*(C'\fR or \f(CW\*(C`Z\*(C'\fR), \f(CW\*(C`XXXXX\*(C'\fR (\f(CW\*(C`\-08:00\*(C'\fR or \f(CW\*(C`\-07:52:58\*(C'\fR or \f(CW\*(C`Z\*(C'\fR)
.RE
.RS 4
.RE
.PP
DateTime::Format::Unicode only formats \f(CW\*(C`CLDR\*(C'\fR datetime patterns, and does not parse them back into a DateTime object. If you want to achieve that, there is already the module DateTime::Format::CLDR that does this. DateTime::Format::CLDR relies on \*(L"format_cldr\*(R" in DateTime for \f(CW\*(C`CLDR\*(C'\fR formatting by the way.
.SH "CONSTRUCTOR"
.IX Header "CONSTRUCTOR"
.SS "new"
.IX Subsection "new"
This takes some hash or hash reference of options, instantiates a new DateTime::Format::Unicode object, and returns it.
.PP
Supported options are as follows. Each option can be later accessed or modified by their associated method.
.IP "\(bu" 4
\&\f(CW\*(C`locale\*(C'\fR
.Sp
A locale, which may be very simple like \f(CW\*(C`en\*(C'\fR or much more complex like \f(CW\*(C`ja\-t\-de\-t0\-und\-x0\-medical\*(C'\fR or maybe \f(CW\*(C`es\-039\-valencia\*(C'\fR (valencian variant of Spanish as spoken in South Europe)
.Sp
If not provided, this will default to \f(CW\*(C`en\*(C'\fR
.IP "\(bu" 4
\&\f(CW\*(C`on_error\*(C'\fR
.Sp
Specifies what to do upon error. Possible values are: \f(CW\*(C`undef\*(C'\fR (default behaviour), \f(CW\*(C`fatal\*(C'\fR (will die), or a \f(CW\*(C`CODE\*(C'\fR reference that will be called with the exception object as its sole argument, before \f(CW\*(C`undef\*(C'\fR is returned in scalar context, or an empty list in list context.
.IP "\(bu" 4
\&\f(CW\*(C`pattern\*(C'\fR
.Sp
A \f(CW\*(C`CLDR\*(C'\fR pattern. If none is provided, this will default to the medium-size date pattern for the given \f(CW\*(C`locale\*(C'\fR. For example, as per the \f(CW\*(C`CLDR\*(C'\fR, for English, this would be \f(CW\*(C`MMM d, y\*(C'\fR whereas for the \f(CW\*(C`locale\*(C'\fR \f(CW\*(C`ja\*(C'\fR, this would be \f(CW\*(C`y/MM/dd\*(C'\fR
.IP "\(bu" 4
\&\f(CW\*(C`time_zone\*(C'\fR
.Sp
Set the timezone by providing either a DateTime::TimeZone object, or a string representing a timezone.
.Sp
It defaults to the special DateTime timezone floating
.SH "METHODS"
.IX Header "METHODS"
.SS "error"
.IX Subsection "error"
Used as a mutator, this sets an exception object and returns an \f(CW\*(C`DateTime::Format::Unicode::NullObject\*(C'\fR in object context (such as when chaining), or \f(CW\*(C`undef\*(C'\fR in scalar context, or an empty list in list context.
.PP
The \f(CW\*(C`DateTime::Format::Unicode::NullObject\*(C'\fR class prevents the perl error of \f(CW\*(C`Can\*(Aqt call method "%s" on an undefined value\*(C'\fR (see perldiag). Upon the last method chained, \f(CW\*(C`undef\*(C'\fR is returned in scalar context or an empty list in list context.
.SS "format_datetime"
.IX Subsection "format_datetime"
.Vb 5
\&    my $fmt = DateTime::Format::Unicode\->new(
\&        locale => \*(Aqen\*(Aq,
\&        pattern => "Hello the time is H:m:s",
\&    );
\&    my $str = $fmt\->format_datetime( $dt );
.Ve
.PP
or
.PP
.Vb 6
\&    my $fmt = DateTime::Format::Unicode\->new(
\&        locale => \*(Aqen\*(Aq,
\&    );
\&    my $str = $fmt\->format_datetime( $dt,
\&        pattern => "Hello the time is H:m:s",
\&    );
.Ve
.PP
This takes a DateTime object, or if none is provided, it will instantiate one using \*(L"now\*(R" in DateTime, and formats the pattern that was set and return the resulting formatted string.
.PP
It takes an optional hash or hash reference of options.
.PP
The options supported are:
.IP "\(bu" 4
pattern
.Sp
A pattern to use to format the datetime. If provided, it will override the default set with the method pattern
.SS "format_interval"
.IX Subsection "format_interval"
.Vb 5
\&    my $fmt = DateTime::Format::Unicode\->new(
\&        locale => \*(Aqen\*(Aq,
\&        pattern => "GyMMMd",
\&    );
\&    my $str = $fmt\->format_interval( $dt1, $dt2 );
.Ve
.PP
or
.PP
.Vb 6
\&    my $fmt = DateTime::Format::Unicode\->new(
\&        locale => \*(Aqen\*(Aq,
\&    );
\&    my $str = $fmt\->format_interval( $dt1, $dt2
\&        pattern => "GyMMMd",
\&    );
.Ve
.PP
This takes 2 datetime objects and it returns a formatted string according to the specified locale and based on the interval pattern \s-1ID\s0 provided with the pattern argument or method.
.PP
Alternatively, you can pass a \f(CW\*(C`pattern\*(C'\fR option that will override the default value set with the method pattern
.PP
You can retrieve an hash of interval format \s-1ID\s0 to its interval format pattern by using DateTime::Locale::FromCLDR. For example:
.PP
.Vb 2
\&    my $locale = DateTime::Locale::FromCLDR\->new( \*(Aqen\*(Aq );
\&    my $ref = $locale\->interval_formats;
.Ve
.PP
This would produce an hash like this:
.PP
.Vb 10
\&    {
\&        Bh => [qw( B h )],
\&        Bhm => [qw( B h m )],
\&        d => ["d"],
\&        Gy => [qw( G y )],
\&        GyM => [qw( G M y )],
\&        GyMd => [qw( d G M y )],
\&        GyMEd => [qw( d G M y )],
\&        GyMMM => [qw( G M y )],
\&        GyMMMd => [qw( d G M y )],
\&        GyMMMEd => [qw( d G M y )],
\&        H => ["H"],
\&        h => [qw( a h )],
\&        Hm => [qw( H m )],
\&        hm => [qw( a h m )],
\&        Hmv => [qw( H m )],
\&        hmv => [qw( a h m )],
\&        Hv => ["H"],
\&        hv => [qw( a h )],
\&        M => ["M"],
\&        Md => [qw( d M )],
\&        MEd => [qw( d M )],
\&        MMM => ["M"],
\&        MMMd => [qw( d M )],
\&        MMMEd => [qw( d M )],
\&        y => ["y"],
\&        yM => [qw( M y )],
\&        yMd => [qw( d M y )],
\&        yMEd => [qw( d M y )],
\&        yMMM => [qw( M y )],
\&        yMMMd => [qw( d M y )],
\&        yMMMEd => [qw( d M y )],
\&        yMMMM => [qw( M y )],
\&    }
.Ve
.PP
The method will try to get the interval greatest difference between the two DateTime objects. If the two objects are equal, the greatest difference will be a day (\f(CW\*(C`d\*(C'\fR). Possibile values are: \f(CW\*(C`B\*(C'\fR (day period), \f(CW\*(C`G\*(C'\fR (eras), \f(CW\*(C`H\*(C'\fR (hours 0\-23), \f(CW\*(C`M\*(C'\fR (minutes), \f(CW\*(C`a\*(C'\fR (am/pm), \f(CW\*(C`d\*(C'\fR (days), \f(CW\*(C`h\*(C'\fR (hours 1\-12), \f(CW\*(C`m\*(C'\fR (minutes), \f(CW\*(C`y\*(C'\fR (years)
.PP
If the method is unable to get a format pattern based on the interval format \s-1ID\s0 provided, it will assume this is a custom format pattern, and will attempt at breaking it down. If that does not succeed, it will return an error.
.SH "Errors"
.IX Header "Errors"
This module does not die upon errors unless requested to. Instead it sets an error object that can be retrieved.
.PP
When an error occurred, an error object will be set and the method will return \f(CW\*(C`undef\*(C'\fR in scalar context and an empty list in list context.
.PP
The only occasions when this module will die is when there is an internal design error, which would be my fault, or if the value set with on_error is \f(CW\*(C`fatal\*(C'\fR or also if the \f(CW\*(C`CODE\*(C'\fR reference set with on_error would, itself, die.
.SH "AUTHOR"
.IX Header "AUTHOR"
Jacques Deguest <\fIjack@deguest.jp\fR>
.SH "SEE ALSO"
.IX Header "SEE ALSO"
DateTime, DateTime::Format::FromCLDR, Locale::Unicode, Locale::Unicode::Data, DateTime::Locale
.SH "COPYRIGHT & LICENSE"
.IX Header "COPYRIGHT & LICENSE"
Copyright(c) 2024 \s-1DEGUEST\s0 Pte. Ltd.
.PP
All rights reserved.
.PP
This program is free software; you can redistribute it and/or modify it under the same terms as Perl itself.