Cldr_Dates_Times v0.1.0 Cldr.DateTime.Formatter View Source

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+4601Minimim 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
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, 10Minimim digits of minutes
mm“03”, “12”Two digits, zero padded
Seconds3, 48Minimim digits of seconds
ss“03”, “48”Two digits, zero padded
Fractional SecondsS3, 48Minimim digits of fractional seconds
SS“03”, “48”Two digits, zero padded
MillsecondsA+4000, 63241Minimim 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

Link to this section Summary

Functions

Returns the cyclic year (format symbol U) name for non-gregorian calendars

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 formatted and localised date, time or datetime for a given Date, Time, DateTime or struct with the appropriate fields

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 0..23 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 k) as a number in the range 1..24 as a string

Returns a boolean indicating is a given language defines the notion of “noon” and “midnight”

Returns the time (format symbol A) as millisenconds 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 the time period for a given time of day

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

Link to this section Functions

Link to this function cyclic_year(date, n \\ 1, locale \\ Cldr.get_current_locale(), options \\ []) View Source
cyclic_year(Map.t, integer, Cldr.Locale.t, Keyword.t) ::
  binary |
  {:error, binary}

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 localed cyclic year.

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 date(date, n \\ 1, locale \\ Cldr.get_current_locale(), options \\ []) View Source
date(Map.t, integer, Cldr.Locale.t, Keyword.t) ::
  binary |
  {:error, binary}

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 day_name(date, n \\ 1, locale \\ Cldr.get_current_locale(), options \\ []) View Source
day_name(Map.t, integer, Cldr.Locale.t, Keyword.t) ::
  binary |
  {:error, binary}

Returns the weekday name (format symbol E) as an string.

  • date is a Date 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 week

  • locale is any locale returned by Cldr.known_locales/0 which determines the localisation of the format

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

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 %{year: 2017, month: 8, day: 15,
...> calendar: Calendar.ISO}, 6
"Tu"

iex> Cldr.DateTime.Formatter.day_name %{year: 2017, month: 8, day: 15,
...> calendar: Calendar.ISO}, 5
"T"

iex> Cldr.DateTime.Formatter.day_name %{year: 2017, month: 8, day: 15,
...> calendar: Calendar.ISO}, 4
"Tuesday"

iex> Cldr.DateTime.Formatter.day_name %{year: 2017, month: 8, day: 15,
...> calendar: Calendar.ISO}, 3
"Tue"

iex> Cldr.DateTime.Formatter.day_name %{year: 2017, month: 8, day: 15,
...> calendar: Calendar.ISO}, 2
"Tue"

iex> Cldr.DateTime.Formatter.day_name %{year: 2017, month: 8, day: 15,
...> calendar: Calendar.ISO}, 1
"Tue"
Link to this function day_of_month(date, n \\ 1, locale \\ Cldr.get_current_locale(), options \\ []) View Source
day_of_month(Map.t, integer, Cldr.Locale.t, Keyword.t) ::
  binary |
  {:error, binary}

Returns the day of the month (symbol d) as an integer.

  • date is a Date 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 month

  • locale is any locale returned by Cldr.known_locales/0 which determines the localisation of the format

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

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

SymbolExampleCldr Format
d2, 22
dd02, 22

Examples

iex> Cldr.DateTime.Formatter.day_of_month %{year: 2017, month: 1, day: 4,
...> calendar: Calendar.ISO}, 1
4

iex> Cldr.DateTime.Formatter.day_of_month %{year: 2017, month: 1, day: 4,
...> calendar: Calendar.ISO}, 2
"04"
Link to this function day_of_week(date, n \\ 1, locale \\ Cldr.get_current_locale(), options \\ []) View Source
day_of_week(Map.t, integer, Cldr.Locale.t, Keyword.t) ::
  binary |
  {:error, binary}

Returns the local day of week (format symbol e) as a number or name.

  • date is a Date 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 week

  • locale is any locale returned by Cldr.known_locales/0 which determines the localisation of the format

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

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.

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 %{year: 2017, month: 8, day: 15,
...> calendar: Calendar.ISO}, 3
"Tue"

iex> Cldr.DateTime.Formatter.day_of_week %{year: 2017, month: 8, day: 15,
...> calendar: Calendar.ISO}, 4
"Tuesday"

