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

ElementSymbolExampleCldr Format
EraG, GG, GGG"AD"Abbreviated
GGGG"Anno Domini"Wide
GGGGG"A"Narrow
Yeary7Minimum 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 YearY7Minimum 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 Yearr, rr, rr+2017Minimum necessary digits
Cyclic YearU, UU, UUU"甲子"Abbreviated
UUUU"甲子" (for now)Wide
UUUUU"甲子" (for now)Narrow
Extended Yearu+4601Minimum necessary digits
QuarterQ2Single digit
QQ"02"Two digits
QQQ"Q2"Abbreviated
QQQQ"2nd quarter"Wide
QQQQQ"2"Narrow
Standalone Quarterq2Single digit
qq"02"Two digits
qqq"Q2"Abbreviated
qqqq"2nd quarter"Wide
qqqqq"2"Narrow
MonthM9Single digit
MM"09"Two digits
MMM"Sep"Abbreviated
MMMM"September"Wide
MMMMM"S"Narrow
Standalone MonthL9Single digit
LL"09"Two digits
LLL"Sep"Abbreviated
LLLL"September"Wide
LLLLL"S"Narrow
Week of Yearw2, 22Single digit
ww02, 22Two digits, zero padded
Week of MonthW2Single digit
Day of YearD3, 33, 333Minimum necessary digits
DD03, 33, 333Minimum of 2 digits, zero padded
DDD003, 033, 333Minimum of 3 digits, zero padded
Day of Monthd2, 22Minimum necessary digits
dd02, 22Two digits, zero padded
ddd2nd, 25thOrdinal day of month
Day of WeekE, EE, EEE"Tue"Abbreviated
EEEE"Tuesday"Wide
EEEEE"T"Narrow
EEEEEE"Tu"Short
e2Single digit
ee"02"Two digits
eee"Tue"Abbreviated
eeee"Tuesday"Wide
eeeee"T"Narrow
eeeeee"Tu"Short
Standalone Day of Weekc, cc2Single digit
ccc"Tue"Abbreviated
cccc"Tuesday"Wide
ccccc"T"Narrow
cccccc"Tu"Short
AM or PMa, aa, aaa"am."Abbreviated
aaaa"am."Wide
aaaaa"am"Narrow
Noon, Mid, AM, PMb, bb, bbb"mid."Abbreviated
bbbb"midnight"Wide
bbbbb"md"Narrow
Flexible time periodB, BB, BBB"at night"Abbreviated
BBBB"at night"Wide
BBBBB"at night"Narrow
Hourh, K, H, kSee the table below
Minutem3, 10Minimum digits of minutes
mm"03", "12"Two digits, zero padded
Seconds3, 48Minimum digits of seconds
ss"03", "48"Two digits, zero padded
Fractional SecondsS3, 48Minimum digits of fractional seconds
SS"03", "48"Two digits, zero padded
MillisecondsA+4000, 63241Minimum digits of milliseconds since midnight
Generic non-location TZv"Etc/UTC":time_zone key, unlocalised
vvvv"unk"Generic timezone name. Currently returns only "unk"
Specific non-location TZz..zzz"UTC":zone_abbr key, unlocalised
zzzz"GMT"Delegates to zone_gmt/4
Timezone IDV"unk":zone_abbr key, unlocalised
VV"Etc/UTCDelegates to zone_gmt/4
VVV"Unknown City"Exemplar city. Not supported.
VVVV"GMT"Delegates to `zone_gmt/4
ISO8601 FormatZ..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 ZX"+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 Zx"+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 FormatO"+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:

SymbolMidn.MorningNoonAfternoonMidn.
h121...11121...1112
K01...1101...110
H01...111213...230
k241...111213...2324

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 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.

Returns the basic zone offset (format symbol Z) part of a DateTime or Time,

Returns the generic non-location format of a timezone (format symbol v) from a DateTime or Time.

Returns the short localised GMT offset (format symbol O) part of a DateTime or Time.

Returns the time zone ID (format symbol V) part of a DateTime or Time

Returns the ISO zone offset (format symbol x) part of a DateTime or Time,

Returns the ISO zone offset (format symbol X) part of a DateTime or Time,

Returns the specific non-location format of a timezone (format symbol z) from a DateTime or Time.

Functions

Link to this function

cyclic_year(cyclic_year, n \\ 1, options \\ [])

View Source
@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

SymbolExampleCldr 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.

Link to this function

cyclic_year(date, n, locale, backend, options \\ %{})

View Source
@spec cyclic_year(
  Cldr.Calendar.any_date_time(),
  integer(),
  Cldr.Locale.locale_reference(),
  Cldr.backend(),
  map()
) :: String.t() | {:error, String.t()}
Link to this function

date(date, n \\ 1, options \\ [])

View Source
@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.

Link to this function

date(date, n, locale, backend, options)

View Source
@spec date(
  Calendar.date(),
  integer(),
  Cldr.Locale.locale_reference(),
  Cldr.backend(),
  Keyword.t() | map()
) :: String.t() | {:error, {module(), String.t()}}
Link to this function

day_name(day_name, n \\ 1, options \\ [])

View Source
@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

Format Symbol

The representation of the day name is made in accordance with the following table:

SymbolExampleCldr 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"
Link to this function

day_name(date, n, locale, backend, options \\ %{})

View Source
Link to this function

day_of_month(day_of_month, n \\ 1, options \\ [])

View Source
@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

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.

SymbolExampleCldr Format
d2, 22
dd02, 22
ddd2nd, 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"
Link to this function

day_of_month(date, n, locale, backend, options \\ %{})

View Source
@spec day_of_month(
  Cldr.Calendar.date(),
  integer(),
  Cldr.Locale.locale_reference(),
  Cldr.backend(),
  map()
) :: String.t() | {:error, String.t()}
Link to this function

day_of_week(day_of_week, n \\ 1, options \\ [])

View Source
@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

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:

SymbolExampleCldr Format
e2Single 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"
Link to this function

day_of_week(date, n, locale, backend, options \\ %{})

View Source
@spec day_of_week(
  Cldr.Calendar.any_date_time(),
  integer(),
  Cldr.Locale.locale_reference(),
  Cldr.backend(),
  map()
) :: String.t() | {:error, String.t()}
Link to this function

day_of_year(day_of_year, n \\ 1, options \\ [])

View Source
@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

Format Symbol

The representation of the day of the year is made in accordance with the following table:

SymbolExampleCldr Format
D3, 33, 333
DD03, 33, 333
DDD003, 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"
Link to this function

day_of_year(date, n, locale, backend, options \\ %{})

View Source
@spec day_of_year(
  Cldr.Calendar.any_date_time(),
  integer(),
  Cldr.Locale.locale_reference(),
  Cldr.backend(),
  map()
) :: String.t() | {:error, String.t()}
Link to this function

era(date, n \\ 1, options \\ [])

View Source
@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 a Date 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 year

  • locale is any valid locale name returned by Cldr.known_locale_names/0 or a Cldr.LanguageTag.t/0 struct. The default is Cldr.get_locale/0

  • options is a Keyword list of options. The only applicable option is :era with a value of either nil (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:

SymbolExampleCldr Format
G, GG, GGG"AD"Abbreviated
GGGG"Anno DominiWide
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"
Link to this function

era(date, n, locale, backend, options \\ %{})

View Source
Link to this function

extended_year(extended_year, n \\ 1, options \\ [])

View Source
@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 a Date 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 year

  • locale is any valid locale name returned by Cldr.known_locale_names/0 or a Cldr.LanguageTag.t/0 struct. The default is Cldr.get_locale/0

  • options is a Keyword list of options. There are no options used in weeK_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

SymbolExampleCldr Format
u+4601Minimum 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.

Link to this function

extended_year(date, n, locale, backend, options \\ %{})

View Source
@spec extended_year(
  Calendar.date(),
  integer(),
  Cldr.Locale.locale_reference(),
  Cldr.backend(),
  map()
) ::
  String.t() | {:error, String.t()}
Link to this function

fractional_second(fractional_second, n \\ 1, options \\ [])

View Source
@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

Format Symbol

The representation of the second is made in accordance with the following table:

SymbolResultsDescription
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"
Link to this function

fractional_second(time, n, locale, backend, options \\ %{})

View Source
@spec fractional_second(
  Cldr.Calendar.time(),
  integer(),
  Cldr.Locale.locale_reference(),
  Cldr.backend(),
  map()
) :: String.t() | {:error, String.t()}
Link to this function

h11(h11, n \\ 1, options \\ [])

View Source
@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

Format Symbol

The representation of the hour is made in accordance with the following table:

SymbolMidn.MorningNoonAfternoonMidn.
K01...1101...110

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"
Link to this function

h11(time, n, locale, backend, options \\ %{})

View Source
Link to this function

h12(h12, n \\ 1, options \\ [])

View Source
@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

Format Symbol

The representation of the hour is made in accordance with the following table:

SymbolMidn.MorningNoonAfternoonMidn.
h121...11121...1112

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"
Link to this function

h12(time, n, locale, backend, options \\ %{})

View Source
Link to this function

h23(h23, n \\ 1, options \\ [])

View Source
@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

Format Symbol

The representation of the hour is made in accordance with the following table:

SymbolMidn.MorningNoonAfternoonMidn.
H01...111213...230

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"
Link to this function

h23(time, n, locale, backend, options \\ %{})

View Source
Link to this function

h24(h24, n \\ 1, options \\ [])

View Source
@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

Format Symbol

The representation of the hour is made in accordance with the following table:

SymbolMidn.MorningNoonAfternoonMidn.
k241...111213...2324

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"
Link to this function

h24(time, n, locale, backend, options \\ %{})

View Source
Link to this macro

has_year_and_month(date)

View Source (macro)
Link to this function

hour(hour, n \\ 1, options \\ [])

View Source
@spec hour(Cldr.Calendar.time(), integer(), Keyword.t()) ::
  String.t() | {:error, String.t()}

Returns the hour formatted in a locale-specific format

Arguments

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"
Link to this function

hour(time, n, locale, backend, options \\ %{})

View Source
Link to this function

literal(date, literal, options \\ [])

View Source
@spec literal(any(), String.t(), Keyword.t()) :: 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"
Link to this function

literal(date, binary, locale, backend, options \\ %{})

View Source
@spec literal(
  any(),
  String.t(),
  Cldr.Locale.locale_reference(),
  Cldr.backend(),
  map()
) :: String.t()
Link to this function

maybe_wrap(value, type, arg3)

View Source
Link to this function

millisecond(millisecond, n \\ 1, options \\ [])

View Source
@spec millisecond(Cldr.Calendar.time(), integer(), Keyword.t()) ::
  String.t() | {:error, String.t()}

Returns the time (format symbol A) as milliseconds since midnight.

Arguments

Format Symbol

The representation of the milliseconds is made in accordance with the following table:

SymbolResultsDescription
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"
Link to this function

millisecond(time, n, locale, backend, options \\ %{})

View Source
@spec millisecond(
  Cldr.Calendar.time(),
  integer(),
  Cldr.Locale.locale_reference(),
  Cldr.backend(),
  map()
) :: String.t() | {:error, String.t()}
Link to this function

minute(minute, n \\ 1, options \\ [])

View Source
@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

Format Symbol

The representation of the minute is made in accordance with the following table:

SymbolResultsDescription
m3, 10Minimum 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"
Link to this function

minute(time, n, locale, backend, options \\ %{})

View Source
@spec minute(
  Cldr.Calendar.time(),
  integer(),
  Cldr.Locale.locale_reference(),
  Cldr.backend(),
  map()
) ::
  String.t() | {:error, String.t()}
Link to this function

month(month, n \\ 1, options \\ [])

View Source
@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

Format Symbol

The representation of the month is made in accordance with the following table:

SymbolExampleCldr Format
M9Single 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"
Link to this function

month(date, n, locale, backend, options \\ %{})

View Source
Link to this function

period_am_pm(period_am_pm, n \\ 1, options \\ [])

View Source
@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 a Time 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 period

  • locale is any valid locale name returned by Cldr.known_locale_names/0 or a Cldr.LanguageTag.t/0 struct. The default is Cldr.get_locale/0

  • options is a Keyword list of options. The available option is period: :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:

SymbolExampleCldr 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"
Link to this function

period_am_pm(time, n, locale, backend, options \\ %{})

View Source
@spec period_am_pm(
  Cldr.Calendar.time(),
  integer(),
  Cldr.Locale.locale_reference(),
  Cldr.backend(),
  map()
) :: String.t() | {:error, String.t()}
Link to this function

period_flex(period_flex, n \\ 1, options \\ [])

View Source
@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 a Time 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 period

  • locale is any valid locale name returned by Cldr.known_locale_names/0 or a Cldr.LanguageTag.t/0 struct. The default is Cldr.get_locale/0

  • options is a Keyword list of options. The available option is period: :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:

SymbolExampleCldr 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"
Link to this function

period_flex(time, n, locale, backend, options \\ %{})

View Source
@spec period_flex(
  Cldr.Calendar.time(),
  integer(),
  Cldr.Locale.locale_reference(),
  Cldr.backend(),
  map()
) :: String.t() | {:error, String.t()}
Link to this function

period_noon_midnight(period_noon_midnight, n \\ 1, options \\ [])

View Source
@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 a Time 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 period

  • locale is any valid locale name returned by Cldr.known_locale_names/0 or a Cldr.LanguageTag.t/0 struct. The default is Cldr.get_locale/0

  • options is a Keyword list of options. The available option is period: :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:

SymbolExampleCldr 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"
Link to this function

period_noon_midnight(time, n, locale, backend, options \\ %{})

View Source
@spec period_noon_midnight(
  Cldr.Calendar.time(),
  integer(),
  Cldr.Locale.locale_reference(),
  Cldr.backend(),
  map()
) :: String.t() | {:error, String.t()}
Link to this function

quarter(quarter, n \\ 1, options \\ [])

View Source
@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

Format Symbol

The representation of the quarter is made in accordance with the following table:

SymbolExampleCldr Format
Q2Single digit
QQ"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"
Link to this function

quarter(date, n, locale, backend, options \\ %{})

View Source
Link to this function

second(second, n \\ 1, options \\ [])

View Source
@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

Format Symbol

The representation of the second is made in accordance with the following table:

SymbolResultsDescription
s3, 48Minimum 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"
Link to this function

second(time, n, locale, backend, options \\ %{})

View Source
@spec second(
  Cldr.Calendar.time(),
  integer(),
  Cldr.Locale.locale_reference(),
  Cldr.backend(),
  map()
) ::
  String.t() | {:error, String.t()}
Link to this function

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

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:

SymbolExampleCldr Format
c, cc2Single 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"
Link to this function

standalone_day_of_week(date, n, locale, backend, options \\ %{})

View Source
@spec standalone_day_of_week(
  Cldr.Calendar.date(),
  integer(),
  Cldr.Locale.locale_reference(),
  Cldr.backend(),
  map()
) :: String.t() | {:error, String.t()}
Link to this function

standalone_month(standalone_month, n \\ 1, options \\ [])

View Source
@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

Format Symbol

The representation of the standalone month is made in accordance with the following table:

SymbolExampleCldr Format
L9Single 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"
Link to this function

standalone_month(date, n, locale, backend, options \\ %{})

View Source
@spec standalone_month(
  Cldr.Calendar.date(),
  integer(),
  Cldr.Locale.locale_reference(),
  Cldr.backend(),
  map()
) :: String.t() | {:error, String.t()}
Link to this function

standalone_quarter(standalone_quarter, n \\ 1, options \\ [])

View Source
@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

Format Symbol

The representation of the quarter is made in accordance with the following table:

SymbolExampleCldr Format
q2Single digit
qq"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"
Link to this function

standalone_quarter(date, n, locale, backend, options \\ %{})

View Source
@spec standalone_quarter(
  Cldr.Calendar.date(),
  integer(),
  Cldr.Locale.locale_reference(),
  Cldr.backend(),
  map()
) :: String.t() | {:error, String.t()}
Link to this function

time(time, n \\ 1, options \\ [])

View Source
@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.

Link to this function

time(time, n, locale, backend, options)

View Source
@spec time(
  Cldr.Calendar.time(),
  integer(),
  Cldr.Locale.locale_reference(),
  Cldr.backend(),
  Keyword.t() | map()
) :: String.t() | {:error, String.t()} | {:error, {module(), String.t()}}
Link to this function

week_aligned_year(week_aligned_year, n \\ 1, options \\ [])

View Source
@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 a Date 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 year

  • locale is any valid locale name returned by Cldr.known_locale_names/0 or a Cldr.LanguageTag.t/0 struct. The default is Cldr.get_locale/0

  • options is a Keyword list of options. There are no options used in weeK_aligned_year/4

Format Symbol

The representation of the year is made in accordance with the following table:

SymbolExampleCldr Format
Y7Minimum 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"
Link to this function

week_aligned_year(date, n, locale, backend, options \\ %{})

View Source
@spec week_aligned_year(
  Cldr.Calendar.date(),
  integer(),
  Cldr.Locale.locale_reference(),
  Cldr.backend(),
  map()
) :: String.t() | {:error, String.t()}
Link to this function

week_of_month(week_of_month, n \\ 1, options \\ [])

View Source
@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

Format Symbol

The representation of the week of the month is made in accordance with the following table:

SymbolExampleCldr Format
W2

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"
Link to this function

week_of_month(date, n, locale, backend, options \\ %{})

View Source
@spec week_of_month(
  Cldr.Calendar.date(),
  integer(),
  Cldr.Locale.locale_reference(),
  Cldr.backend(),
  map()
) :: String.t() | {:error, String.t()}
Link to this function

week_of_year(week_of_year, n \\ 1, options \\ [])

View Source
@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

Notes

Determining the week of the year is influenced by two factors:

  1. 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.

  2. 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:

SymbolExampleCldr Format
w2, 22
ww02, 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"
Link to this function

week_of_year(date, n, locale, backend, options \\ %{})

View Source
@spec week_of_year(
  Cldr.Calendar.date(),
  integer(),
  Cldr.Locale.locale_reference(),
  Cldr.backend(),
  map()
) :: String.t() | {:error, String.t()}
Link to this function

year(year, n \\ 1, options \\ [])

View Source
@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

Format Symbol

The representation of the quarter is made in accordance with the following table:

SymbolExampleCldr Format
y7Minimum 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"
Link to this function

year(date, n, locale, backend, options \\ %{})

View Source
Link to this function

zone_basic(zone_basic, n \\ 1, options \\ [])

View Source
@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

Format Symbol

The representation of the timezone is made in accordance with the following table:

SymbolResultsDescription
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"
Link to this function

zone_basic(time, n, locale, backend, options \\ %{})

View Source
@spec zone_basic(
  Cldr.Calendar.date_time(),
  integer(),
  Cldr.Locale.locale_reference(),
  Cldr.backend(),
  map()
) :: String.t() | {:error, String.t()}
Link to this function

zone_generic(zone_generic, n \\ 1, options \\ [])

View Source
@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

Format Symbol

The representation of the timezone is made in accordance with the following table:

SymbolResultsDescription
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"
Link to this function

zone_generic(time, n, locale, backend, options \\ %{})

View Source
@spec zone_generic(
  Cldr.Calendar.date_time(),
  integer(),
  Cldr.Locale.locale_reference(),
  Cldr.backend(),
  map()
) :: String.t() | {:error, String.t()}
Link to this function

zone_gmt(zone_gmt, n \\ 1, options \\ [])

View Source
@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

Format Symbol

The representation of the GMT offset is made in accordance with the following table:

SymbolResultsDescription
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"
Link to this function

zone_gmt(time, n, locale, backend, options \\ %{})

View Source
Link to this function

zone_id(zone_id, n \\ 1, options \\ [])

View Source
@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

Format Symbol

The representation of the timezone ID is made in accordance with the following table:

SymbolResultsDescription
V"unk":zone_abbr key, unlocalised
VV"Etc/UTCDelegates 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"
Link to this function

zone_id(time, n, locale, backend, options \\ %{})

View Source
Link to this function

zone_iso(zone_iso, n \\ 1, options \\ [])

View Source
@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

Format Symbol

The representation of the timezone offset is made in accordance with the following table:

SymbolResultsDescription
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"
Link to this function

zone_iso(time, n, locale, backend, options \\ %{})

View Source
Link to this function

zone_iso_z(zone_iso_z, n \\ 1, options \\ [])

View Source
@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

Format Symbol

The representation of the timezone offset is made in accordance with the following table:

SymbolResultsDescription
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"
Link to this function

zone_iso_z(time, n, locale, backend, options \\ %{})

View Source
@spec zone_iso_z(
  Cldr.Calendar.date_time(),
  integer(),
  Cldr.Locale.locale_reference(),
  Cldr.backend(),
  map()
) :: String.t() | {:error, String.t()}
Link to this function

zone_short(zone_short, n \\ 1, options \\ [])

View Source
@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

Format Symbol

The representation of the timezone is made in accordance with the following table:

SymbolResultsDescription
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"
Link to this function

zone_short(time, n, locale, backend, options \\ %{})

View Source
@spec zone_short(
  Cldr.Calendar.date_time(),
  integer(),
  Cldr.Locale.locale_reference(),
  Cldr.backend(),
  map()
) :: String.t() | {:error, String.t()}