View Source Cldr.DateTime.Formatter (Cldr Dates & Times v2.20.3)
Functions that implement the formatting for each specific format symbol.
Each format symbol is an ASCII character in the
range a-zA-z
. Although not all characters are used as
format symbols, all characters are reserved for that use
requiring that literals be enclosed in single quote
characters, for example 'a literal'
.
Variations of each format are defined by repeating the
format symbol one or more times. CLDR typically defines
an :abbreviated
, :wide
and :narrow
format that is
reprented by a sequence of 3, 4 or 5 format symbols but
this can vary depending on the format symbol.
The CLDR standard
defines a wide range of format symbols. Most - but not
all - of these symbols are supported in Cldr
. The supported
symbols are described below.
Format Symbol Table
Element | Symbol | Example | Cldr Format |
---|---|---|---|
Era | G, GG, GGG | "AD" | Abbreviated |
GGGG | "Anno Domini" | Wide | |
GGGGG | "A" | Narrow | |
Year | y | 7 | Minimum necessary digits |
yy | "17" | Least significant 2 digits | |
yyy | "017", "2017" | Padded to at least 3 digits | |
yyyy | "2017" | Padded to at least 4 digits | |
yyyyy | "02017" | Padded to at least 5 digits | |
ISOWeek Year | Y | 7 | Minimum necessary digits |
YY | "17" | Least significant 2 digits | |
YYY | "017", "2017" | Padded to at least 3 digits | |
YYYY | "2017" | Padded to at least 4 digits | |
YYYYY | "02017" | Padded to at least 5 digits | |
Related Gregorian Year | r, rr, rr+ | 2017 | Minimum necessary digits |
Cyclic Year | U, UU, UUU | "甲子" | Abbreviated |
UUUU | "甲子" (for now) | Wide | |
UUUUU | "甲子" (for now) | Narrow | |
Extended Year | u+ | 4601 | Minimum necessary digits |
Quarter | Q | 2 | Single digit |
"02" | Two digits | ||
QQQ | "Q2" | Abbreviated | |
QQQQ | "2nd quarter" | Wide | |
QQQQQ | "2" | Narrow | |
Standalone Quarter | q | 2 | Single digit |
"02" | Two digits | ||
qqq | "Q2" | Abbreviated | |
qqqq | "2nd quarter" | Wide | |
qqqqq | "2" | Narrow | |
Month | M | 9 | Single digit |
MM | "09" | Two digits | |
MMM | "Sep" | Abbreviated | |
MMMM | "September" | Wide | |
MMMMM | "S" | Narrow | |
Standalone Month | L | 9 | Single digit |
LL | "09" | Two digits | |
LLL | "Sep" | Abbreviated | |
LLLL | "September" | Wide | |
LLLLL | "S" | Narrow | |
Week of Year | w | 2, 22 | Single digit |
ww | 02, 22 | Two digits, zero padded | |
Week of Month | W | 2 | Single digit |
Day of Year | D | 3, 33, 333 | Minimum necessary digits |
DD | 03, 33, 333 | Minimum of 2 digits, zero padded | |
DDD | 003, 033, 333 | Minimum of 3 digits, zero padded | |
Day of Month | d | 2, 22 | Minimum necessary digits |
dd | 02, 22 | Two digits, zero padded | |
ddd | 2nd, 25th | Ordinal day of month | |
Day of Week | E, EE, EEE | "Tue" | Abbreviated |
EEEE | "Tuesday" | Wide | |
EEEEE | "T" | Narrow | |
EEEEEE | "Tu" | Short | |
e | 2 | Single digit | |
ee | "02" | Two digits | |
eee | "Tue" | Abbreviated | |
eeee | "Tuesday" | Wide | |
eeeee | "T" | Narrow | |
eeeeee | "Tu" | Short | |
Standalone Day of Week | c, cc | 2 | Single digit |
ccc | "Tue" | Abbreviated | |
cccc | "Tuesday" | Wide | |
ccccc | "T" | Narrow | |
cccccc | "Tu" | Short | |
AM or PM | a, aa, aaa | "am." | Abbreviated |
aaaa | "am." | Wide | |
aaaaa | "am" | Narrow | |
Noon, Mid, AM, PM | b, bb, bbb | "mid." | Abbreviated |
bbbb | "midnight" | Wide | |
bbbbb | "md" | Narrow | |
Flexible time period | B, BB, BBB | "at night" | Abbreviated |
BBBB | "at night" | Wide | |
BBBBB | "at night" | Narrow | |
Hour | h, K, H, k | See the table below | |
Minute | m | 3, 10 | Minimum digits of minutes |
mm | "03", "12" | Two digits, zero padded | |
Second | s | 3, 48 | Minimum digits of seconds |
ss | "03", "48" | Two digits, zero padded | |
Fractional Seconds | S | 3, 48 | Minimum digits of fractional seconds |
SS | "03", "48" | Two digits, zero padded | |
Milliseconds | A+ | 4000, 63241 | Minimum digits of milliseconds since midnight |
Generic non-location TZ | v | "Etc/UTC" | :time_zone key, unlocalised |
vvvv | "unk" | Generic timezone name. Currently returns only "unk" | |
Specific non-location TZ | z..zzz | "UTC" | :zone_abbr key, unlocalised |
zzzz | "GMT" | Delegates to zone_gmt/4 | |
Timezone ID | V | "unk" | :zone_abbr key, unlocalised |
VV | "Etc/UTC | Delegates to zone_gmt/4 | |
VVV | "Unknown City" | Exemplar city. Not supported. | |
VVVV | "GMT" | Delegates to `zone_gmt/4 | |
ISO8601 Format | Z..ZZZ | "+0100" | ISO8601 Basic Format with hours and minutes |
ZZZZ | "+01:00" | Delegates to `zone_gmt/4 | |
ZZZZZ | "+01:00:10" | ISO8601 Extended format with optional seconds | |
ISO8601 plus Z | X | "+01" | ISO8601 Basic Format with hours and optional minutes or "Z" |
XX | "+0100" | ISO8601 Basic Format with hours and minutes or "Z" | |
XXX | "+0100" | ISO8601 Basic Format with hours and minutes, optional seconds or "Z" | |
XXXX | "+010059" | ISO8601 Basic Format with hours and minutes, optional seconds or "Z" | |
XXXXX | "+01:00:10" | ISO8601 Extended Format with hours and minutes, optional seconds or "Z" | |
ISO8601 minus Z | x | "+0100" | ISO8601 Basic Format with hours and optional minutes |
xx | "-0800" | ISO8601 Basic Format with hours and minutes | |
xxx | "+01:00" | ISO8601 Extended Format with hours and minutes | |
xxxx | "+010059" | ISO8601 Basic Format with hours and minutes, optional seconds | |
xxxxx | "+01:00:10" | ISO8601 Extended Format with hours and minutes, optional seconds | |
GMT Format | O | "+0100" | Short localised GMT format |
OOOO | "+010059" | Long localised GMT format |
Formatting symbols for hour of day
The hour of day can be formatted differently depending whether a 12- or 24-hour day is being represented and depending on the way in which midnight and noon are represented. The following table illustrates the differences:
Symbol | Midn. | Morning | Noon | Afternoon | Midn. |
---|---|---|---|---|---|
h | 12 | 1...11 | 12 | 1...11 | 12 |
K | 0 | 1...11 | 0 | 1...11 | 0 |
H | 0 | 1...11 | 12 | 13...23 | 0 |
k | 24 | 1...11 | 12 | 13...23 | 24 |
Summary
Functions
Returns the cyclic year (format symbol U
) name for
non-gregorian calendars.
Returns a formatted date.
Returns the weekday name (format symbol E
) as an string.
Returns the day of the month (symbol d
) as an integer.
Returns the local day of week (format symbol e
) as a
number or name.
Returns the day of the year (symbol D
) as an integer in string
format.
Returns the era
(format symbol G
) of a date
for given locale.
Returns the Extended year (format symbol u
).
Returns the :second
of a time
or datetime
(format symbol S
) as float
in string format. The seconds are calculate to include microseconds if they
are available. The number of S
's in the format determines the formatting.
Returns the formatting of the :hour
(format symbol K
) as a number in the
range 0..11 as a string.
Returns the formatting of the :hour
(format symbol h
) as a number in the
range 1..12 as a string.
Returns the formatting of the :hour
(format symbol H
) as a number
in the range 0..23 as a string.
Returns the formatting of the :hour
(format symbol k
) as a number in the
range 1..24 as a string.
Returns the hour formatted in a locale-specific format
Returns a literal.
Returns the time
(format symbol A
) as milliseconds since
midnight.
Returns the :minute
of a time
or datetime
(format symbol m
) as number
in string format. The number of m
's in the format determines the formatting.
Returns the month
(format symbol M
) of a date
for given locale.
Returns a localised version of am
or pm
(format symbol a
).
Returns the formatting of the time period as a string, for
example at night
(format symbol B
).
Returns the formatting of the time period as either
noon
, midnight
or am
/pm
(format symbol 'b').
Returns the quarter
(format symbol Q
) of a date
for given locale.
Returns the related gregorian year (format symbol r
)
of a date for given locale.
Returns the :second
of a time
or datetime
(format symbol s
) as number
in string format. The number of s
's in the format determines the formatting.
Returns the stand-alone local day (format symbol c
)
of week number/name.
Returns the month
(symbol L
) in standalone format which is
intended to formatted without an accompanying day (d
).
Returns the standalone quarter
(format symbol a
) of a date
for given locale.
Returns a formatted time.
Returns the year
(format symbol Y
) in “Week of Year”
based calendars in which the year transition occurs
on a week boundary.
Returns the week of the month (format symbol W
) as an integer.
Returns the week of the year (symbol w
) as an integer.
Returns the year
(format symbol y
) of a date
as an integer. The y
format returns the year
as a simple integer in string format.
Functions
@spec cyclic_year(Cldr.Calendar.any_date_time(), integer(), Keyword.t()) :: String.t() | {:error, String.t()}
Returns the cyclic year (format symbol U
) name for
non-gregorian calendars.
NOTE: In the current implementation, the cyclic year is
delegated to Cldr.DateTime.Formatter.year/3
(format symbol y
) and does not return a localized
cyclic year.
Format Symbol
Symbol | Example | Cldr Format |
---|---|---|
U, UU, UUU | "甲子" | Abbreviated |
UUUU | "甲子" (for now) | Wide |
UUUUU | "甲子" (for now) | Narrow |
Calendars such as the Chinese lunar
calendar (and related calendars) and the Hindu calendars
use 60-year cycles of year names. If the calendar does
not provide cyclic year name data, or if the year value
to be formatted is out of the range of years for which
cyclic name data is provided, then numeric formatting
is used (behaves like format symbol y
).
Currently the CLDR data only provides abbreviated names, which will be used for all requested name widths.
@spec cyclic_year( Cldr.Calendar.any_date_time(), integer(), Cldr.Locale.locale_reference(), Cldr.backend(), map() ) :: String.t() | {:error, String.t()}
@spec date(Calendar.date(), integer(), Keyword.t()) :: String.t() | {:error, String.t()} | {:error, {module(), String.t()}}
Returns a formatted date.
DateTime formats are defined in CLDR using substitution rules whereby the Date and/or Time are substituted into a format string. Therefore this function crafts a date format string which is then inserted into the overall format being requested.
@spec date( Calendar.date(), integer(), Cldr.Locale.locale_reference(), Cldr.backend(), Keyword.t() | map() ) :: String.t() | {:error, {module(), String.t()}}
@spec day_name(Cldr.Calendar.any_date_time(), integer(), Keyword.t()) :: String.t() | {:error, String.t()}
Returns the weekday name (format symbol E
) as an string.
Arguments
date
is aDate
struct or any map that contains at least the keys:year
,:month
,:day
and:calendar
n
in an integer between 1 and 6 that determines the format of the day of weeklocale
is any valid locale name returned byCldr.known_locale_names/0
or aCldr.LanguageTag.t/0
struct. The default isCldr.get_locale/0
options
is aKeyword
list of options. There are no options used inday_name/4
Format Symbol
The representation of the day name is made in accordance with the following table:
Symbol | Example | Cldr Format |
---|---|---|
E, EE, EEE | "Tue" | Abbreviated |
EEEE | "Tuesday" | Wide |
EEEEE | "T" | Narrow |
EEEEEE | "Tu" | Short |
Examples
iex> Cldr.DateTime.Formatter.day_name ~D[2017-08-15], 6
"Tu"
iex> Cldr.DateTime.Formatter.day_name ~D[2017-08-15], 5
"T"
iex> Cldr.DateTime.Formatter.day_name ~D[2017-08-15], 4
"Tuesday"
iex> Cldr.DateTime.Formatter.day_name ~D[2017-08-15], 3
"Tue"
iex> Cldr.DateTime.Formatter.day_name ~D[2017-08-15], 2
"Tue"
iex> Cldr.DateTime.Formatter.day_name ~D[2017-08-15], 1
"Tue"
@spec day_name( Cldr.Calendar.any_date_time(), integer(), Cldr.Locale.locale_reference(), Cldr.backend(), map() ) :: String.t() | {:error, String.t()}
@spec day_of_month(Cldr.Calendar.any_date_time(), integer(), Keyword.t()) :: String.t() | {:error, String.t()}
Returns the day of the month (symbol d
) as an integer.
Arguments
date
is aDate
struct or any map that contains at least the keys:year
,:month
,:day
and:calendar
n
in an integer between 1 and 2 that determines the format of the day of monthlocale
is any valid locale name returned byCldr.known_locale_names/0
or aCldr.LanguageTag.t/0
struct. The default isCldr.get_locale/0
options
is aKeyword
list of options. There are no options used inday_of_month/4
Format Symbol
The representation of the day of the month is made in accordance
with the following table. Note that ddd
is not part of the CLDR
standard.
Symbol | Example | Cldr Format |
---|---|---|
d | 2, 22 | |
dd | 02, 22 | |
ddd | 2nd, 22nd |
Examples
iex> Cldr.DateTime.Formatter.day_of_month ~D[2017-01-04], 1
4
iex> Cldr.DateTime.Formatter.day_of_month ~D[2017-01-04], 2
"04"
iex> Cldr.DateTime.Formatter.day_of_month ~D[2017-01-04], 3
"4th"
@spec day_of_month( Cldr.Calendar.date(), integer(), Cldr.Locale.locale_reference(), Cldr.backend(), map() ) :: String.t() | {:error, String.t()}
@spec day_of_week(Cldr.Calendar.any_date_time(), integer(), Keyword.t()) :: String.t() | {:error, String.t()}
Returns the local day of week (format symbol e
) as a
number or name.
Arguments
date
is aDate
struct or any map that contains at least the keys:year
,:month
,:day
and:calendar
n
in an integer between 1 and 6 that determines the format of the day of weeklocale
is any valid locale name returned byCldr.known_locale_names/0
or aCldr.LanguageTag.t/0
struct. The default isCldr.get_locale/0
options
is aKeyword
list of options. There are no options used inday_of_week/4
Notes
Returns the same as format symbol E
except that it adds a
numeric value that will depend on the local starting day
of the week.
Format Symbol
The representation of the time period is made in accordance with the following table:
Symbol | Example | Cldr Format |
---|---|---|
e | 2 | Single digit |
ee | "02" | Two digits |
eee | "Tue" | Abbreviated |
eeee | "Tuesday" | Wide |
eeeee | "T" | Narrow |
eeeeee | "Tu" | Short |
Examples
iex> Cldr.DateTime.Formatter.day_of_week ~D[2017-08-15], 3
"Tue"
iex> Cldr.DateTime.Formatter.day_of_week ~D[2017-08-15], 4
"Tuesday"
iex> Cldr.DateTime.Formatter.day_of_week ~D[2017-08-15], 5
"T"
iex> Cldr.DateTime.Formatter.day_of_week ~D[2017-08-15], 6
"Tu"
iex> Cldr.DateTime.Formatter.day_of_week ~D[2017-08-15], 1
"2"
iex> Cldr.DateTime.Formatter.day_of_week ~D[2017-08-15], 2
"02"
@spec day_of_week( Cldr.Calendar.any_date_time(), integer(), Cldr.Locale.locale_reference(), Cldr.backend(), map() ) :: String.t() | {:error, String.t()}
@spec day_of_year(Cldr.Calendar.any_date_time(), integer(), Keyword.t()) :: String.t() | {:error, String.t()}
Returns the day of the year (symbol D
) as an integer in string
format.
Arguments
date
is aDate
struct or any map that contains at least the keys:year
,:month
,:day
and:calendar
n
in an integer between 1 and 3 that determines the format of the day of yearlocale
is any valid locale name returned byCldr.known_locale_names/0
or aCldr.LanguageTag.t/0
struct. The default isCldr.get_locale/0
options
is aKeyword
list of options. There are no options used inday_of_year/4
Format Symbol
The representation of the day of the year is made in accordance with the following table:
Symbol | Example | Cldr Format |
---|---|---|
D | 3, 33, 333 | |
DD | 03, 33, 333 | |
DDD | 003, 033, 333 |
Examples
iex> Cldr.DateTime.Formatter.day_of_year ~D[2017-01-15], 1
"15"
iex> Cldr.DateTime.Formatter.day_of_year ~D[2017-01-15], 2
"15"
iex> Cldr.DateTime.Formatter.day_of_year ~D[2017-01-15], 3
"015"
@spec day_of_year( Cldr.Calendar.any_date_time(), integer(), Cldr.Locale.locale_reference(), Cldr.backend(), map() ) :: String.t() | {:error, String.t()}
@spec era(Cldr.Calendar.any_date_time(), pos_integer(), Keyword.t()) :: String.t() | {:error, String.t()}
Returns the era
(format symbol G
) of a date
for given locale.
Arguments
date
is aDate
struct or any map that contains at least the keys:month
and:calendar
n
in an integer between 1 and 5 that determines the format of the yearlocale
is any valid locale name returned byCldr.known_locale_names/0
or aCldr.LanguageTag.t/0
struct. The default isCldr.get_locale/0
options
is aKeyword
list of options. The only applicable option is:era
with a value of eithernil
(the default) or:variant
which will return the variant form of an era if one is available.
Format Symbol
The representation of the era is made in accordance with the following table:
Symbol | Example | Cldr Format |
---|---|---|
G, GG, GGG | "AD" | Abbreviated |
GGGG | "Anno Domini | Wide |
GGGGG | "A" | Narrow |
Examples
iex> Cldr.DateTime.Formatter.era(~D[2017-12-01], 1)
"AD"
iex> Cldr.DateTime.Formatter.era(~D[2017-12-01], 4, "fr", MyApp.Cldr)
"après Jésus-Christ"
iex> Cldr.DateTime.Formatter.era(~D[2017-12-01], 4, "fr", MyApp.Cldr, era: :variant)
"de l’ère commune"
@spec era( Cldr.Calendar.any_date_time(), pos_integer(), Cldr.Locale.locale_reference(), Cldr.backend(), map() ) :: String.t() | {:error, String.t()}
@spec extended_year(Cldr.Calendar.any_date_time(), integer(), Keyword.t()) :: String.t() | {:error, String.t()}
Returns the Extended year (format symbol u
).
Arguments
date
is aDate
struct or any map that contains at least the keys:month
and:calendar
n
in an integer between 1 and 5 that determines the format of the yearlocale
is any valid locale name returned byCldr.known_locale_names/0
or aCldr.LanguageTag.t/0
struct. The default isCldr.get_locale/0
options
is aKeyword
list of options. There are no options used inweeK_aligned_year/4
NOTE: This current implementation always returns
the year provided in the supplied date. This means
u
returns the same result as the format y
.
Format Symbol
Symbol | Example | Cldr Format |
---|---|---|
u+ | 4601 | Minimum necessary digits |
This is a single number designating the year of this calendar system, encompassing all supra-year fields.
For example, for the Julian calendar system, year numbers are positive, with an era of BCE or CE. An extended year value for the Julian calendar system assigns positive values to CE years and negative values to BCE years, with 1 BCE being year 0.
For u
, all field lengths specify a minimum number of
digits; there is no special interpretation for uu
.
@spec extended_year( Calendar.date(), integer(), Cldr.Locale.locale_reference(), Cldr.backend(), map() ) :: String.t() | {:error, String.t()}
@spec fractional_second(Cldr.Calendar.time(), integer(), Keyword.t()) :: String.t() | {:error, String.t()}
Returns the :second
of a time
or datetime
(format symbol S
) as float
in string format. The seconds are calculate to include microseconds if they
are available. The number of S
's in the format determines the formatting.
Arguments
time
is aTime
struct or any map that contains at least the key:second
with and optional:microsecond
key of the format used byTime
n
is the number of fractional digits to which the float number of seconds is roundedlocale
is any valid locale name returned byCldr.known_locale_names/0
or aCldr.LanguageTag.t/0
struct. The default isCldr.get_locale/0
options
is aKeyword
list of options. There are no options used infractional_second/4
Format Symbol
The representation of the second
is made in accordance with the following
table:
Symbol | Results | Description |
---|---|---|
S | "4.0" | Minimum digits of fractional seconds |
SS | "4.00" | Number of seconds zero-padded to 2 fractional digits |
SSS | "4.002" | Number of seconds zero-padded to 3 fractional digits |
Examples
iex> Cldr.DateTime.Formatter.fractional_second %{second: 4, microsecond: {2000, 3}}, 1
"4.0"
iex> Cldr.DateTime.Formatter.fractional_second %{second: 4, microsecond: {2000, 3}}, 3
"4.002"
iex> Cldr.DateTime.Formatter.fractional_second %{second: 4}, 1
"4"
@spec fractional_second( Cldr.Calendar.time(), integer(), Cldr.Locale.locale_reference(), Cldr.backend(), map() ) :: String.t() | {:error, String.t()}
@spec h11(Cldr.Calendar.time(), integer(), Keyword.t()) :: String.t() | {:error, String.t()}
Returns the formatting of the :hour
(format symbol K
) as a number in the
range 0..11 as a string.
Arguments
time
is aTime
struct or any map that contains at least the key:hour
n
is the number of digits to which:hour
is paddedlocale
is any valid locale name returned byCldr.known_locale_names/0
or aCldr.LanguageTag.t/0
struct. The default isCldr.get_locale/0
options
is aKeyword
list of options. There are no options used inh11/4
Format Symbol
The representation of the hour
is made in accordance with the following
table:
Symbol | Midn. | Morning | Noon | Afternoon | Midn. |
---|---|---|---|---|---|
K | 0 | 1...11 | 0 | 1...11 | 0 |
Examples
iex> Cldr.DateTime.Formatter.h11 %{hour: 0}
"0"
iex> Cldr.DateTime.Formatter.h11 %{hour: 12}
"0"
iex> Cldr.DateTime.Formatter.h11 %{hour: 24}
"0"
iex> Cldr.DateTime.Formatter.h11 %{hour: 23}
"11"
iex> Cldr.DateTime.Formatter.h11 %{hour: 11}
"11"
iex> Cldr.DateTime.Formatter.h11 %{hour: 9}
"9"
@spec h11( Cldr.Calendar.time(), integer(), Cldr.Locale.locale_reference(), Cldr.backend(), map() ) :: String.t() | {:error, String.t()}
@spec h12(Cldr.Calendar.time(), integer(), Keyword.t()) :: String.t() | {:error, String.t()}
Returns the formatting of the :hour
(format symbol h
) as a number in the
range 1..12 as a string.
Arguments
time
is aTime
struct or any map that contains at least the key:hour
n
is the number of digits to which:hour
is paddedlocale
is any valid locale name returned byCldr.known_locale_names/0
or aCldr.LanguageTag.t/0
struct. The default isCldr.get_locale/0
options
is aKeyword
list of options. There are no options used inh12/4
Format Symbol
The representation of the hour
is made in accordance with the following
table:
Symbol | Midn. | Morning | Noon | Afternoon | Midn. |
---|---|---|---|---|---|
h | 12 | 1...11 | 12 | 1...11 | 12 |
Examples
iex> Cldr.DateTime.Formatter.h12 %{hour: 0}
"12"
iex> Cldr.DateTime.Formatter.h12 %{hour: 12}
"12"
iex> Cldr.DateTime.Formatter.h12 %{hour: 24}
"12"
iex> Cldr.DateTime.Formatter.h12 %{hour: 11}
"11"
iex> Cldr.DateTime.Formatter.h12 %{hour: 23}
"11"
@spec h12( Cldr.Calendar.time(), integer(), Cldr.Locale.locale_reference(), Cldr.backend(), map() ) :: String.t() | {:error, String.t()}
@spec h23(Cldr.Calendar.time(), integer(), Keyword.t()) :: String.t() | {:error, String.t()}
Returns the formatting of the :hour
(format symbol H
) as a number
in the range 0..23 as a string.
Arguments
time
is aTime
struct or any map that contains at least the key:hour
n
is the number of digits to which:hour
is paddedlocale
is any valid locale name returned byCldr.known_locale_names/0
or aCldr.LanguageTag.t/0
struct. The default isCldr.get_locale/0
options
is aKeyword
list of options. There are no options used inh23/4
Format Symbol
The representation of the hour
is made in accordance with the following
table:
Symbol | Midn. | Morning | Noon | Afternoon | Midn. |
---|---|---|---|---|---|
H | 0 | 1...11 | 12 | 13...23 | 0 |
Examples:
iex> Cldr.DateTime.Formatter.h23 %{hour: 10}
"10"
iex> Cldr.DateTime.Formatter.h23 %{hour: 13}
"13"
iex> Cldr.DateTime.Formatter.h23 %{hour: 21}
"21"
iex> Cldr.DateTime.Formatter.h23 %{hour: 24}
"0"
iex> Cldr.DateTime.Formatter.h23 %{hour: 0}
"0"
@spec h23( Cldr.Calendar.time(), integer(), Cldr.Locale.locale_reference(), Cldr.backend(), map() ) :: String.t() | {:error, String.t()}
@spec h24(Cldr.Calendar.time(), integer(), Keyword.t()) :: String.t() | {:error, String.t()}
Returns the formatting of the :hour
(format symbol k
) as a number in the
range 1..24 as a string.
Arguments
time
is aTime
struct or any map that contains at least the key:hour
n
is the number of digits to which:hour
is paddedlocale
is any valid locale name returned byCldr.known_locale_names/0
or aCldr.LanguageTag.t/0
struct. The default isCldr.get_locale/0
options
is aKeyword
list of options. There are no options used inh24/4
Format Symbol
The representation of the hour
is made in accordance with the following
table:
Symbol | Midn. | Morning | Noon | Afternoon | Midn. |
---|---|---|---|---|---|
k | 24 | 1...11 | 12 | 13...23 | 24 |
Examples
iex(4)> Cldr.DateTime.Formatter.h24 %{hour: 0}
"24"
iex(5)> Cldr.DateTime.Formatter.h24 %{hour: 12}
"12"
iex(6)> Cldr.DateTime.Formatter.h24 %{hour: 13}
"13"
iex(7)> Cldr.DateTime.Formatter.h24 %{hour: 9}
"9"
iex(8)> Cldr.DateTime.Formatter.h24 %{hour: 24}
"24"
@spec h24( Cldr.Calendar.time(), integer(), Cldr.Locale.locale_reference(), Cldr.backend(), map() ) :: String.t() | {:error, String.t()}
@spec hour(Cldr.Calendar.time(), integer(), Keyword.t()) :: String.t() | {:error, String.t()}
Returns the hour formatted in a locale-specific format
Arguments
time
is aTime
struct or any map that contains at least the key:hour
n
is the number of digits to which:hour
is paddedlocale
is any valid locale name returned byCldr.known_locale_names/0
or aCldr.LanguageTag.t/0
struct. The default isCldr.get_locale/0
options
is aKeyword
list of options. There are no options used inhour/4
Examples
iex> Cldr.DateTime.Formatter.hour ~N[2020-04-25 15:00:00.0]
"3"
iex> Cldr.DateTime.Formatter.hour ~N[2020-04-25 15:00:00.0], locale: "fr"
"15"
iex> Cldr.DateTime.Formatter.hour ~N[2020-04-25 15:00:00.0], locale: "en-AU"
"3"
iex> Cldr.DateTime.Formatter.hour ~N[2020-04-25 15:00:00.0], locale: "en-AU-u-hc-h23"
"15"
@spec hour( Cldr.Calendar.time(), integer(), Cldr.Locale.locale_reference(), Cldr.backend(), map() ) :: String.t() | {:error, String.t()}
Returns a literal.
Example
iex> Cldr.DateTime.Formatter.literal %{time_zone:
...> "Etc/UTC", utc_offset: 0, std_offset: 0}, "A literal"
"A literal"
@spec literal( any(), String.t(), Cldr.Locale.locale_reference(), Cldr.backend(), map() ) :: String.t()
@spec millisecond(Cldr.Calendar.time(), integer(), Keyword.t()) :: String.t() | {:error, String.t()}
Returns the time
(format symbol A
) as milliseconds since
midnight.
Arguments
time
is aTime
struct or any map that contains at least the key:second
with and optional:microsecond
key of the format used byTime
n
is the number of fractional digits to which the float number of seconds is roundedlocale
is any valid locale name returned byCldr.known_locale_names/0
or aCldr.LanguageTag.t/0
struct. The default isCldr.get_locale/0
options
is aKeyword
list of options. There are no options used inmillisecond/4
Format Symbol
The representation of the milliseconds
is made in accordance with the following
table:
Symbol | Results | Description |
---|---|---|
A+ | "4000" | Minimum necessary digits of milliseconds since midnight |
Examples
iex> Cldr.DateTime.Formatter.millisecond %{hour: 0, minute: 0,
...> second: 4, microsecond: {2000, 3}}, 1
"4002"
iex> Cldr.DateTime.Formatter.millisecond %{hour: 0, minute: 0, second: 4}, 1
"4000"
iex> Cldr.DateTime.Formatter.millisecond %{hour: 10, minute: 10, second: 4}, 1
"36604000"
iex> Cldr.DateTime.Formatter.millisecond ~T[07:35:13.215217]
"27313215"
@spec millisecond( Cldr.Calendar.time(), integer(), Cldr.Locale.locale_reference(), Cldr.backend(), map() ) :: String.t() | {:error, String.t()}
@spec minute(Cldr.Calendar.time(), integer(), Keyword.t()) :: String.t() | {:error, String.t()}
Returns the :minute
of a time
or datetime
(format symbol m
) as number
in string format. The number of m
's in the format determines the formatting.
Arguments
time
is aTime
struct or any map that contains at least the key:minute
n
is the number of digits to which:minute
is paddedlocale
is any valid locale name returned byCldr.known_locale_names/0
or aCldr.LanguageTag.t/0
struct. The default isCldr.get_locale/0
options
is aKeyword
list of options. There are no options used inminute/4
Format Symbol
The representation of the minute
is made in accordance with the following
table:
Symbol | Results | Description |
---|---|---|
m | 3, 10 | Minimum digits of minutes |
mm | "03", "12" | Number of minutes zero-padded to 2 digits |
Examples
iex> Cldr.DateTime.Formatter.minute %{minute: 3}, 1
3
iex> Cldr.DateTime.Formatter.minute %{minute: 3}, 2
"03"
@spec minute( Cldr.Calendar.time(), integer(), Cldr.Locale.locale_reference(), Cldr.backend(), map() ) :: String.t() | {:error, String.t()}
@spec month(Cldr.Calendar.any_date_time(), integer(), Keyword.t()) :: String.t() | {:error, String.t()}
Returns the month
(format symbol M
) of a date
for given locale.
Arguments
date
is aDate
struct or any map that contains at least the keys:month
and:calendar
n
in an integer between 1 and 5 that determines the format of the monthlocale
is any valid locale name returned byCldr.known_locale_names/0
or aCldr.LanguageTag.t/0
struct. The default isCldr.get_locale/0
options
is aKeyword
list of options. There are no options used inmonth/4
Format Symbol
The representation of the month is made in accordance with the following table:
Symbol | Example | Cldr Format |
---|---|---|
M | 9 | Single digit |
MM | "09" | Two digits |
MMM | "Sep" | Abbreviated |
MMMM | "September" | Wide |
MMMMM | "S" | Narrow |
Examples
iex> Cldr.DateTime.Formatter.month ~D[2019-09-08]
"9"
iex> Cldr.DateTime.Formatter.month ~D[2019-09-08], 2
"09"
iex> Cldr.DateTime.Formatter.month ~D[2019-09-08], 3
"Sep"
iex> Cldr.DateTime.Formatter.month ~D[2019-09-08], 4
"September"
iex> Cldr.DateTime.Formatter.month ~D[2019-09-08], 5
"S"
@spec month( Cldr.Calendar.any_date_time(), integer(), Cldr.Locale.locale_reference(), Cldr.backend(), map() ) :: String.t() | {:error, String.t()}
@spec period_am_pm(Cldr.Calendar.time(), integer(), Keyword.t()) :: String.t() | {:error, String.t()}
Returns a localised version of am
or pm
(format symbol a
).
Arguments
time
is aTime
struct or any map that contains at least the key:second
n
in an integer between 1 and 5 that determines the format of the time periodlocale
is any valid locale name returned byCldr.known_locale_names/0
or aCldr.LanguageTag.t/0
struct. The default isCldr.get_locale/0
options
is aKeyword
list of options. The available option isperiod: :variant
which will use a veriant of localised "am" or "pm" if one is available
Notes
May be upper or lowercase depending on the locale and other options. The wide form may be the same as the short form if the “real” long form (eg ante meridiem) is not customarily used.
Format Symbol
The representation of the time period is made in accordance with the following table:
Symbol | Example | Cldr Format |
---|---|---|
a, aa, aaa | "am." | Abbreviated |
aaaa | "am." | Wide |
aaaaa | "am" | Narrow |
Examples
iex> Cldr.DateTime.Formatter.period_am_pm %{hour: 0, minute: 0}
"AM"
iex> Cldr.DateTime.Formatter.period_am_pm %{hour: 3, minute: 0}
"AM"
iex> Cldr.DateTime.Formatter.period_am_pm %{hour: 13, minute: 0}
"PM"
iex> Cldr.DateTime.Formatter.period_am_pm %{hour: 21, minute: 0}, 5
"p"
iex> Cldr.DateTime.Formatter.period_am_pm %{hour: 21, minute: 0}, 5
"p"
@spec period_am_pm( Cldr.Calendar.time(), integer(), Cldr.Locale.locale_reference(), Cldr.backend(), map() ) :: String.t() | {:error, String.t()}
@spec period_flex(Cldr.Calendar.time(), integer(), Keyword.t()) :: String.t() | {:error, String.t()}
Returns the formatting of the time period as a string, for
example at night
(format symbol B
).
Arguments
time
is aTime
struct or any map that contains at least the key:second
n
in an integer between 1 and 5 that determines the format of the time periodlocale
is any valid locale name returned byCldr.known_locale_names/0
or aCldr.LanguageTag.t/0
struct. The default isCldr.get_locale/0
options
is aKeyword
list of options. The available option isperiod: :variant
which will use a veriant of localised flexible time period names if one is available
Notes
The time period may be upper or lowercase depending on the locale and other options. Often there is only one width that is customarily used.
Format Symbol
The representation of the time period is made in accordance with the following table:
Symbol | Example | Cldr Format |
---|---|---|
B, BB, BBB | "at night" | Abbreviated |
BBBB | "at night" | Wide |
BBBBB | "at night" | Narrow |
Examples
iex> Cldr.DateTime.Formatter.period_flex %{hour: 11, minute: 5, second: 23}
"in the morning"
iex> Cldr.DateTime.Formatter.period_flex %{hour: 16, minute: 5, second: 23}
"in the afternoon"
iex> Cldr.DateTime.Formatter.period_flex %{hour: 23, minute: 5, second: 23}
"at night"
@spec period_flex( Cldr.Calendar.time(), integer(), Cldr.Locale.locale_reference(), Cldr.backend(), map() ) :: String.t() | {:error, String.t()}
@spec period_noon_midnight(Cldr.Calendar.time(), integer(), Keyword.t()) :: String.t() | {:error, String.t()}
Returns the formatting of the time period as either
noon
, midnight
or am
/pm
(format symbol 'b').
Arguments
time
is aTime
struct or any map that contains at least the key:second
n
in an integer between 1 and 5 that determines the format of the time periodlocale
is any valid locale name returned byCldr.known_locale_names/0
or aCldr.LanguageTag.t/0
struct. The default isCldr.get_locale/0
options
is aKeyword
list of options. The available option isperiod: :variant
which will use a variant of localised "noon" and "midnight" if one is available
Notes
If the language doesn't support "noon" or "midnight" then
am
/pm
is used for all time periods.
May be upper or lowercase depending on the locale and other options.
If the locale doesn't have the notion of a unique noon == 12:00
,
then the PM form may be substituted. Similarly for midnight == 00:00
and the AM form.
Format Symbol
The representation of the time period is made in accordance with the following table:
Symbol | Example | Cldr Format |
---|---|---|
b, bb, bbb | "mid." | Abbreviated |
bbbb | "midnight" | Wide |
bbbbb | "md" | Narrow |
Examples
iex> Cldr.DateTime.Formatter.period_noon_midnight %{hour: 12, minute: 0}
"noon"
iex> Cldr.DateTime.Formatter.period_noon_midnight %{hour: 0, minute: 0}
"midnight"
iex> Cldr.DateTime.Formatter.period_noon_midnight %{hour: 11, minute: 0}
"in the morning"
iex> Cldr.DateTime.Formatter.period_noon_midnight %{hour: 16, minute: 0}
"PM"
@spec period_noon_midnight( Cldr.Calendar.time(), integer(), Cldr.Locale.locale_reference(), Cldr.backend(), map() ) :: String.t() | {:error, String.t()}
@spec quarter(Cldr.Calendar.any_date_time(), integer(), Keyword.t()) :: String.t() | {:error, String.t()}
Returns the quarter
(format symbol Q
) of a date
for given locale.
Arguments
date
is aDate
struct or any map that contains at least the keys:month
and:calendar
n
in an integer between 1 and 5 that determines the format of the quarterlocale
is any valid locale name returned byCldr.known_locale_names/0
or aCldr.LanguageTag.t/0
struct. The default isCldr.get_locale/0
options
is aKeyword
list of options. There are no options used inquarter/5
Format Symbol
The representation of the quarter is made in accordance with the following table:
Symbol | Example | Cldr Format |
---|---|---|
Q | 2 | Single digit |
"02" | Two digits | |
QQQ | "Q2" | Abbreviated |
QQQQ | "2nd quarter" | Wide |
QQQQQ | "2" | Narrow |
Examples
iex> Cldr.DateTime.Formatter.quarter ~D[2017-04-01], 1
2
iex> Cldr.DateTime.Formatter.quarter ~D[2017-04-01], 2
"02"
iex> Cldr.DateTime.Formatter.quarter ~D[2017-04-01], 3
"Q2"
iex> Cldr.DateTime.Formatter.quarter ~D[2017-04-01], 4
"2nd quarter"
iex> Cldr.DateTime.Formatter.quarter ~D[2017-04-01], 5
"2"
@spec quarter( Cldr.Calendar.any_date_time(), integer(), Cldr.Locale.locale_reference(), Cldr.backend(), map() ) :: String.t() | {:error, String.t()}
@spec second(Cldr.Calendar.time(), integer(), Keyword.t()) :: String.t() | {:error, String.t()}
Returns the :second
of a time
or datetime
(format symbol s
) as number
in string format. The number of s
's in the format determines the formatting.
Arguments
time
is aTime
struct or any map that contains at least the key:second
n
is the number of digits to which:hour
is paddedlocale
is any valid locale name returned byCldr.known_locale_names/0
or aCldr.LanguageTag.t/0
struct. The default isCldr.get_locale/0
options
is aKeyword
list of options. There are no options used insecond/4
Format Symbol
The representation of the second
is made in accordance with the following
table:
Symbol | Results | Description |
---|---|---|
s | 3, 48 | Minimum digits of seconds |
ss | "03", "48" | Number of seconds zero-padded to 2 digits |
Examples
iex> Cldr.DateTime.Formatter.second %{second: 23}, 1
"23"
iex> Cldr.DateTime.Formatter.second %{second: 4}, 2
"04"
@spec second( Cldr.Calendar.time(), integer(), Cldr.Locale.locale_reference(), Cldr.backend(), map() ) :: String.t() | {:error, String.t()}
standalone_day_of_week(standalone_day_of_week, n \\ 1, options \\ [])
View Source@spec standalone_day_of_week(Cldr.Calendar.any_date_time(), integer(), Keyword.t()) :: String.t() | {:error, String.t()}
Returns the stand-alone local day (format symbol c
)
of week number/name.
Arguments
date
is aDate
struct or any map that contains at least the keys:year
,:month
,:day
and:calendar
n
in an integer between 1 and 6 that determines the format of the day of weeklocale
is any valid locale name returned byCldr.known_locale_names/0
or aCldr.LanguageTag.t/0
struct. The default isCldr.get_locale/0
options
is aKeyword
list of options. There are no options used instandalone_day_of_week/4
Notes
This is the same as weekday_number/4
except that it is intended
for use without the associated d
format symbol.
Format Symbol
The representation of the time period is made in accordance with the following table:
Symbol | Example | Cldr Format |
---|---|---|
c, cc | 2 | Single digit |
ccc | "Tue" | Abbreviated |
cccc | "Tuesday" | Wide |
ccccc | "T" | Narrow |
cccccc | "Tu" | Short |
Examples
iex> Cldr.DateTime.Formatter.standalone_day_of_week ~D[2017-08-15], 3
"Tue"
iex> Cldr.DateTime.Formatter.standalone_day_of_week ~D[2017-08-15], 4
"Tuesday"
iex> Cldr.DateTime.Formatter.standalone_day_of_week ~D[2017-08-15], 5
"T"
iex> Cldr.DateTime.Formatter.standalone_day_of_week ~D[2017-08-15], 6
"Tu"
@spec standalone_day_of_week( Cldr.Calendar.date(), integer(), Cldr.Locale.locale_reference(), Cldr.backend(), map() ) :: String.t() | {:error, String.t()}
@spec standalone_month(Cldr.Calendar.any_date_time(), integer(), Keyword.t()) :: String.t() | {:error, String.t()}
Returns the month
(symbol L
) in standalone format which is
intended to formatted without an accompanying day (d
).
Arguments
date
is aDate
struct or any map that contains at least the keys:month
and:calendar
n
in an integer between 1 and 5 that determines the format of the monthlocale
is any valid locale name returned byCldr.known_locale_names/0
or aCldr.LanguageTag.t/0
struct. The default isCldr.get_locale/0
options
is aKeyword
list of options. There are no options used instandalone_month/4
Format Symbol
The representation of the standalone month is made in accordance with the following table:
Symbol | Example | Cldr Format |
---|---|---|
L | 9 | Single digit |
LL | "09" | Two digits |
LLL | "Sep" | Abbreviated |
LLLL | "September" | Wide |
LLLLL | "S" | Narrow |
Examples
iex> Cldr.DateTime.Formatter.standalone_month ~D[2019-09-08]
"9"
iex> Cldr.DateTime.Formatter.standalone_month ~D[2019-09-08], 2
"09"
iex> Cldr.DateTime.Formatter.standalone_month ~D[2019-09-08], 3
"Sep"
iex> Cldr.DateTime.Formatter.standalone_month ~D[2019-09-08], 4
"September"
iex> Cldr.DateTime.Formatter.standalone_month ~D[2019-09-08], 5
"S"
@spec standalone_month( Cldr.Calendar.date(), integer(), Cldr.Locale.locale_reference(), Cldr.backend(), map() ) :: String.t() | {:error, String.t()}
@spec standalone_quarter(Cldr.Calendar.any_date_time(), integer(), Keyword.t()) :: String.t() | {:error, String.t()}
Returns the standalone quarter
(format symbol a
) of a date
for given locale.
Arguments
date
is aDate
struct or any map that contains at least the keys:month
and:calendar
n
in an integer between 1 and 5 that determines the format of the quarterlocale
is any valid locale name returned byCldr.known_locale_names/0
or aCldr.LanguageTag.t/0
struct. The default isCldr.get_locale/0
options
is aKeyword
list of options. There are no options used instandalone_quarter/5
Format Symbol
The representation of the quarter is made in accordance with the following table:
Symbol | Example | Cldr Format |
---|---|---|
q | 2 | Single digit |
"02" | Two digits | |
qqq | "Q2" | Abbreviated |
qqqq | "2nd quarter" | Wide |
qqqqq | "2" | Narrow |
Examples
iex> Cldr.DateTime.Formatter.standalone_quarter ~D[2019-06-08], 1
2
iex> Cldr.DateTime.Formatter.standalone_quarter ~D[2019-06-08], 2
"02"
iex> Cldr.DateTime.Formatter.standalone_quarter ~D[2019-06-08], 3
"Q2"
iex> Cldr.DateTime.Formatter.standalone_quarter ~D[2019-06-08], 4
"2nd quarter"
iex> Cldr.DateTime.Formatter.standalone_quarter ~D[2019-06-08], 5
"2"
@spec standalone_quarter( Cldr.Calendar.date(), integer(), Cldr.Locale.locale_reference(), Cldr.backend(), map() ) :: String.t() | {:error, String.t()}
@spec time(Cldr.Calendar.time(), integer(), Keyword.t()) :: String.t() | {:error, {module(), String.t()}}
Returns a formatted time.
DateTime formats are defined in CLDR using substitution rules whereby the Date and/or Time are substituted into a format string. Therefore this function crafts a time format string which is then inserted into the overall format being requested.
@spec time( Cldr.Calendar.time(), integer(), Cldr.Locale.locale_reference(), Cldr.backend(), Keyword.t() | map() ) :: String.t() | {:error, String.t()} | {:error, {module(), String.t()}}
@spec week_aligned_year(Cldr.Calendar.any_date_time(), integer(), Keyword.t()) :: String.t() | {:error, String.t()}
Returns the year
(format symbol Y
) in “Week of Year”
based calendars in which the year transition occurs
on a week boundary.
Arguments
date
is aDate
struct or any map that contains at least the keys:month
and:calendar
n
in an integer between 1 and 5 that determines the format of the yearlocale
is any valid locale name returned byCldr.known_locale_names/0
or aCldr.LanguageTag.t/0
struct. The default isCldr.get_locale/0
options
is aKeyword
list of options. There are no options used inweeK_aligned_year/4
Format Symbol
The representation of the year is made in accordance with the following table:
Symbol | Example | Cldr Format |
---|---|---|
Y | 7 | Minimum necessary digits |
YY | "17" | Least significant 2 digits |
YYY | "017", "2017" | Padded to at least 3 digits |
YYYY | "2017" | Padded to at least 4 digits |
YYYYY | "02017" | Padded to at least 5 digits |
The result may differ from calendar year ‘y’ near a year transition. This numeric year designation is used in conjunction with pattern character ‘w’ in the ISO year-week calendar as defined by ISO 8601, but can be used in non-Gregorian based calendar systems where week date processing is desired.
The field length is interpreted in the same was as for
y
; that is, yy
specifies use of the two low-order
year digits, while any other field length specifies a
minimum number of digits to display.
Examples
iex> Cldr.DateTime.Formatter.week_aligned_year ~D[2017-01-04], 1
"2017"
iex> Cldr.DateTime.Formatter.week_aligned_year ~D[2017-01-04], 2
"17"
iex> Cldr.DateTime.Formatter.week_aligned_year ~D[2017-01-04], 3
"2017"
iex> Cldr.DateTime.Formatter.week_aligned_year ~D[2017-01-04], 4
"2017"
iex> Cldr.DateTime.Formatter.week_aligned_year ~D[2017-01-04], 5
"02017"
@spec week_aligned_year( Cldr.Calendar.date(), integer(), Cldr.Locale.locale_reference(), Cldr.backend(), map() ) :: String.t() | {:error, String.t()}
@spec week_of_month(Cldr.Calendar.any_date_time(), integer(), Keyword.t()) :: String.t() | {:error, String.t()}
Returns the week of the month (format symbol W
) as an integer.
Arguments
date
is aDate
struct or any map that contains at least the keys:year
,:month
,:day
and:calendar
n
in an integer between that should be between 1 and 4 that determines the format of the week of the monthlocale
is any valid locale name returned byCldr.known_locale_names/0
or aCldr.LanguageTag.t/0
struct. The default isCldr.get_locale/0
options
is aKeyword
list of options. There are no options used inweek_of_month/4
Format Symbol
The representation of the week of the month is made in accordance with the following table:
Symbol | Example | Cldr Format |
---|---|---|
W | 2 |
Examples
iex> import Cldr.Calendar.Sigils
Cldr.Calendar.Sigils
iex> Cldr.DateTime.Formatter.week_of_month ~D[2019-01-07], 1
"2"
iex> Cldr.DateTime.Formatter.week_of_month ~d[2019-W04-1], 1
"4"
@spec week_of_month( Cldr.Calendar.date(), integer(), Cldr.Locale.locale_reference(), Cldr.backend(), map() ) :: String.t() | {:error, String.t()}
@spec week_of_year(Cldr.Calendar.any_date_time(), integer(), Keyword.t()) :: String.t() | {:error, String.t()}
Returns the week of the year (symbol w
) as an integer.
Arguments
date
is aDate
struct or any map that contains at least the keys:year
,:month
,:day
and:calendar
n
in an integer between 1 and 2 that determines the format of the week of the yearlocale
is any valid locale name returned byCldr.known_locale_names/0
or aCldr.LanguageTag.t/0
struct. The default isCldr.get_locale/0
options
is aKeyword
list of options. There are no options used inweek_of_year/4
Notes
Determining the week of the year is influenced by two factors:
The calendar in use. For example the ISO calendar (which is the default calendar in Elixir) follows the ISO standard in which the first week of the year is the week containing the first thursday of the year.
The territory in use. For example, in the US the first week of the year is the week containing January 1st whereas many territories follow the ISO standard.
Format Symbol
The representation of the day of the year is made in accordance with the following table:
Symbol | Example | Cldr Format |
---|---|---|
w | 2, 22 | |
ww | 02, 22 |
Examples
iex> import Cldr.Calendar.Sigils
Cldr.Calendar.Sigils
iex> Cldr.DateTime.Formatter.week_of_year ~D[2019-01-07], 1
"2"
iex> Cldr.DateTime.Formatter.week_of_year ~d[2019-W04-1], 2
"04"
@spec week_of_year( Cldr.Calendar.date(), integer(), Cldr.Locale.locale_reference(), Cldr.backend(), map() ) :: String.t() | {:error, String.t()}
@spec year(Cldr.Calendar.any_date_time(), integer(), Keyword.t()) :: String.t() | {:error, String.t()}
Returns the year
(format symbol y
) of a date
as an integer. The y
format returns the year
as a simple integer in string format.
The format yy
is a special case which requests just
the two low-order digits of the year, zero-padded
as necessary. For most use cases, y
or yy
should
be adequate.
Arguments
date
is aDate
struct or any map that contains at least the keys:month
and:calendar
n
in an integer between 1 and 5 that determines the format of the yearlocale
is any valid locale name returned byCldr.known_locale_names/0
or aCldr.LanguageTag.t/0
struct. The default isCldr.get_locale/0
options
is aKeyword
list of options. There are no options used inyear/4
Format Symbol
The representation of the quarter is made in accordance with the following table:
Symbol | Example | Cldr Format |
---|---|---|
y | 7 | Minimum necessary digits |
yy | "17" | Least significant 2 digits |
yyy | "017", "2017" | Padded to at least 3 digits |
yyyy | "2017" | Padded to at least 4 digits |
yyyyy | "02017" | Padded to at least 5 digits |
In most cases the length of the y
field specifies
the minimum number of digits to display, zero-padded
as necessary; more digits will be displayed if needed
to show the full year.
Examples
iex> Cldr.DateTime.Formatter.year %{year: 2017, calendar: Calendar.ISO}, 1
2017
iex> Cldr.DateTime.Formatter.year %{year: 2017, calendar: Calendar.ISO}, 2
"17"
iex> Cldr.DateTime.Formatter.year %{year: 2017, calendar: Calendar.ISO}, 3
"2017"
iex> Cldr.DateTime.Formatter.year %{year: 2017, calendar: Calendar.ISO}, 4
"2017"
iex> Cldr.DateTime.Formatter.year %{year: 2017, calendar: Calendar.ISO}, 5
"02017"
@spec year( Cldr.Calendar.any_date_time(), integer(), Cldr.Locale.locale_reference(), Cldr.backend(), map() ) :: String.t() | {:error, String.t()}
@spec zone_basic(Cldr.Calendar.date_time(), integer(), Keyword.t()) :: String.t() | {:error, String.t()}
Returns the basic zone offset (format symbol Z
) part of a DateTime
or Time
,
The ISO8601 basic format with hours, minutes and optional seconds fields. The format is equivalent to RFC 822 zone format (when optional seconds field is absent). This is equivalent to the "xxxx" specifier.
Arguments
time
is aDateTime.t/0
struct or any map that contains at least the:utc_offset
and:std_offset
keys of the format used byTime
n
is the specific non-location timezone format and is in the range1..4
locale
is any valid locale name returned byCldr.known_locale_names/0
or aCldr.LanguageTag.t/0
struct. The default isCldr.get_locale/0
options
is aKeyword
list of options. There are no options used inzone_basic/4
Format Symbol
The representation of the timezone
is made in accordance with the following
table:
Symbol | Results | Description |
---|---|---|
Z..ZZZ | "+0100" | ISO8601 Basic Format with hours and minutes |
ZZZZ | "+01:00" | Delegates to `zone_gmt/4 |
ZZZZZ | "+01:00:10" | ISO8601 Extended format with optional seconds |
Examples
iex> Cldr.DateTime.Formatter.zone_basic %{time_zone: "Etc/UTC",
...> utc_offset: 3600, std_offset: 0}, 1
"+0100"
iex> Cldr.DateTime.Formatter.zone_basic %{time_zone: "Etc/UTC",
...> utc_offset: 3610, std_offset: 0}, 4
"GMT+01:00"
iex> Cldr.DateTime.Formatter.zone_basic %{time_zone: "Etc/UTC",
...> utc_offset: 0, std_offset: 0}, 5
"Z"
iex> Cldr.DateTime.Formatter.zone_basic %{time_zone: "Etc/UTC",
...> utc_offset: 3610, std_offset: 0}, 5
"+01:00:10"
@spec zone_basic( Cldr.Calendar.date_time(), integer(), Cldr.Locale.locale_reference(), Cldr.backend(), map() ) :: String.t() | {:error, String.t()}
@spec zone_generic(Cldr.Calendar.date_time(), integer(), Keyword.t()) :: String.t() | {:error, String.t()}
Returns the generic non-location format of a timezone (format symbol v
)
from a DateTime
or Time
.
Since Elixir does not provide full time zone support, we return here only
the :time_zone
element of the provided DateTime
or other struct without
any localization.
Arguments
time
is aDateTime.t/0
struct or any map that contains at least the key:time_zone
key of the format used byTime
n
is the generic non-location timezone format and is either1
(the default) or4
locale
is any valid locale name returned byCldr.known_locale_names/0
or aCldr.LanguageTag.t/0
struct. The default isCldr.get_locale/0
options
is aKeyword
list of options. There are no options used inzone_generic/4
Format Symbol
The representation of the timezone
is made in accordance with the following
table:
Symbol | Results | Description |
---|---|---|
v | "Etc/UTC" | :time_zone key, unlocalised |
vvvv | "unk" | Generic timezone name. Currently returns only "unk" |
Examples
iex> Cldr.DateTime.Formatter.zone_generic %{time_zone: "Etc/UTC",
...> utc_offset: 0, std_offset: 0}, 4
"GMT"
iex> Cldr.DateTime.Formatter.zone_generic %{time_zone: "Etc/UTC",
...> utc_offset: 0, std_offset: 0}, 1
"Etc/UTC"
@spec zone_generic( Cldr.Calendar.date_time(), integer(), Cldr.Locale.locale_reference(), Cldr.backend(), map() ) :: String.t() | {:error, String.t()}
@spec zone_gmt(Cldr.Calendar.date_time(), integer(), Keyword.t()) :: String.t() | {:error, String.t()}
Returns the short localised GMT offset (format symbol O
) part of a
DateTime
or Time
.
Arguments
time
is aDateTime.t/0
struct or any map that contains at least the:utc_offset
and:std_offset
keys of the format used byTime
n
is the specific non-location timezone format and is in the range1..4
locale
is any valid locale name returned byCldr.known_locale_names/0
or aCldr.LanguageTag.t/0
struct. The default isCldr.get_locale/0
options
is aKeyword
list of options. There are no options used inzone_gmt/4
Format Symbol
The representation of the GMT offset
is made in accordance with the following
table:
Symbol | Results | Description |
---|---|---|
O | "GMT+1" | Short localised GMT format |
OOOO | "GMT+01:00" | Long localised GMT format |
Examples
iex> Cldr.DateTime.Formatter.zone_gmt %{time_zone: "Etc/UTC",
...> utc_offset: 3610, std_offset: 0}, 1
"GMT+1"
iex> Cldr.DateTime.Formatter.zone_gmt %{time_zone: "Etc/UTC",
...> utc_offset: 3610, std_offset: 0}, 4
"GMT+01:00"
@spec zone_gmt( Cldr.Calendar.date_time(), integer(), Cldr.Locale.locale_reference(), Cldr.backend(), map() ) :: String.t() | {:error, String.t()}
@spec zone_id(Cldr.Calendar.date_time(), integer(), Keyword.t()) :: String.t() | {:error, String.t()}
Returns the time zone ID (format symbol V
) part of a DateTime
or Time
For now the short timezone name, exemplar city and generic location formats are not supported and therefore return the fallbacks defined in CLDR.
Arguments
time
is aDateTime.t/0
struct or any map that contains at least the:utc_offset
and:std_offset
keys of the format used byTime
n
is the specific non-location timezone format and is in the range1..4
locale
is any valid locale name returned byCldr.known_locale_names/0
or aCldr.LanguageTag.t/0
struct. The default isCldr.get_locale/0
options
is aKeyword
list of options. There are no options used inzone_id/4
Format Symbol
The representation of the timezone ID
is made in accordance with the following
table:
Symbol | Results | Description |
---|---|---|
V | "unk" | :zone_abbr key, unlocalised |
VV | "Etc/UTC | Delegates to zone_gmt/4 |
VVV | "Unknown City" | Examplar city. Not supported. |
VVVV | "GMT" | Delegates to `zone_gmt/4 |
Examples
iex> Cldr.DateTime.Formatter.zone_id %{zone_abbr: "Etc/UTC",
...> utc_offset: 0, std_offset: 0}, 1
"unk"
iex> Cldr.DateTime.Formatter.zone_id %{zone_abbr: "Etc/UTC",
...> utc_offset: 0, std_offset: 0}, 2
"Etc/UTC"
iex> Cldr.DateTime.Formatter.zone_id %{zone_abbr: "Etc/UTC",
...> utc_offset: 0, std_offset: 0}, 3
"Unknown City"
iex> Cldr.DateTime.Formatter.zone_id %{zone_abbr: "Etc/UTC",
...> utc_offset: 0, std_offset: 0}, 4
"GMT"
@spec zone_id( Cldr.Calendar.date_time(), integer(), Cldr.Locale.locale_reference(), Cldr.backend(), map() ) :: String.t() | {:error, String.t()}
@spec zone_iso(Cldr.Calendar.date_time(), integer(), Keyword.t()) :: String.t() | {:error, String.t()}
Returns the ISO zone offset (format symbol x
) part of a DateTime
or Time
,
This is the ISO8601 format with hours, minutes and optional seconds fields but with no "Z" as the identifier if the timezone offset is 0.
Arguments
time
is aDateTime.t/0
struct or any map that contains at least the:utc_offset
and:std_offset
keys of the format used byTime
n
is the specific non-location timezone format and is in the range1..4
locale
is any valid locale name returned byCldr.known_locale_names/0
or aCldr.LanguageTag.t/0
struct. The default isCldr.get_locale/0
options
is aKeyword
list of options. There are no options used inzone_iso/4
Format Symbol
The representation of the timezone offset
is made in accordance with the following
table:
Symbol | Results | Description |
---|---|---|
x | "+0100" | ISO8601 Basic Format with hours and optional minutes |
xx | "-0800" | ISO8601 Basic Format with hours and minutes |
xxx | "+01:00" | ISO8601 Extended Format with hours and minutes |
xxxx | "+010059" | ISO8601 Basic Format with hours and minutes, optional seconds |
xxxxx | "+01:00:10" | ISO8601 Extended Format with hours and minutes, optional seconds |
Examples
iex> Cldr.DateTime.Formatter.zone_iso %{time_zone: "Etc/UTC",
...> utc_offset: 3610, std_offset: 0}, 1
"+01"
iex> Cldr.DateTime.Formatter.zone_iso %{time_zone: "Etc/UTC",
...> utc_offset: 3610, std_offset: 0}, 2
"+0100"
iex> Cldr.DateTime.Formatter.zone_iso %{time_zone: "Etc/UTC",
...> utc_offset: 3610, std_offset: 0}, 3
"+01:00"
iex> Cldr.DateTime.Formatter.zone_iso %{time_zone: "Etc/UTC",
...> utc_offset: 3610, std_offset: 0}, 4
"+010010"
iex> Cldr.DateTime.Formatter.zone_iso %{time_zone: "Etc/UTC",
...> utc_offset: 3610, std_offset: 0}, 5
"+01:00:10"
iex> Cldr.DateTime.Formatter.zone_iso %{time_zone: "Etc/UTC",
...> utc_offset: 0, std_offset: 0}, 5
"+00:00"
iex> Cldr.DateTime.Formatter.zone_iso %{time_zone: "Etc/UTC",
...> utc_offset: 0, std_offset: 0}, 4
"+0000"
iex> Cldr.DateTime.Formatter.zone_iso %{time_zone: "Etc/UTC",
...> utc_offset: 0, std_offset: 0}, 3
"+00:00"
iex> Cldr.DateTime.Formatter.zone_iso %{time_zone: "Etc/UTC",
...> utc_offset: 0, std_offset: 0}, 2
"+0000"
iex> Cldr.DateTime.Formatter.zone_iso %{time_zone: "Etc/UTC",
...> utc_offset: 0, std_offset: 0}, 1
"+00"
@spec zone_iso( Cldr.Calendar.date_time(), integer(), Cldr.Locale.locale_reference(), Cldr.backend(), map() ) :: String.t() | {:error, String.t()}
@spec zone_iso_z(Cldr.Calendar.date_time(), integer(), Keyword.t()) :: String.t() | {:error, String.t()}
Returns the ISO zone offset (format symbol X
) part of a DateTime
or Time
,
This is the ISO8601 format with hours, minutes and optional seconds fields with "Z" as the identifier if the timezone offset is 0.
Arguments
time
is aDateTime.t/0
struct or any map that contains at least the:utc_offset
and:std_offset
keys of the format used byTime
n
is the specific non-location timezone format and is in the range1..4
locale
is any valid locale name returned byCldr.known_locale_names/0
or aCldr.LanguageTag.t/0
struct. The default isCldr.get_locale/0
options
is aKeyword
list of options. There are no options used inzone_iso_z/4
Format Symbol
The representation of the timezone offset
is made in accordance with the following
table:
Symbol | Results | Description |
---|---|---|
X | "+01" | ISO8601 Basic Format with hours and optional minutes or "Z" |
XX | "+0100" | ISO8601 Basic Format with hours and minutes or "Z" |
XXX | "+0100" | ISO8601 Basic Format with hours and minutes, optional seconds or "Z" |
XXXX | "+010059" | ISO8601 Basic Format with hours and minutes, optional seconds or "Z" |
XXXXX | "+01:00:10" | ISO8601 Extended Format with hours and minutes, optional seconds or "Z" |
Examples
iex> Cldr.DateTime.Formatter.zone_iso_z %{time_zone: "Etc/UTC",
...> utc_offset: 3610, std_offset: 0}, 1
"+01"
iex> Cldr.DateTime.Formatter.zone_iso_z %{time_zone: "Etc/UTC",
...> utc_offset: 3610, std_offset: 0}, 2
"+0100"
iex> Cldr.DateTime.Formatter.zone_iso_z %{time_zone: "Etc/UTC",
...> utc_offset: 3610, std_offset: 0}, 3
"+01:00:10"
iex> Cldr.DateTime.Formatter.zone_iso_z %{time_zone: "Etc/UTC",
...> utc_offset: 3610, std_offset: 0}, 4
"+010010"
iex> Cldr.DateTime.Formatter.zone_iso_z %{time_zone: "Etc/UTC",
...> utc_offset: 3610, std_offset: 0}, 5
"+01:00:10"
iex> Cldr.DateTime.Formatter.zone_iso_z %{time_zone: "Etc/UTC",
...> utc_offset: 0, std_offset: 0}, 5
"Z"
iex> Cldr.DateTime.Formatter.zone_iso_z %{time_zone: "Etc/UTC",
...> utc_offset: 0, std_offset: 0}, 4
"Z"
iex> Cldr.DateTime.Formatter.zone_iso_z %{time_zone: "Etc/UTC",
...> utc_offset: 0, std_offset: 0}, 3
"Z"
iex> Cldr.DateTime.Formatter.zone_iso_z %{time_zone: "Etc/UTC",
...> utc_offset: 0, std_offset: 0}, 2
"Z"
@spec zone_iso_z( Cldr.Calendar.date_time(), integer(), Cldr.Locale.locale_reference(), Cldr.backend(), map() ) :: String.t() | {:error, String.t()}
@spec zone_short(Cldr.Calendar.date_time(), integer(), Keyword.t()) :: String.t() | {:error, String.t()}
Returns the specific non-location format of a timezone (format symbol z
)
from a DateTime
or Time
.
Since Elixir does not provide full time zone support, we return here only
the :time_zone
element of the provided DateTime
or other struct without
any localization.
Arguments
time
is aDateTime.t/0
struct or any map that contains at least the:zone_abbr
,:utc_offset
and:std_offset
keys of the format used byTime
n
is the specific non-location timezone format and is in the range1..4
locale
is any valid locale name returned byCldr.known_locale_names/0
or aCldr.LanguageTag.t/0
struct. The default isCldr.get_locale/0
options
is aKeyword
list of options. There are no options used inzone_short/4
Format Symbol
The representation of the timezone
is made in accordance with the following
table:
Symbol | Results | Description |
---|---|---|
z..zzz | "UTC" | :zone_abbr key, unlocalised |
zzzz | "GMT" | Delegates to zone_gmt/4 |
Examples
iex> Cldr.DateTime.Formatter.zone_short %{zone_abbr: "UTC",
...> utc_offset: 0, std_offset: 0}, 1
"UTC"
iex> Cldr.DateTime.Formatter.zone_short %{zone_abbr: "UTC",
...> utc_offset: 0, std_offset: 0}, 4
"GMT"
@spec zone_short( Cldr.Calendar.date_time(), integer(), Cldr.Locale.locale_reference(), Cldr.backend(), map() ) :: String.t() | {:error, String.t()}