iex> Cldr.DateTime.Formatter.day_of_week %{year: 2017, month: 8, day: 15,
...> calendar: Calendar.ISO}, 5
"T"

iex> Cldr.DateTime.Formatter.day_of_week %{year: 2017, month: 8, day: 15,
...> calendar: Calendar.ISO}, 6
"Tu"

iex> Cldr.DateTime.Formatter.day_of_week %{year: 2017, month: 8, day: 15,
...> calendar: Calendar.ISO}, 1
"2"

iex> Cldr.DateTime.Formatter.day_of_week %{year: 2017, month: 8, day: 15,
...> calendar: Calendar.ISO}, 2
"02"
Link to this function day_of_year(date, n \\ 1, locale \\ Cldr.get_current_locale(), options \\ []) View Source
day_of_year(Map.t, integer, Cldr.Locale.t, Keyword.t) ::
  binary |
  {:error, binary}

Returns the day of the year (symbol D) as an integer in string format.

  • date is a Date 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 year

  • locale is any locale returned by Cldr.known_locales/0 which determines the localisation of the format

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

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 %{year: 2017, month: 1, day: 15,
...> calendar: Calendar.ISO}, 1
"15"

iex> Cldr.DateTime.Formatter.day_of_year %{year: 2017, month: 1, day: 15,
...> calendar: Calendar.ISO}, 2
"15"

iex> Cldr.DateTime.Formatter.day_of_year %{year: 2017, month: 1, day: 15,
...> calendar: Calendar.ISO}, 3
"015"
Link to this function era(date, n \\ 1, locale \\ Cldr.get_current_locale(), options \\ []) View Source
era(Map.t, integer, Cldr.Locale.t, Keyword.t) ::
  binary |
  {:error, binary}

Returns the era (format symbol G) of a date for given locale.

  • 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 locale returned by Cldr.known_locales/0 which determines the localisation of the format

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

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

Link to this function extended_year(date, n \\ 1, locale \\ Cldr.get_current_locale(), options \\ []) View Source
extended_year(Map.t, integer, Cldr.Locale.t, Keyword.t) ::
  binary |
  {:error, binary}

Returns the Extended year (format symbol u).

NOTE: This current implementation always returns the year provided in the supplied date. This means u returns the same result as the format y.

SymbolExampleCldr Format
u+4601Minimim 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 format(date, format, locale \\ Cldr.get_current_locale(), options \\ []) View Source

Returns the formatted and localised date, time or datetime for a given Date, Time, DateTime or struct with the appropriate fields.

  • date is a Date, Time, DateTime or other struct that contains the required date and time fields.

  • format is a valid format string, for example yy/MM/dd hh:MM

  • locale is any locale returned by Cldr.known_locales/0

  • options is a keyword list of options. The valid options are:

    • :number_system. The resulting formatted and localised date/time string will be transliterated into this number system. Number system is anything returned from Cldr.Number.System.number_systems_for/1

NOTE This function is called by Cldr.Date/to_string/2, Cldr.Time.to_string/2 and Cldr.DateTime.to_string/2 which is the preferred API.

Examples

iex> Cldr.DateTime.Formatter.format %{year: 2017, month: 9, day: 3, hour: 10, minute: 23}, "yy/MM/dd hh:MM", "en"
{:ok, "17/09/03 10:09"}
Link to this function fractional_second(time, n \\ 1, locale \\ Cldr.get_current_locale(), options \\ []) View Source
fractional_second(Map.t, integer, Cldr.Locale.t, Keyword.t) ::
  binary |
  {:error, binary}

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.

  • time is a Time struct or any map that contains at least the key :second with and optional :microsecond key of the format used by Time

  • n is the number of fractional digits to which the float number of seconds is rounded

  • locale is any locale returned by Cldr.known_locales/0 which determines the localisation of the format

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

SymbolResultsDescription
S“4.0”Minimim 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 hour_0_11(time, n \\ 1, locale \\ Cldr.get_current_locale(), options \\ []) View Source
hour_0_11(Map.t, integer, Cldr.Locale.t, Keyword.t) ::
  binary |
  {:error, binary}

Returns the formatting of the :hour (format symbol K) as a number in the range 0..11 as a string.

  • time is a Time struct or any map that contains at least the key :second

  • n is the number of digits to which :hour is padded

  • locale is any locale returned by Cldr.known_locales/0 which determines the localisation of the format

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

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

