DateTime-Locale-FromCLDR
view release on metacpan or search on metacpan
NAME
DateTime::Locale::FromCLDR - DateTime Localised Data from Unicode CLDR
SYNOPSIS
use DateTime::Locale::FromCLDR;
my $locale = DateTime::Locale::FromCLDR->new( 'ja-Kana-JP' ) ||
die( DateTime::Locale::FromCLDR->error );
my $locale = DateTime::Locale::FromCLDR->new( 'ja-Kana-JP', calendar => 'japanese' ) ||
die( DateTime::Locale::FromCLDR->error );
my $array = $locale->am_pm_abbreviated;
my $array = $locale->available_formats;
$locale->calendar( 'hebrew' );
my $str = $locale->calendar;
# a Locale::Unicode object that stringifies to the initial locale value (ja-Kana-JP)
my $obj = $locale->code;
my $str = $locale->date_at_time_format_full;
my $str = $locale->date_at_time_format_long;
my $str = $locale->date_at_time_format_medium;
my $str = $locale->date_at_time_format_short;
my $str = $locale->date_format_default;
my $str = $locale->date_format_full;
my $str = $locale->date_format_long;
my $str = $locale->date_format_medium;
my $str = $locale->date_format_short;
my $str = $locale->date_formats;
my $str = $locale->datetime_format;
my $str = $locale->datetime_format_default;
my $str = $locale->datetime_format_full;
my $str = $locale->datetime_format_long;
my $str = $locale->datetime_format_medium;
my $str = $locale->datetime_format_short;
my $str = $locale->day_format_abbreviated;
my $str = $locale->day_format_narrow;
my $str = $locale->day_format_short;
my $str = $locale->day_format_wide;
my $str = $locale->day_period_format_abbreviated( $datetime_object );
my $str = $locale->day_period_format_narrow( $datetime_object );
my $str = $locale->day_period_format_wide( $datetime_object );
my $str = $locale->day_period_stand_alone_abbreviated( $datetime_object );
my $str = $locale->day_period_stand_alone_narrow( $datetime_object );
my $str = $locale->day_period_stand_alone_wide( $datetime_object );
my $hashref = $locale->day_periods;
my $str = $locale->day_stand_alone_abbreviated;
my $str = $locale->day_stand_alone_narrow;
my $str = $locale->day_stand_alone_short;
my $str = $locale->day_stand_alone_wide;
my $str = $locale->default_date_format_length;
my $str = $locale->default_time_format_length;
my $str = $locale->era_abbreviated;
my $str = $locale->era_narrow;
my $str = $locale->era_wide;
my $str = $locale->first_day_of_week;
my $str = $locale->format_for( 'yMEd' );
my $str = $locale->gmt_format(0);
my $str = $locale->gmt_format(3600);
my $str = $locale->gmt_format(-3600);
my $str = $locale->gmt_format(-3600, width => 'short');
my $str = $locale->gmt_format(-3600, { width => 'short' });
# Alias for method 'code'
my $obj = $locale->id;
my $array = $locale->interval_format( GyMEd => 'd' );
my $hashref = $locale->interval_formats;
my $greatest_diff = $locale->interval_greatest_diff( $datetime_object_1, $datetime_object_2 );
my $str = $locale->language;
my $str = $locale->language_code;
# Alias for method 'language_code'
my $str = $locale->language_id;
# Locale::Unicode object
my $obj = $locale->locale;
# Equivalent to $locale->locale->as_string
my $str = $locale->locale_as_string;
# As per standard, it falls back to 'wide' format if it is not available
my $str = $locale->metazone_daylight_long( metazone => 'Taipei' );
# Missing the 'offset' argument
my $str = $locale->format_gmt;
# More code
}
catch( $e )
{
say "Oops: ", $e->message;
}
VERSION
v0.5.0
DESCRIPTION
This is a powerful replacement for DateTime::Locale and
DateTime::Locale::FromData that use static data from over 1,000
pre-generated modules, whereas DateTime::Locale::FromCLDR builds a
"locale" object to access its Unicode CLDR <https://cldr.unicode.org/>
(Common Locale Data Repository) data from SQLite data made available
with Locale::Unicode::Data
It provides the same API as DateTime::Locale, but in a dynamic way. This
is important since in the Unicode LDML specifications
<https://unicode.org/reports/tr35/>, a "locale" inherits from its
parent's data.
Once a data is retrieved by a method, it is cached to avoid waste of
time.
It also adds a few methods to access the "locale" at time patterns
<https://unicode.org/reports/tr35/tr35-dates.html#dateTimeFormats>, such
as date_at_time_format_full, and native_variants
It also provides key support for day period
<https://unicode.org/reports/tr35/tr35-dates.html#Day_Period_Rule_Sets>
It also provides support for interval datetime, and a method to find the
greatest datetime difference element between 2 datetimes, as well as a
method to get all the available format patterns for intervals, and a
method to retrieve the components of an specific interval patterns
It adds the "short" format for day missing in DateTime::Locale::FromData
Note that in "CLDR" parlance, there are standard pattern formats. For
example "full", "long", "medium", "short" or also "abbreviated",
"short", "wide", "narrow" providing various level of conciseness.
CONSTRUCTOR
new
# Japanese as spoken in Japan
my $locale = DateTime::Locale::FromCLDR->new( 'ja-JP' ) ||
die( DateTime::Locale::FromCLDR->error );
# Okinawan as spoken in Japan Southern islands
my $locale = DateTime::Locale::FromCLDR->new( 'ryu-Kana-JP-t-de-t0-und-x0-medical' ) ||
die( DateTime::Locale::FromCLDR->error );
use Locale::Unicode;
my $loc = Locale::Unicode->new( 'fr-FR' );
my $locale = DateTime::Locale::FromCLDR->new( $loc ) ||
die( DateTime::Locale::FromCLDR->error );
Specifying a calendar ID other than the default "gregorian":
my $locale = DateTime::Locale::FromCLDR->new( 'ja-JP', calendar => 'japanese' ) ||
die( DateTime::Locale::FromCLDR->error );
or, using an hash reference:
my $locale = DateTime::Locale::FromCLDR->new( 'ja-JP', { calendar => 'japanese' } ) ||
die( DateTime::Locale::FromCLDR->error );
Instantiate a new DateTime::Locale::FromCLDR object based on a "locale"
provided, and returns it. By default, it uses the calendar "gregorian",
but you can specify a different one with the "calendar" option.
You can provide any "locale", even complex one as shown above, and only
its core part will be retained. So, for example:
my $locale = DateTime::Locale::FromCLDR->new( 'ryu-Kana-JP-t-de-t0-und-x0-medical' ) ||
die( DateTime::Locale::FromCLDR->error );
say $locale; # ryu-Kana-JP
If an error occurs, it sets an exception object and returns "undef" in
scalar context, or an empty list in list context, or possibly a special
"DateTime::Locale::FromCLDR::NullObject" in object context. See "error"
for more information.
The object is overloaded and stringifies into the core part of the
original string provided upon instantiation.
The core part is comprised of the "language" ID, an optional "script"
ID, an optional "territory" ID and zero or multiple "variant" IDs. See
Locale::Unicode and the LDML specifications
<https://unicode.org/reports/tr35/tr35.html#Locale> for more
information.
METHODS
All methods are read-only unless stated otherwise.
am_pm_abbreviated
This is an alias for am_pm_format_abbreviated
am_pm_format_abbreviated
my $array = $locale->am_pm_format_abbreviated;
Returns an array reference of the terms used to represent "am" and "pm"
The array reference could be empty if the "locale" does not support
specifying "am"/"pm"
For example:
my $locale = DateTime::Locale::FromCLDR->new( 'en' );
my $ampm = $locale->am_pm_abbreviated
say @$ampm; # AM, PM
my $locale = DateTime::Locale::FromCLDR->new( 'ja' );
my $ampm = $locale->am_pm_abbreviated
say @$ampm; # åˆå‰, åˆå¾Œ
my $locale = DateTime::Locale::FromCLDR->new( 'fr' );
my $ampm = $locale->am_pm_abbreviated
say @$ampm; # Empty
See "calendar_term" in Locale::Unicode::Data
am_pm_format_narrow
Same as am_pm_format_abbreviated, but returns the narrow format of the
AM/PM terms.
my $locale = DateTime::Locale::FromCLDR->new( 'en' );
say $locale->am_pm_format_narrow;
am_pm_format_wide
Same as am_pm_format_abbreviated, but returns the wide format of the
AM/PM terms.
my $locale = DateTime::Locale::FromCLDR->new( 'en' );
say $locale->am_pm_format_wide;
am_pm_standalone_abbreviated
Same as am_pm_format_abbreviated, but returns the abbreviated
stand-alone format of the AM/PM terms.
my $locale = DateTime::Locale::FromCLDR->new( 'en' );
say $locale->am_pm_standalone_abbreviated;
am_pm_standalone_narrow
Same as am_pm_format_abbreviated, but returns the narrow stand-alone
format of the AM/PM terms.
my $locale = DateTime::Locale::FromCLDR->new( 'en' );
say $locale->am_pm_standalone_narrow;
am_pm_standalone_wide
Same as am_pm_format_abbreviated, but returns the wide stand-alone
format of the AM/PM terms.
my $locale = DateTime::Locale::FromCLDR->new( 'en' );
say $locale->am_pm_standalone_wide;
available_formats
my $locale = DateTime::Locale::FromCLDR->new( 'en' );
my $array = $locale->available_formats;
Returns an array reference of all the format ID available for this
"locale"
See "calendar_available_format" in Locale::Unicode::Data
available_format_patterns
my $locale = DateTime::Locale::FromCLDR->new( 'en' );
my $ref = $locale->available_format_patterns;
Returns an hash reference of all the available format ID to their
corresponding pattern for the "locale"
See "calendar_available_format" in Locale::Unicode::Data
calendar
my $locale = DateTime::Locale::FromCLDR->new( 'ja-Kana-JP', calendar => 'japanese' ) ||
die( DateTime::Locale::FromCLDR->error );
my $str = $locale->calendar; # japanese
$locale->calendar( 'gregorian' );
Sets or gets the calendar ID used to perform queries along with the
given "locale"
code
my $obj = $locale->code;
Returns the Locale::Unicode object either received or created upon
object instantiation.
date_at_time_format_full
my $str = $locale->date_at_time_format_full;
Returns the full date at time pattern
<https://unicode.org/reports/tr35/tr35-dates.html#dateTimeFormats>
For example:
my $locale = DateTime::Locale::FromCLDR->new( 'en' );
say $locale->date_at_time_format_full;
# EEEE, MMMM d, y 'at' h:mm:ss a zzzz
# Tuesday, July 23, 2024 at 1:26:38 AM UTC
my $locale = DateTime::Locale::FromCLDR->new( 'fr' );
say $locale->date_at_time_format_full;
# EEEE d MMMM y 'Ã ' HH:mm:ss zzzz
# mardi 23 juillet 2024 Ã 01:27:11 UTC
date_at_time_format_long
Same as date_at_time_format_full, but returns the long format pattern.
my $locale = DateTime::Locale::FromCLDR->new( 'en' );
say $locale->date_at_time_format_long;
# MMMM d, y 'at' h:mm:ss a z
# July 23, 2024 at 1:26:11 AM UTC
date_at_time_format_medium
Same as date_at_time_format_full, but returns the medium format pattern.
my $locale = DateTime::Locale::FromCLDR->new( 'en' );
say $locale->date_at_time_format_medium;
# MMM d, y 'at' h:mm:ss a
# Jul 23, 2024 at 1:25:43 AM
date_at_time_format_short
Same as date_at_time_format_full, but returns the short format pattern.
my $locale = DateTime::Locale::FromCLDR->new( 'en' );
say $locale->date_at_time_format_short;
# M/d/yy 'at' h:mm a
# 7/23/24 at 1:25 AM
date_format_default
This is an alias to date_format_medium
date_format_full
my $locale = DateTime::Locale::FromCLDR->new( 'en' );
say $locale->date_format_full;
# EEEE, MMMM d, y
# Tuesday, July 23, 2024
Returns the full date pattern
<https://unicode.org/reports/tr35/tr35-dates.html#dateFormats>
See also "calendar_format_l10n" in Locale::Unicode::Data
date_format_long
Same as date_format_full, but returns the long format pattern.
my $locale = DateTime::Locale::FromCLDR->new( 'en' );
say $locale->date_format_long;
# MMMM d, y
# July 23, 2024
date_format_medium
Same as date_format_full, but returns the medium format pattern.
my $locale = DateTime::Locale::FromCLDR->new( 'en' );
say $locale->date_format_long;
# MMM d, y
# Jul 23, 2024
date_format_short
Same as date_format_full, but returns the short format pattern.
my $locale = DateTime::Locale::FromCLDR->new( 'en' );
say $locale->date_format_short;
# M/d/yy
# 7/23/24
date_formats
my $now = DateTime->now( locale => 'en' );
my $ref = $locale->date_formats;
foreach my $type ( sort( keys( %$ref ) ) )
{
say $type, ":";
say $ref->{ $type };
say $now->format_cldr( $ref->{ $type } ), "\n";
}
Would produce:
full:
EEEE, MMMM d, y
Tuesday, July 23, 2024
long:
MMMM d, y
July 23, 2024
medium:
MMM d, y
Jul 23, 2024
short:
M/d/yy
7/23/24
Returns an hash reference with the keys being: "full", "long", "medium",
"short" and their value the result of their associated date format
methods.
datetime_format
This is an alias for datetime_format_medium
datetime_format_default
This is also an alias for datetime_format_medium
datetime_format_full
my $locale = DateTime::Locale::FromCLDR->new( 'en' );
say $locale->datetime_format_full;
# EEEE, MMMM d, y, h:mm:ss a zzzz
# Tuesday, July 23, 2024, 1:53:27 AM UTC
Returns the full datetime pattern
<https://unicode.org/reports/tr35/tr35-dates.html#dateTimeFormats>
See also "calendar_datetime_format" in Locale::Unicode::Data
datetime_format_long
Same as datetime_format_full, but returns the long format pattern.
my $locale = DateTime::Locale::FromCLDR->new( 'en' );
say $locale->datetime_format_long;
# MMMM d, y, h:mm:ss a z
# July 23, 2024, 1:57:02 AM UTC
datetime_format_medium
Same as datetime_format_full, but returns the medium format pattern.
my $locale = DateTime::Locale::FromCLDR->new( 'en' );
say $locale->datetime_format_medium;
# MMM d, y, h:mm:ss a
# Jul 23, 2024, 2:03:16 AM
datetime_format_short
Same as datetime_format_full, but returns the short format pattern.
my $locale = DateTime::Locale::FromCLDR->new( 'en' );
say $locale->datetime_format_short;
# M/d/yy, h:mm a
# 7/23/24, 2:04 AM
day_format_abbreviated
my $locale = DateTime::Locale::FromCLDR->new( 'en' );
my $days = $locale->day_format_abbreviated;
say @$days;
# Mon, Tue, Wed, Thu, Fri, Sat, Sun
Returns an array reference of week day names abbreviated format with
Monday first and Sunday last.
See also "calendar_term" in Locale::Unicode::Data
day_format_narrow
Same as day_format_abbreviated, but returns the narrow format days.
my $locale = DateTime::Locale::FromCLDR->new( 'en' );
my $days = $locale->day_format_abbreviated;
say @$days;
# M, T, W, T, F, S, S
day_format_short
Same as day_format_abbreviated, but returns the short format days.
my $locale = DateTime::Locale::FromCLDR->new( 'en' );
my $days = $locale->day_format_short;
say @$days;
# Mo, Tu, We, Th, Fr, Sa, Su
day_format_wide
Same as day_format_abbreviated, but returns the wide format days.
my $locale = DateTime::Locale::FromCLDR->new( 'en' );
my $days = $locale->day_format_wide;
say @$days;
# Monday, Tuesday, Wednesday, Thursday, Friday, Saturday, Sunday
day_period_format_abbreviated
my $dt = DateTime->new( year => 2024, hour => 7 );
my $locale = DateTime::Locale::FromCLDR->new( 'en' );
say $locale->day_period_format_abbreviated( $dt );
# in the morning
my $dt = DateTime->new( year => 2024, hour => 13 );
my $locale = DateTime::Locale::FromCLDR->new( 'en' );
say $locale->day_period_format_abbreviated( $dt );
# in the afternoon
my $dt = DateTime->new( year => 2024, hour => 7 );
my $locale = DateTime::Locale::FromCLDR->new( 'ja-Kana-JP' );
say $locale->day_period_format_abbreviated( $dt );
# æœ
# which means "morning" in Japanese
my $dt = DateTime->new( year => 2024, hour => 13 );
my $locale = DateTime::Locale::FromCLDR->new( 'fr' );
say $locale->day_period_format_abbreviated( $dt );
# après-midi
Returns a string representing the localised expression of the period of
day the DateTime object provided is.
If nothing relevant could be found somehow, this will return an empty
string. "undef" is returned only if an error occurred.
This is used to provide the relevant value for the token "B" or "b" in
the Unicode LDML format patterns
See also "calendar_term" in Locale::Unicode::Data, "day_period" in
Locale::Unicode::Data and DateTime::Format::Unicode
day_period_format_narrow
Same as day_period_format_abbreviated, but returns the narrow format of
day period.
my $dt = DateTime->new( year => 2024, hour => 7 );
my $locale = DateTime::Locale::FromCLDR->new( 'en' );
say $locale->day_period_format_narrow( $dt );
# in the morning
day_period_format_wide
Same as day_period_format_abbreviated, but returns the wide format of
day period.
my $dt = DateTime->new( year => 2024, hour => 7 );
my $locale = DateTime::Locale::FromCLDR->new( 'en' );
say $locale->day_period_format_wide( $dt );
# in the morning
day_period_stand_alone_abbreviated
my $dt = DateTime->new( year => 2024, hour => 7 );
my $locale = DateTime::Locale::FromCLDR->new( 'en' );
say $locale->day_period_stand_alone_abbreviated( $dt );
# morning
my $dt = DateTime->new( year => 2024, hour => 13 );
my $locale = DateTime::Locale::FromCLDR->new( 'en' );
say $locale->day_period_stand_alone_abbreviated( $dt );
# afternoon
my $dt = DateTime->new( year => 2024, hour => 7 );
my $locale = DateTime::Locale::FromCLDR->new( 'ja-Kana-JP' );
say $locale->day_period_stand_alone_abbreviated( $dt );
# ""
The previous example would yield nothing, and as per the LDML
specifications
<https://unicode.org/reports/tr35/tr35-dates.html#dfst-period>, you
would need to use the localised AM/PM instead.
my $dt = DateTime->new( year => 2024, hour => 13 );
my $locale = DateTime::Locale::FromCLDR->new( 'fr' );
say $locale->day_period_stand_alone_abbreviated( $dt );
# ap.m.
Returns a string representing the localised expression of the period of
day the DateTime object provided is.
If nothing relevant could be found somehow, this will return an empty
string. "undef" is returned only if an error occurred.
This is used to provide a stand-alone word that can be used as a title,
or in a different context.
See also "calendar_term" in Locale::Unicode::Data, "day_period" in
Locale::Unicode::Data and DateTime::Format::Unicode
day_period_stand_alone_narrow
Same as day_period_stand_alone_abbreviated, but returns the narrow
stand-alone version of the day period.
my $dt = DateTime->new( year => 2024, hour => 13 );
my $locale = DateTime::Locale::FromCLDR->new( 'fr' );
say $locale->day_period_stand_alone_narrow( $dt );
# ap.m.
day_period_stand_alone_wide
Same as day_period_stand_alone_abbreviated, but returns the wide
stand-alone version of the day period.
my $dt = DateTime->new( year => 2024, hour => 13 );
my $locale = DateTime::Locale::FromCLDR->new( 'fr' );
say $locale->day_period_stand_alone_wide( $dt );
# après-midi
day_periods
my $locale = DateTime::Locale::FromCLDR->new( 'en' );
my $hash = $locale->day_periods;
# Would return an hash reference like:
{
midnight => ["00:00", "00:00"],
morning1 => ["06:00", "12:00"],
noon => ["12:00", "12:00"],
afternoon1 => ["12:00", "18:00"],
evening1 => ["18:00", "21:00"],
night1 => ["21:00", "06:00"],
}
Returns an hash reference of day period token and values of 2-elements
array (start time and end time in hours and minutes)
day_stand_alone_abbreviated
my $locale = DateTime::Locale::FromCLDR->new( 'en' );
my $days = $locale->day_stand_alone_abbreviated;
say @$days;
# Mon, Tue, Wed, Thu, Fri, Sat, Sun
Returns an array reference of week day names in abbreviated format with
Monday first and Sunday last.
This is often identical to the "format" type.
See the LDML specifications
<https://unicode.org/reports/tr35/tr35-dates.html#months_days_quarters_e
ras> for more information on the difference between the "format" and
"stand-alone" types.
day_stand_alone_narrow
Same as day_stand_alone_abbreviated, but returns the narrow format days.
my $locale = DateTime::Locale::FromCLDR->new( 'en' );
my $days = $locale->day_stand_alone_narrow;
say @$days;
# M, T, W, T, F, S, S
day_stand_alone_short
Same as day_stand_alone_abbreviated, but returns the short format days.
my $locale = DateTime::Locale::FromCLDR->new( 'en' );
my $days = $locale->day_stand_alone_short;
say @$days;
# Mo, Tu, We, Th, Fr, Sa, Su
day_stand_alone_wide
Same as day_stand_alone_abbreviated, but returns the wide format days.
my $locale = DateTime::Locale::FromCLDR->new( 'en' );
my $days = $locale->day_stand_alone_wide;
say @$days;
# Monday, Tuesday, Wednesday, Thursday, Friday, Saturday, Sunday
default_date_format_length
This returns the string "medium"
default_time_format_length
This returns the string "medium"
era_abbreviated
my $array = $locale->era_abbreviated;
say @$array;
# BC, AD
Returns an array reference of era names in abbreviated format.
See also "calendar_eras_l10n" in Locale::Unicode::Data
era_narrow
Same as era_abbreviated, but returns the narrow format eras.
my $locale = DateTime::Locale::FromCLDR->new( 'en' );
my $array = $locale->era_narrow;
say @$array;
# B, A
era_wide
Same as era_abbreviated, but returns the wide format eras.
my $locale = DateTime::Locale::FromCLDR->new( 'en' );
my $array = $locale->era_wide;
say @$array;
# Before Christ, Anno Domini
error
Used as a mutator, this sets an exception object and returns an
"DateTime::Locale::FromCLDR::NullObject" in object context (such as when
chaining), or "undef" in scalar context, or an empty list in list
context.
The "DateTime::Locale::FromCLDR::NullObject" class prevents the perl
error of "Can't call method "%s" on an undefined value" (see perldiag).
Upon the last method chained, "undef" is returned in scalar context or
an empty list in list context.
fatal
$cldr->fatal(1); # Enable fatal exceptions
$cldr->fatal(0); # Disable fatal exceptions
my $bool = $cldr->fatal;
Sets or get the boolean value, whether to die upon exception, or not. If
set to true, then instead of setting an exception object, this module
will die with an exception object. You can catch the exception object
then after using "try". For example:
use v.5.34; # to be able to use try-catch blocks in perl
use experimental 'try';
no warnings 'experimental';
try
{
my $cldr = DateTime::Locale::FromCLDR->new( 'en', fatal => 1 );
# Forgot the 'offset':
my $str = $locale->format_gmt;
}
catch( $e )
{
say "Error occurred: ", $e->message;
# Error occurred: No value for width was provided.
}
first_day_of_week
my $integer = $locale->first_day_of_week;
Returns an integer ranging from 1 to 7 where 1 means Monday and 7 means
Sunday.
This represents what is the first day of the week for this "locale"
Since the information on the first day of the week pertains to a
"territory", if the "locale" you provided does not have such
information, this method will find out the likely subtag to get the
"locale"'s rightful "territory"
See the LDML specifications about likely subtags
<https://unicode.org/reports/tr35/tr35.html#Likely_Subtags> for more
information.
For example:
my $locale = DateTime::Locale::FromCLDR->new( 'en' );
Since there is no "territory" associated, this will look up the likely
subtag to find the target "locale" is "en-Latn-US", and thus the
"territory" for "en" is "US" and first day of the week is 7
Another example:
my $locale = DateTime::Locale::FromCLDR->new( 'fr-Latn' );
This will ultimately get the territory "FR" and first day of the week is
1
# Okinawan as spoken in the Japanese Southern islands
my $locale = DateTime::Locale::FromCLDR->new( 'ryu' );
This will become "ryu-Kana-JP" and thus the "territory" would be "JP"
and first day of the week is 7
This information is cached in the current object, like for all the other
methods in this API.
format_for
my $locale = DateTime::Locale::FromCLDR->new( 'en' );
my $pattern = $locale->format_for( 'Bhm' );
Provided with the format ID of an available format and this will return
the localised "CLDR" pattern.
Keep in mind that the "CLDR" formatting method of DateTime does not
recognise all the "CLDR" pattern tokens. Thus, for example, if you chose
the standard available pattern "Bhm", this method would return the
localised pattern "h:mm B". However, DateTime does not understand the
token "B"
my $now = DateTime->now( locale => "en", time_zone => "Asia/Tokyo" );
# Assuming $now = 2024-07-23T21:39:39
say $now->format_cldr( 'h:mm B' );
# 9:39 B
But "B" is the day period, which can be looked up with "day_period" in
Locale::Unicode::Data, which provides us with the day period token
"night1", which itself can be looked up with "calendar_term" in
Locale::Unicode::Data and gives us the localised string "at night". Thus
the proper "CLDR" formatting really should be "9:39 at night"
You can use DateTime::Format::Unicode instead of the default DateTime
"CLDR" formatting if you want to get better support for all CLDR pattern
tokens.
With Japanese:
my $locale = DateTime::Locale::FromCLDR->new( 'ja' );
my $pattern = $locale->format_for( 'Bhm' );
# BK:mm
my $now = DateTime->now( locale => "ja", time_zone => "Asia/Tokyo" );
say $now->format_cldr( 'BK:mm' );
# B9:54
But, this should have yielded: "夜9:54" instead.
format_gmt
my $locale = DateTime::Locale::FromCLDR->new( 'en' );
# Get the offset in seconds from the UTC
my $offset = $dt->offset;
my $str = $locale->gmt_format( $offset );
# The 'width' is 'long' by default
my $str = $locale->gmt_format( $offset, width => 'short' );
This returns a localised and formatted GMT timezone given an offset in
seconds of the datetime from UTC.
For example:
* "GMT"
* "UTC"
* "Гринуич"
Optionally, you can provide the "width" option that may have the value
"long" (default), or "short"
If the offset is 0, meaning this is the GMT time, then the localised
representation of "GMT" is returned using timezone_format_gmt_zero,
otherwise it will use the GMT format provided by timezone_format_gmt and
timezone_format_hour for the formatting of the "hours", "minutes" and
possibly "seconds".
Also, if the option "width" is provided with a value "short", then the
GMT hours, minutes, seconds formatting will not be zero padded.
For example:
* "GMT+03:30"
Long
* "GMT+3:30"
Short
* "UTC-03.00"
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( a h m )],
Hm => [qw( H m )],
hmv => [qw( a h m )],
Hmv => [qw( 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 )],
}
Returns an hash reference of all available interval format IDs and their
associated greatest difference token
<https://unicode.org/reports/tr35/tr35-dates.html#intervalFormats>
The "default" interval format pattern is something like "{0} – {1}", but
this changes depending on the "locale" and is not always available.
"{0}" is the placeholder for the first datetime and "{1}" is the
placeholder for the second one.
See "interval_formats" in Locale::Unicode::Data
interval_greatest_diff
my $locale = DateTime::Locale::FromCLDR->new( 'en' );
my $diff = $locale->interval_greatest_diff( $dt1, $dt2 );
my $locale = DateTime::Locale::FromCLDR->new( 'en' );
my $diff = $locale->interval_greatest_diff( $dt1, $dt2, day_period_first => 1 );
# or, using an hash reference instead:
# my $diff = $locale->interval_greatest_diff( $dt1, $dt2, { day_period_first => 1 } );
Provided with 2 DateTime objects, and this will compute the greatest
difference
<https://unicode.org/reports/tr35/tr35-dates.html#intervalFormats>.
Quoting from the LDML specifications
<https://unicode.org/reports/tr35/tr35-dates.html#intervalFormats>:
"The data supplied in CLDR requires the software to determine the
calendar field with the greatest difference before using the format
pattern. For example, the greatest difference in "Jan 10-12, 2008" is
the day field, while the greatest difference in "Jan 10 - Feb 12, 2008"
is the month field. This is used to pick the exact pattern."
If both "DateTime" objects are identical, this will return an empty
string.
You can alter the inner working of the algorithm by providing the option
"day_period_first" with a true value. This will prioritise the day
period over the AM/PM (morning vs afternoon). What this means, is that
if you have two datetimes, one with an hour at "10:00" and another one
at "13:00", by default, the algorithm used in web browser, will return
"a" (component for AM/PM) highlighting the difference between morning
and afternoon. However, if you pass the option "day_period_first", then,
this method will prioritise the day periods difference and return "B"
(component for day periods).
This is important, because of the way almost all, but 4 locales ("bg",
"id", "uz" and "zu"), have sliced up their day periods.
For the locale "en", for example, the day periods are:
* "midnight"
00:00 00:00
* "morning1"
06:00 12:00
* "noon"
12:00 12:00
* "afternoon1"
12:00 18:00
* "evening1"
18:00 21:00
* "night1"
21:00 06:00
As you can see, there are no occurrence of a day period that spans both
morning and afternoon, and thus, because of those data, this method
would always return, by default, "a" instead of "B"
For the table of the "CLDR" components, see "Format Patterns" in
Locale::Unicode::Data
If an error occurred, an exception object is set and "undef" is returned
in scalar context, and an empty list in list context.
is_dst
my $locale = DateTime::Locale::FromCLDR->new( 'en' );
my $dt = DateTime->new( year => 2024, month => 7, day => 1, time_zone => 'Asia/Tokyo' );
my $bool = $locale->is_dst( $dt );
metazone_generic_short
my $locale = DateTime::Locale::FromCLDR->new( 'en' );
my $str = $locale->metazone_generic_short( metazone => 'Atlantic' );
# AT
my $locale = DateTime::Locale::FromCLDR->new( 'fr' );
my $str = $locale->metazone_generic_short( metazone => 'Atlantic' );
# HA
This returns the localised metazone name for the "generic" time and
"short" format for the given "metazone" ID.
If nothing can be found, an empty string is returned.
If an error occurred, an exception object is set, and "undef" is
returned in scalar context, or an empty list in list context.
metazone_standard_long
my $locale = DateTime::Locale::FromCLDR->new( 'en' );
my $str = $locale->metazone_standard_long( metazone => 'Atlantic' );
# Atlantic Standard Time
my $locale = DateTime::Locale::FromCLDR->new( 'fr' );
my $str = $locale->metazone_standard_long( metazone => 'Atlantic' );
# heure normale de l’Atlantique
This returns the localised metazone name for the "standard" time and
"long" format for the given "metazone" ID.
If nothing can be found, an empty string is returned.
If an error occurred, an exception object is set, and "undef" is
returned in scalar context, or an empty list in list context.
metazone_standard_short
my $locale = DateTime::Locale::FromCLDR->new( 'en' );
my $str = $locale->metazone_standard_short( metazone => 'Atlantic' );
# AST
my $locale = DateTime::Locale::FromCLDR->new( 'fr' );
my $str = $locale->metazone_standard_short( metazone => 'Atlantic' );
# HNA
This returns the localised metazone name for the "standard" time and
"short" format for the given "metazone" ID.
If nothing can be found, an empty string is returned.
If an error occurred, an exception object is set, and "undef" is
returned in scalar context, or an empty list in list context.
month_format_abbreviated
my $locale = DateTime::Locale::FromCLDR->new( 'en' );
my $array = $locale->month_format_abbreviated;
say @$array;
# Jan, Feb, Mar, Apr, May, Jun, Jul, Aug, Sep, Oct, Nov, Dec
Returns an array reference of month names in abbreviated format from
January to December.
See also "calendar_term" in Locale::Unicode::Data
month_format_narrow
Same as month_format_abbreviated, but returns the months in narrow
format.
my $locale = DateTime::Locale::FromCLDR->new( 'en' );
my $array = $locale->month_format_narrow;
say @$array;
# J, F, M, A, M, J, J, A, S, O, N, D
month_format_wide
Same as month_format_abbreviated, but returns the months in wide format.
my $locale = DateTime::Locale::FromCLDR->new( 'en' );
my $array = $locale->month_format_wide;
say @$array;
# January, February, March, April, May, June, July, August, September, October, November, December
month_stand_alone_abbreviated
my $locale = DateTime::Locale::FromCLDR->new( 'en' );
my $array = $locale->month_stand_alone_abbreviated;
say @$array;
# Jan, Feb, Mar, Apr, May, Jun, Jul, Aug, Sep, Oct, Nov, Dec
Returns an array reference of month names in abbreviated stand-alone
format from January to December.
See also "calendar_term" in Locale::Unicode::Data
Note that there is often little difference between the "format" and
"stand-alone" format types.
See the LDML specifications
<https://unicode.org/reports/tr35/tr35-dates.html#months_days_quarters_e
ras> for more information on the difference between the "format" and
"stand-alone" types.
month_stand_alone_narrow
Same as month_stand_alone_abbreviated, but returns the months in narrow
format.
my $locale = DateTime::Locale::FromCLDR->new( 'en' );
my $array = $locale->month_stand_alone_narrow;
say @$array;
# J, F, M, A, M, J, J, A, S, O, N, D
month_stand_alone_wide
Same as month_format_abbreviated, but returns the months in wide format.
my $locale = DateTime::Locale::FromCLDR->new( 'en' );
my $array = $locale->month_stand_alone_wide;
say @$array;
# January, February, March, April, May, June, July, August, September, October, November, December
name
my $locale = DateTime::Locale::FromCLDR->new( 'fr' );
say $locale->name; # French
my $locale = DateTime::Locale::FromCLDR->new( 'fr-CH' );
say $locale->name; # Swiss French
The "locale"'s name in English.
See also native_name
native_language
my $locale = DateTime::Locale::FromCLDR->new( 'fr-CH' );
say $locale->native_language; # français
Returns the "locale"'s "language" name as written in the "locale" own
language.
If nothing can be found, it will return an empty string.
native_name
my $locale = DateTime::Locale::FromCLDR->new( 'fr-CH' );
say $locale->native_name; # français suisse
Returns the "locale"'s name as written in the "locale" own language.
If nothing can be found, it will return an empty string.
native_script
my $locale = DateTime::Locale::FromCLDR->new( 'fr-Latn-CH' );
say $locale->native_script; # latin
my $locale = DateTime::Locale::FromCLDR->new( 'fr' );
say $locale->native_script; # undef
* "superscript"
For example "×", "(^)"
* "time_separator"
This is intended to replace "any use of the "timeSeparator" pattern
character in a date-time format pattern"
For example ":", "Ù«", "."
number_system
my $locale = DateTime::Locale::FromCLDR->new( 'ar-EG' );
say $locale->number_system;
# arab
my $locale = DateTime::Locale::FromCLDR->new( 'ja' );
say $locale->number_system;
# latn
Returns a string representing the number system for the "locale"
number_system_digits
my $locale = DateTime::Locale::FromCLDR->new( 'en' );
my $digits = $locale->number_system_digits( 'latn' );
say $digits; # [0, 1, 2, 3, 4, 5, 6, 7, 8. 9];
# Japanese traditional numbering system
my $digits = $locale->number_system_digits( 'jpan' );
say $digits; # ["〇","一","二","三","å››","五","å…","七","å…«","ä¹"];
Provided with a valid number system ID, and this will return an array
reference of digits for that number system, from 0 to 9.
It sets an exception object upon error, and returns "undef" in scalar
context, or an empty list in list context.
prefers_24_hour_time
This checks whether the "locale" prefers the 24H format or the 12H one
and returns true (1) if it prefers the 24 hours format or false (0)
otherwise.
How it finds out? It pulls the preferred time format from the CLDR data
by calling time_format_preferred, and from there returns true (1) if the
value is either "H" or "k", or else false (0).
This is as specified by the Unicode LDML
<https://www.unicode.org/reports/tr35/tr35-dates.html#availableFormats_a
ppendItems>, which states: "the locale's actual preference for 12-hour
or 24-hour time cycle is determined from the Time Data as described
above in timeFormats."
quarter_format_abbreviated
my $locale = DateTime::Locale::FromCLDR->new( 'en' );
my $array = $locale->quarter_format_abbreviated;
say @$array;
# Q1, Q2, Q3, Q4
Returns an array reference of quarter names in abbreviated format.
See also "calendar_term" in Locale::Unicode::Data
quarter_format_narrow
Same as quarter_format_abbreviated, but returns the quarters in narrow
format.
my $locale = DateTime::Locale::FromCLDR->new( 'en' );
my $array = $locale->quarter_format_narrow;
say @$array;
# 1, 2, 3, 4
quarter_format_wide
Same as quarter_format_abbreviated, but returns the quarters in wide
format.
my $locale = DateTime::Locale::FromCLDR->new( 'en' );
my $array = $locale->quarter_format_wide;
say @$array;
# 1st quarter, 2nd quarter, 3rd quarter, 4th quarter
quarter_stand_alone_abbreviated
my $locale = DateTime::Locale::FromCLDR->new( 'en' );
my $array = $locale->quarter_stand_alone_abbreviated;
say @$array;
# Q1, Q2, Q3, Q4
Returns an array reference of quarter names in abbreviated format.
See also "calendar_term" in Locale::Unicode::Data
Note that there is often little difference between the "format" and
"stand-alone" format types.
See the LDML specifications
<https://unicode.org/reports/tr35/tr35-dates.html#months_days_quarters_e
ras> for more information on the difference between the "format" and
"stand-alone" types.
quarter_stand_alone_narrow
Same as quarter_stand_alone_abbreviated, but returns the quarters in
narrow format.
my $locale = DateTime::Locale::FromCLDR->new( 'en' );
my $array = $locale->quarter_stand_alone_narrow;
say @$array;
# 1, 2, 3, 4
quarter_stand_alone_wide
Same as quarter_stand_alone_abbreviated, but returns the quarters in
wide format.
my $locale = DateTime::Locale::FromCLDR->new( 'en' );
my $array = $locale->quarter_stand_alone_wide;
say @$array;
# 1st quarter, 2nd quarter, 3rd quarter, 4th quarter
script
my $locale = DateTime::Locale::FromCLDR->new( 'ja-Kana-JP' );
my $str = $locale->script;
# Katakana
Returns the name of the "locale"'s "script" in English.
If there is no "script" specified in the "locale", it will return
"undef"
If there is a "script" in the "locale", but, somehow, it cannot be found
in the "en" "locale"'s language tree, it will return an empty string.
script_code
my $locale = DateTime::Locale::FromCLDR->new( 'ja-Kana-JP' );
my $script = $locale->script_code;
# Kana
my $locale = DateTime::Locale::FromCLDR->new( 'ja-JP' );
my $script = $locale->script_code;
# undef
Returns the "locale"'s "script" ID, or "undef" if there is none.
script_id
This is an alias for script_code
split_interval
my $locale = DateTime::Locale::FromCLDR->new( 'en' );
my $ref = $locale->split_interval(
pattern => $string,
greatest_diff => 'd',
) || die( $locale->error );
This method actually calls "split_interval" in Locale::Unicode::Data and
passes it all the arguments it received, so please check its
documentation.
It returns the array reference it received from "split_interval" in
Locale::Unicode::Data, or upon error, its sets an exception object, and
returns "undef" in scalar context or an empty list in list context.
territory
my $locale = DateTime::Locale::FromCLDR->new( 'ja-JP' );
my $script = $locale->territory;
# Japan
my $locale = DateTime::Locale::FromCLDR->new( 'zh-034' );
my $script = $locale->territory;
# Southern Asia
my $locale = DateTime::Locale::FromCLDR->new( 'en' );
my $script = $locale->territory;
# undef
my $locale = DateTime::Locale::FromCLDR->new( 'en-XX' );
my $script = $locale->territory;
# ''
Returns the name of the "locale"'s "territory" in English.
If there is no "territory" specified in the "locale", it will return
"undef"
If there is a "territory" in the "locale", but, somehow, it cannot be
found in the "en" "locale"'s language tree, it will return an empty
string.
territory_code
my $locale = DateTime::Locale::FromCLDR->new( 'ja-JP' );
my $script = $locale->territory_code;
# JP
my $locale = DateTime::Locale::FromCLDR->new( 'ja-Kana' );
my $script = $locale->territory_code;
# undef
Returns the "locale"'s "territory" ID, or "undef" if there is none.
territory_id
This is an alias for territory_code
territory_info
my $locale = DateTime::Locale::FromCLDR->new( 'en' );
my $ref = $locale->territory_info;
which would yield:
{
calendars => undef,
contains => undef,
currency => "USD",
first_day => 7,
gdp => 19490000000000,
languages => [qw(
en es zh-Hant fr de fil it vi ko ru nv yi pdc hnj haw
frc chr esu dak cho lkt ik mus io cic cad jbo osa zh
)],
literacy_percent => 99,
min_days => 1,
parent => "021",
population => 332639000,
status => "regular",
territory => "US",
territory_id => 297,
weekend => undef,
}
my $locale = DateTime::Locale::FromCLDR->new( 'en-GB' );
my $ref = $locale->territory_info;
which would yield:
{
calendars => undef,
contains => undef,
currency => "GBP",
first_day => 1,
gdp => 2925000000000,
languages => [qw(
en fr de es pl pa ur ta gu sco cy bn ar zh-Hant it lt pt
so tr ga gd kw en-Shaw
)],
literacy_percent => 99,
min_days => 4,
parent => 154,
population => 65761100,
status => "regular",
territory => "GB",
territory_id => 121,
weekend => undef,
}
Returns an hash reference of information related to the ISO3166 country
code associated with the "locale". If the "locale" has no country code
associated, it will expand it using the Unicode LDML rule with
"likely_subtag" in Locale::Unicode::Data
Keep in mind that the default or fallback data are stored in the special
territory code 001 (World). Thus, for example, if the "calendars" field
is empty, the default value would be in 001, and would be
"["gregorian"]"
time_format_allowed
my $locale = DateTime::Locale::FromCLDR->new( 'en' );
my $array = $locale->time_format_allowed;
Returns an array reference of allowed time patterns
<https://unicode.org/reports/tr35/tr35-dates.html#Time_Data> for the
"locale"'s associated territory. If the locale has no "territory"
associated with, it will check the likely subtag to derive the
"territory" for that "locale"
time_format_default
This is an alias for time_format_medium
time_format_full
my $locale = DateTime::Locale::FromCLDR->new( 'en' );
say $locale->time_format_full;
# h:mm:ss a zzzz
# 10:44:07 PM UTC
Returns the full date pattern
<https://unicode.org/reports/tr35/tr35-dates.html#dateFormats>
See also "calendar_format_l10n" in Locale::Unicode::Data
time_format_long
Same as time_format_full, but returns the long format pattern.
my $locale = DateTime::Locale::FromCLDR->new( 'en' );
say $locale->time_format_long;
# h:mm:ss a z
# 10:44:07 PM UTC
time_format_medium
Same as time_format_full, but returns the medium format pattern.
my $locale = DateTime::Locale::FromCLDR->new( 'en' );
say $locale->time_format_medium;
# h:mm:ss a
# 10:44:07 PM
time_format_preferred
my $locale = DateTime::Locale::FromCLDR->new( 'en' );
my $str = $locale->time_format_preferred;
Returns a string representing the time preferred pattern
<https://unicode.org/reports/tr35/tr35-dates.html#Time_Data> for the
"locale"'s associated territory. If the locale has no "territory"
associated with, it will check the likely subtag to derive the
"territory" for that "locale"
time_format_short
Same as time_format_full, but returns the short format pattern.
my $locale = DateTime::Locale::FromCLDR->new( 'en' );
say $locale->time_format_short;
# h:mm a
# 10:44 PM
time_formats
my $now = DateTime->now( locale => 'en' );
my $ref = $locale->time_formats;
foreach my $type ( sort( keys( %$ref ) ) )
{
say $type, ":";
say $ref->{ $type };
say $now->format_cldr( $ref->{ $type } ), "\n";
}
Would produce:
full:
h:mm:ss a zzzz
10:44:07 PM UTC
long:
h:mm:ss a z
10:44:07 PM UTC
medium:
h:mm:ss a
10:44:07 PM
short:
( run in 0.628 second using v1.01-cache-2.11-cpan-39bf76dae61 )