SymbolMidn.MorningNoonAfternoonMidn.
K01…1101…110

Examples

iex> Cldr.DateTime.Formatter.hour_0_11 %{hour: 0}
"0"

iex> Cldr.DateTime.Formatter.hour_0_11 %{hour: 12}
"0"

iex> Cldr.DateTime.Formatter.hour_0_11 %{hour: 24}
"0"

iex> Cldr.DateTime.Formatter.hour_0_11 %{hour: 23}
"11"

iex> Cldr.DateTime.Formatter.hour_0_11 %{hour: 11}
"11"

iex> Cldr.DateTime.Formatter.hour_0_11 %{hour: 9}
"9"
Link to this function hour_0_23(time, n \\ 1, locale \\ Cldr.get_current_locale(), options \\ []) View Source
hour_0_23(Map.t, integer, Cldr.Locale.t, Keyword.t) ::
  binary |
  {:error, binary}

Returns the formatting of the :hour (format symbol H) as a number in the range 0..23 as a string.

  • time is a Time struct or any map that contains at least the key :second

  • n is the number of digits to which :hour is padded

  • locale is any locale returned by Cldr.known_locales/0 which determines the localisation of the format

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

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

SymbolMidn.MorningNoonAfternoonMidn.
H01…111213…230

Examples:

iex> Cldr.DateTime.Formatter.hour_0_23 %{hour: 10}
"10"

iex> Cldr.DateTime.Formatter.hour_0_23 %{hour: 13}
"13"

iex> Cldr.DateTime.Formatter.hour_0_23 %{hour: 21}
"21"

iex> Cldr.DateTime.Formatter.hour_0_23 %{hour: 24}
"0"

iex> Cldr.DateTime.Formatter.hour_0_23 %{hour: 0}
"0"
Link to this function hour_1_12(time, n \\ 1, locale \\ Cldr.get_current_locale(), options \\ []) View Source
hour_1_12(Map.t, integer, Cldr.Locale.t, Keyword.t) ::
  binary |
  {:error, binary}

Returns the formatting of the :hour (format symbol h) as a number in the range 1..12 as a string.

  • time is a Time struct or any map that contains at least the key :second

  • n is the number of digits to which :hour is padded

  • locale is any locale returned by Cldr.known_locales/0 which determines the localisation of the format

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

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

SymbolMidn.MorningNoonAfternoonMidn.
h121…11121…1112

Examples

iex> Cldr.DateTime.Formatter.hour_1_12 %{hour: 0}
"12"

iex> Cldr.DateTime.Formatter.hour_1_12 %{hour: 12}
"12"

iex> Cldr.DateTime.Formatter.hour_1_12 %{hour: 24}
"12"

iex> Cldr.DateTime.Formatter.hour_1_12 %{hour: 11}
"11"

iex> Cldr.DateTime.Formatter.hour_1_12 %{hour: 23}
"11"
Link to this function hour_1_24(time, n \\ 1, locale \\ Cldr.get_current_locale(), options \\ []) View Source
hour_1_24(Map.t, integer, Cldr.Locale.t, Keyword.t) ::
  binary |
  {:error, binary}

Returns the formatting of the :hour (format symbol k) as a number in the range 1..24 as a string.

  • time is a Time struct or any map that contains at least the key :second

  • n is the number of digits to which :hour is padded

  • locale is any locale returned by Cldr.known_locales/0 which determines the localisation of the format

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

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

SymbolMidn.MorningNoonAfternoonMidn.
k241…111213…2324

Examples

iex(4)> Cldr.DateTime.Formatter.hour_1_24 %{hour: 0}
"24"

iex(5)> Cldr.DateTime.Formatter.hour_1_24 %{hour: 12}
"12"

iex(6)> Cldr.DateTime.Formatter.hour_1_24 %{hour: 13}
"13"

iex(7)> Cldr.DateTime.Formatter.hour_1_24 %{hour: 9}
"9"

iex(8)> Cldr.DateTime.Formatter.hour_1_24 %{hour: 24}
"24"
Link to this function language_has_noon_and_midnight?(language) View Source
language_has_noon_and_midnight?(binary) :: boolean

Returns a boolean indicating is a given language defines the notion of “noon” and “midnight”

Examples

iex> Cldr.DateTime.Formatter.language_has_noon_and_midnight? "fr"
true

iex> Cldr.DateTime.Formatter.language_has_noon_and_midnight? "en"
true

iex> Cldr.DateTime.Formatter.language_has_noon_and_midnight? "af"
false
Link to this function literal(date, binary, locale \\ Cldr.get_current_locale(), options \\ []) View Source
literal(any, binary, Cldr.Locale.t, Keyword.t) ::
  binary |
  {:error, binary}

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 millisecond(time, n \\ 1, locale \\ Cldr.get_current_locale(), options \\ []) View Source
millisecond(Map.t, integer, Cldr.Locale.t, Keyword.t) ::
  binary |
  {:error, binary}

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

  • time is a Time struct or any map that contains at least the key :second with and optional :microsecond key of the format used by Time

  • n is the number of fractional digits to which the float number of seconds is rounded

  • locale is any locale returned by Cldr.known_locales/0 which determines the localisation of the format

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

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 minute(time, n \\ 1, locale \\ Cldr.get_current_locale(), options \\ []) View Source
minute(Map.t, non_neg_integer, Cldr.Locale.t, Keyword.t) ::
  binary |
  {:error, binary}

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.

  • time is a Time struct or any map that contains at least the key :minute

  • n is the number of digits to which :minute is padded

  • locale is any locale returned by Cldr.known_locales/0 which determines the localisation of the format

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

SymbolResultsDescription
m3, 10Minimim 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 month(date, n \\ 1, locale \\ Cldr.get_current_locale(), options \\ []) View Source
month(Map.t, integer, Cldr.Locale.t, Keyword.t) ::
  binary |
  {:error, binary}

Returns the month (format symbol M) of a date for given locale.

  • 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 month

  • locale is any locale returned by Cldr.known_locales/0 which determines the localisation of the format

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

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 %{month: 9, calendar: Calendar.ISO}
9

iex> Cldr.DateTime.Formatter.month %{month: 9, calendar: Calendar.ISO}, 2
"09"

iex> Cldr.DateTime.Formatter.month %{month: 9, calendar: Calendar.ISO}, 3
"Sep"

iex> Cldr.DateTime.Formatter.month %{month: 9, calendar: Calendar.ISO}, 4
"September"

iex> Cldr.DateTime.Formatter.month %{month: 9, calendar: Calendar.ISO}, 5
"S"
Link to this function period_am_pm(time, n \\ 1, locale \\ Cldr.get_current_locale(), options \\ []) View Source
period_am_pm(Map.t, integer, Cldr.Locale.t, Keyword.t) ::
  binary |
  {:error, binary}

Returns a localised version of am or pm (format symbol a).

  • 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 locale returned by Cldr.known_locales/0 which determines the localisation of the format

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

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.

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(15)> Cldr.DateTime.Formatter.period_am_pm %{hour: 0, minute: 0}
"AM"

iex(16)> Cldr.DateTime.Formatter.period_am_pm %{hour: 3, minute: 0}
"AM"

iex(17)> Cldr.DateTime.Formatter.period_am_pm %{hour: 13, minute: 0}
"PM"

iex(18)> Cldr.DateTime.Formatter.period_am_pm %{hour: 21, minute: 0}
"PM"
Link to this function period_flex(time, n \\ 1, locale \\ Cldr.get_current_locale(), options \\ []) View Source
period_flex(Map.t, integer, Cldr.Locale.t, Keyword.t) ::
  binary |
  {:error, binary}

Returns the formatting of the time period as a string, for example at night (format symbol B).

  • 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 locale returned by Cldr.known_locales/0 which determines the localisation of the format

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

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.

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_noon_midnight(time, n \\ 1, locale \\ Cldr.get_current_locale(), options \\ []) View Source
period_noon_midnight(Map.t, integer, Cldr.Locale.t, Keyword.t) ::
  binary |
  {:error, binary}

Returns the formatting of the time period as either noon, midnight or am/pm (format symbol ‘b’).

  • 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 locale returned by Cldr.known_locales/0 which determines the localisation of the format

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

If the langauge 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 the notion of a unique noon == 12:00, then the PM form may be substituted. Similarly for midnight == 00:00 and the AM form.

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}
"AM"

iex> Cldr.DateTime.Formatter.period_noon_midnight %{hour: 16, minute: 0}
"PM"
Link to this function quarter(date, n \\ 1, locale \\ Cldr.get_current_locale(), options \\ []) View Source
quarter(Map.t, integer, Cldr.Locale.t, Keyword.t) ::
  binary |
  {:error, binary}

Returns the quarter (format symbol Q) of a date for given locale.

  • 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 quarter

  • locale is any locale returned by Cldr.known_locales/0 which determines the localisation of the format

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

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 %{month: 4,
...> calendar: Calendar.ISO}, 1
2

iex> Cldr.DateTime.Formatter.quarter %{month: 4,
...> calendar: Calendar.ISO}, 2
"02"

iex> Cldr.DateTime.Formatter.quarter %{month: 4,
...> calendar: Calendar.ISO}, 3
"Q2"

iex> Cldr.DateTime.Formatter.quarter %{month: 4,
...> calendar: Calendar.ISO}, 4
"2nd quarter"

iex> Cldr.DateTime.Formatter.quarter %{month: 4,
...> calendar: Calendar.ISO}, 5
"2"
Link to this function second(time, n \\ 1, locale \\ Cldr.get_current_locale(), options \\ []) View Source
second(Map.t, integer, Cldr.Locale.t, Keyword.t) ::
  binary |
  {:error, binary}

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.

  • time is a Time struct or any map that contains at least the key :second

  • n is the number of digits to which :hour is padded

  • locale is any locale returned by Cldr.known_locales/0 which determines the localisation of the format

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

SymbolResultsDescription
s3, 48Minimim 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 standalone_day_of_week(date, n \\ 1, locale \\ Cldr.get_current_locale(), options \\ []) View Source
standalone_day_of_week(Map.t, integer, Cldr.Locale.t, Keyword.t) ::
  binary |
  {:error, binary}

Returns the stand-alone local day (format symbol c) of week number/name.

  • date is a Date 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 week

  • locale is any locale returned by Cldr.known_locales/0 which determines the localisation of the format

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

This is the same as weekday_number/4 except that it is intended for use without the associated d 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 %{year: 2017, month: 8,
...> day: 15, calendar: Calendar.ISO}, 3
"Tue"

iex> Cldr.DateTime.Formatter.standalone_day_of_week %{year: 2017, month: 8,
...> day: 15, calendar: Calendar.ISO}, 4
"Tuesday"

iex> Cldr.DateTime.Formatter.standalone_day_of_week %{year: 2017, month: 8,
...> day: 15, calendar: Calendar.ISO}, 5
"T"

iex> Cldr.DateTime.Formatter.standalone_day_of_week %{year: 2017, month: 8,
...> day: 15, calendar: Calendar.ISO}, 6
"Tu"
Link to this function standalone_month(date, n \\ 1, locale \\ Cldr.get_current_locale(), options \\ []) View Source
standalone_month(Map.t, integer, Cldr.Locale.t, Keyword.t) ::
  binary |
  {:error, binary}

Returns the month (symbol L) in standalone format which is intended to formatted without an accompanying day (d).

  • 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 month

  • locale is any locale returned by Cldr.known_locales/0 which determines the localisation of the format

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

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 %{month: 9, calendar: Calendar.ISO}
9

iex> Cldr.DateTime.Formatter.standalone_month %{month: 9, calendar: Calendar.ISO}, 2
"09"

iex> Cldr.DateTime.Formatter.standalone_month %{month: 9, calendar: Calendar.ISO}, 3
"Sep"

iex> Cldr.DateTime.Formatter.standalone_month %{month: 9, calendar: Calendar.ISO}, 4
"September"

iex> Cldr.DateTime.Formatter.standalone_month %{month: 9, calendar: Calendar.ISO}, 5
"S"
Link to this function standalone_quarter(date, n \\ 1, locale \\ Cldr.get_current_locale(), options \\ []) View Source
standalone_quarter(Map.t, integer, Cldr.Locale.t, Keyword.t) ::
  binary |
  {:error, binary}

Returns the standalone quarter (format symbol a) of a date for given locale.

  • 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 quarter

  • locale is any locale returned by Cldr.known_locales/0 which determines the localisation of the format

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

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(1)> Cldr.DateTime.Formatter.standalone_quarter %{month: 4,
...> calendar: Calendar.ISO}, 1
2

iex(2)> Cldr.DateTime.Formatter.standalone_quarter %{month: 4,
...> calendar: Calendar.ISO}, 2
"02"

iex(3)> Cldr.DateTime.Formatter.standalone_quarter %{month: 4,
...> calendar: Calendar.ISO}, 3
"Q2"

iex(4)> Cldr.DateTime.Formatter.standalone_quarter %{month: 4,
...> calendar: Calendar.ISO}, 4
"2nd quarter"

iex(5)> Cldr.DateTime.Formatter.standalone_quarter %{month: 4,
...> calendar: Calendar.ISO}, 5
"2"
Link to this function time(date, n \\ 1, locale \\ Cldr.get_current_locale(), options \\ []) View Source
time(Map.t, integer, Cldr.Locale.t, Keyword.t) ::
  binary |
  {:error, binary}

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_period_for(time, language) View Source
time_period_for(Map.t, binary) :: atom

Returns the time period for a given time of day.

The time period is a locale-specific key that is used to localise a time into a textual representation of “am”, “pm”, “noon”, “midnight”, “evening”, “morning” and so on as defined in the CLDR day period rules.

Examples

iex> Cldr.DateTime.Formatter.time_period_for ~T[06:05:54.515228], "en"
:morning1

iex> Cldr.DateTime.Formatter.time_period_for ~T[13:05:54.515228], "en"
:afternoon1

iex> Cldr.DateTime.Formatter.time_period_for ~T[21:05:54.515228], "en"
:night1

iex> Cldr.DateTime.Formatter.time_period_for ~T[21:05:54.515228], "fr"
:evening1
Link to this function type_from_calendar(calendar) View Source
Link to this function week_aligned_year(date, n \\ 1, locale \\ Cldr.get_current_locale(), options \\ []) View Source
week_aligned_year(Map.t, integer, Cldr.Locale.t, Keyword.t) ::
  binary |
  {:error, binary}

Returns the year (format symbol Y) in “Week of Year” based calendars in which the year transition occurs on a week boundary.

  • 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 locale returned by Cldr.known_locales/0 which determines the localisation of the format

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

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(12)> Cldr.DateTime.Formatter.week_aligned_year %{year: 2017, month: 1, day: 4,
...> calendar: Calendar.ISO}, 1
"2018"

iex(13)> Cldr.DateTime.Formatter.week_aligned_year %{year: 2017, month: 1, day: 4,
...> calendar: Calendar.ISO}, 2
"18"

iex(14)> Cldr.DateTime.Formatter.week_aligned_year %{year: 2017, month: 1, day: 4,
...> calendar: Calendar.ISO}, 3
"2018"

iex(15)> Cldr.DateTime.Formatter.week_aligned_year %{year: 2017, month: 1, day: 4,
...> calendar: Calendar.ISO}, 4
"2018"

iex(16)> Cldr.DateTime.Formatter.week_aligned_year %{year: 2017, month: 1, day: 4,
...> calendar: Calendar.ISO}, 5
"02018"
Link to this function week_of_month(date, n \\ 1, locale \\ Cldr.get_current_locale(), options \\ []) View Source
week_of_month(Map.t, integer, Cldr.Locale.t, Keyword.t) ::
  binary |
  {:error, binary}

Returns the week of the month (format symbol W) as an integer.

  • date is a Date struct or any map that contains at least the keys :year, :month, :day and :calendar

  • n in an integer between that should be 1

  • locale is any locale returned by Cldr.known_locales/0 which determines the localisation of the format

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

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

SymbolExampleCldr Format
W2

Examples

Link to this function week_of_year(date, n \\ 1, locale \\ Cldr.get_current_locale(), options \\ []) View Source
week_of_year(Map.t, integer, Cldr.Locale.t, Keyword.t) ::
  binary |
  {:error, binary}

Returns the week of the year (symbol w) as an integer.

  • date is a Date 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 year

  • locale is any locale returned by Cldr.known_locales/0 which determines the localisation of the format

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

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

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

SymbolExampleCldr Format
w2, 22
ww02, 22

Examples

Link to this function year(date, n \\ 1, locale \\ Cldr.get_current_locale(), options \\ []) View Source
year(Map.t, integer, Cldr.Locale.t, Keyword.t) ::
  binary |
  {:error, binary}

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.

  • 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 locale returned by Cldr.known_locales/0 which determines the localisation of the format

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

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 zone_basic(time, n \\ 1, locale \\ Cldr.get_current_locale(), options \\ []) View Source
zone_basic(Map.t, integer, Cldr.Locale.t, Keyword.t) ::
  binary |
  {:error, binary}

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.

  • time is a Time struct or any map that contains at least the :utc_offset and :std_offset keys of the format used by Time

  • n is the specific non-location timezone format and is in the range 1..4

  • locale is any locale returned by Cldr.known_locales/0 which determines the localisation of the format

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

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(79)> Cldr.DateTime.Formatter.zone_basic %{time_zone: "Etc/UTC", utc_offset: 3610, std_offset: 0}, 5
"+01:00:10"
Link to this function zone_generic(time, n \\ 1, locale \\ Cldr.get_current_locale(), options \\ []) View Source
zone_generic(Map.t, integer, Cldr.Locale.t, Keyword.t) ::
  binary |
  {:error, binary}
zone_generic(Map.t, integer, Cldr.Locale.t, Keyword.t) ::
  binary |
  {:error, binary}

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.

  • time is a Time struct or any map that contains at least the key :time_zone key of the format used by Time

  • n is the generic non-location timezone format and is either 1 (the default) or 4

  • locale is any locale returned by Cldr.known_locales/0 which determines the localisation of the format

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

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_gmt(time, n \\ 1, locale \\ Cldr.get_current_locale(), options \\ []) View Source

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

  • time is a Time struct or any map that contains at least the :utc_offset and :std_offset keys of the format used by Time

  • n is the specific non-location timezone format and is in the range 1..4

  • locale is any locale returned by Cldr.known_locales/0 which determines the localisation of the format

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

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_id(time, n \\ 1, locale \\ Cldr.get_current_locale(), options \\ []) View Source
zone_id(Map.t, integer, Cldr.Locale.t, Keyword.t) ::
  binary |
  {:error, binary}

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.

  • time is a Time struct or any map that contains at least the :utc_offset and :std_offset keys of the format used by Time

  • n is the specific non-location timezone format and is in the range 1..4

  • locale is any locale returned by Cldr.known_locales/0 which determines the localisation of the format

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

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 %{time_zone: "Etc/UTC", utc_offset: 0, std_offset: 0}, 1
"unk"

iex> Cldr.DateTime.Formatter.zone_id %{time_zone: "Etc/UTC", utc_offset: 0, std_offset: 0}, 2
"Etc/UTC"

iex> Cldr.DateTime.Formatter.zone_id %{time_zone: "Etc/UTC", utc_offset: 0, std_offset: 0}, 3
"Unknown City"

iex> Cldr.DateTime.Formatter.zone_id %{time_zone: "Etc/UTC", utc_offset: 0, std_offset: 0}, 4
"GMT"
Link to this function zone_iso(time, n \\ 1, locale \\ Cldr.get_current_locale(), options \\ []) View Source

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.

  • time is a Time struct or any map that contains at least the :utc_offset and :std_offset keys of the format used by Time

  • n is the specific non-location timezone format and is in the range 1..4

  • locale is any locale returned by Cldr.known_locales/0 which determines the localisation of the format

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

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_z(time, n \\ 1, locale \\ Cldr.get_current_locale(), options \\ []) View Source
zone_iso_z(Map.t, integer, Cldr.Locale.t, Keyword.t) ::
  binary |
  {:error, binary}
zone_iso_z(Map.t, integer, Cldr.Locale.t, Keyword.t) ::
  binary |
  {:error, binary}

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.

  • time is a Time struct or any map that contains at least the :utc_offset and :std_offset keys of the format used by Time

  • n is the specific non-location timezone format and is in the range 1..4

  • locale is any locale returned by Cldr.known_locales/0 which determines the localisation of the format

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

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_short(time, n \\ 1, locale \\ Cldr.get_current_locale(), options \\ []) View Source

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.

  • time is a Time struct or any map that contains at least the :zone_abbr, :utc_offset and :std_offset keys of the format used by Time

  • n is the specific non-location timezone format and is in the range 1..4

  • locale is any locale returned by Cldr.known_locales/0 which determines the localisation of the format

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

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"