@spec cyclic_year(Calendar.date(), 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

Calendars such as the Chinese lunar calendar (and related calendars) and the Hindu calendars use 60-year cycles of year names. If the calendar does not provide cyclic year name data, or if the year value to be formatted is out of the range of years for which cyclic name data is provided, then numeric formatting is used (behaves like format symbol y).

Currently the CLDR data only provides abbreviated names, which will be used for all requested name widths.

@spec date(Calendar.date(), integer(), Keyword.t()) ::
  String.t() | {:error, String.t()}

Returns a formatted date.

DateTime formats are defined in CLDR using substitution rules whereby the Date and/or Time are substituted into a format string. Therefore this function crafts a date format string which is then inserted into the overall format being requested.

@spec day_name(Calendar.date(), integer(), Keyword.t()) ::
  String.t() | {:error, String.t()}

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

Arguments

• 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 valid locale name returned by Cldr.known_locale_names/0 or a Cldr.LanguageTag struct. The default is Cldr.get_locale/0

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

Format Symbol

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

Examples

iex> Cldr.DateTime.Formatter.day_name ~D[2017-08-15], 6
"Tu"

iex> Cldr.DateTime.Formatter.day_name ~D[2017-08-15], 5
"T"

iex> Cldr.DateTime.Formatter.day_name ~D[2017-08-15], 4
"Tuesday"

iex> Cldr.DateTime.Formatter.day_name ~D[2017-08-15], 3
"Tue"

iex> Cldr.DateTime.Formatter.day_name ~D[2017-08-15], 2
"Tue"

iex> Cldr.DateTime.Formatter.day_name ~D[2017-08-15], 1
"Tue"

@spec day_of_month(Calendar.date(), integer(), Keyword.t()) ::
  String.t() | {:error, String.t()}

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

Arguments

• 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 valid locale name returned by Cldr.known_locale_names/0 or a Cldr.LanguageTag struct. The default is Cldr.get_locale/0

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

Format Symbol

The representation of the day of the month is made in accordance with the following table. Note that ddd is not part of the CLDR standard.

Examples

iex> Cldr.DateTime.Formatter.day_of_month ~D[2017-01-04], 1
4

iex> Cldr.DateTime.Formatter.day_of_month ~D[2017-01-04], 2
"04"

iex> Cldr.DateTime.Formatter.day_of_month ~D[2017-01-04], 3
"4th"

@spec day_of_week(Calendar.date(), integer(), Keyword.t()) ::
  String.t() | {:error, String.t()}

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

Arguments

• date is 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 valid locale name returned by Cldr.known_locale_names/0 or a Cldr.LanguageTag struct. The default is Cldr.get_locale/0

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

Notes

Returns the same as format symbol E except that it adds a numeric value that will depend on the local starting day of the week.

Format Symbol

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

Examples

iex> Cldr.DateTime.Formatter.day_of_week ~D[2017-08-15], 3
"Tue"

iex> Cldr.DateTime.Formatter.day_of_week ~D[2017-08-15], 4
"Tuesday"

iex> Cldr.DateTime.Formatter.day_of_week ~D[2017-08-15], 5
"T"

iex> Cldr.DateTime.Formatter.day_of_week ~D[2017-08-15], 6
"Tu"

iex> Cldr.DateTime.Formatter.day_of_week ~D[2017-08-15], 1
"2"

iex> Cldr.DateTime.Formatter.day_of_week ~D[2017-08-15], 2
"02"

@spec day_of_year(Calendar.date(), integer(), Keyword.t()) ::
  String.t() | {:error, String.t()}

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

Arguments

• date is 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 valid locale name returned by Cldr.known_locale_names/0 or a Cldr.LanguageTag struct. The default is Cldr.get_locale/0

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

Format Symbol

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

Examples

iex> Cldr.DateTime.Formatter.day_of_year ~D[2017-01-15], 1
"15"

iex> Cldr.DateTime.Formatter.day_of_year ~D[2017-01-15], 2
"15"

iex> Cldr.DateTime.Formatter.day_of_year ~D[2017-01-15], 3
"015"

@spec era(Calendar.date(), 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 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:

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"

@spec extended_year(Calendar.date(), 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 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

This is a single number designating the year of this calendar system, encompassing all supra-year fields.

For example, for the Julian calendar system, year numbers are positive, with an era of BCE or CE. An extended year value for the Julian calendar system assigns positive values to CE years and negative values to BCE years, with 1 BCE being year 0.

For u, all field lengths specify a minimum number of digits; there is no special interpretation for uu.

@spec fractional_second(Calendar.time(), integer(), Keyword.t()) ::
  String.t() | {:error, String.t()}

Returns the :second of a time or datetime (format symbol S) as float in string format. The seconds are calculate to include microseconds if they are available. The number of S's in the format determines the formatting.

Arguments

• time is 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 valid locale name returned by Cldr.known_locale_names/0 or a Cldr.LanguageTag struct. The default is Cldr.get_locale/0

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

Format Symbol

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

Examples

iex> Cldr.DateTime.Formatter.fractional_second %{second: 4, microsecond: {2000, 3}}, 1
"4.0"

iex> Cldr.DateTime.Formatter.fractional_second %{second: 4, microsecond: {2000, 3}}, 3
"4.002"

iex> Cldr.DateTime.Formatter.fractional_second %{second: 4}, 1
"4"

@spec h11(Calendar.time(), integer(), Keyword.t()) ::
  String.t() | {:error, String.t()}

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

Arguments

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

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

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

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

Format Symbol

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

Examples

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

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

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

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

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

iex> Cldr.DateTime.Formatter.h11 %{hour: 9}
"9"

@spec h12(Calendar.time(), integer(), Keyword.t()) ::
  String.t() | {:error, String.t()}

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

Arguments

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

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

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

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

Format Symbol

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

Examples

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

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

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

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

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

@spec h23(Calendar.time(), integer(), Keyword.t()) ::
  String.t() | {:error, String.t()}

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

Arguments

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

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

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

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

Format Symbol

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

Examples:

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

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

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

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

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

@spec h24(Calendar.time(), integer(), Keyword.t()) ::
  String.t() | {:error, String.t()}

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

Arguments

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

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

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

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

Format Symbol

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

Examples

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

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

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

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

iex(8)> Cldr.DateTime.Formatter.h24 %{hour: 24}
"24"

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

Returns the hour formatted in a locale-specific format

Arguments

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

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

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

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

Examples

iex> Cldr.DateTime.Formatter.hour ~N[2020-04-25 15:00:00.0]
"3"

iex> Cldr.DateTime.Formatter.hour ~N[2020-04-25 15:00:00.0], locale: "fr"
"15"

iex> Cldr.DateTime.Formatter.hour ~N[2020-04-25 15:00:00.0], locale: "en-AU"
"3"

iex> Cldr.DateTime.Formatter.hour ~N[2020-04-25 15:00:00.0], locale: "en-AU-u-hc-h23"
"15"

@spec 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"

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

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

Arguments

• 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 valid locale name returned by Cldr.known_locale_names/0 or a Cldr.LanguageTag struct. The default is Cldr.get_locale/0

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

Format Symbol

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

Examples

iex> Cldr.DateTime.Formatter.millisecond %{hour: 0, minute: 0,
...>   second: 4, microsecond: {2000, 3}}, 1
"4002"

iex> Cldr.DateTime.Formatter.millisecond %{hour: 0, minute: 0, second: 4}, 1
"4000"

iex> Cldr.DateTime.Formatter.millisecond %{hour: 10, minute: 10, second: 4}, 1
"36604000"

iex> Cldr.DateTime.Formatter.millisecond ~T[07:35:13.215217]
"27313215"

@spec minute(Calendar.time(), integer(), Keyword.t()) ::
  String.t() | {:error, String.t()}

Returns the :minute of a time or datetime (format symbol m) as number in string format. The number of m's in the format determines the formatting.

Arguments

• time is 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 valid locale name returned by Cldr.known_locale_names/0 or a Cldr.LanguageTag struct. The default is Cldr.get_locale/0

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

Format Symbol

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

Examples

iex> Cldr.DateTime.Formatter.minute %{minute: 3}, 1
3

iex> Cldr.DateTime.Formatter.minute %{minute: 3}, 2
"03"

@spec month(Calendar.date(), integer(), Keyword.t()) ::
  String.t() | {:error, String.t()}

Returns the month (format symbol M) 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 month

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

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

Format Symbol

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

Examples

iex> Cldr.DateTime.Formatter.month ~D[2019-09-08]
"9"

iex> Cldr.DateTime.Formatter.month ~D[2019-09-08], 2
"09"

iex> Cldr.DateTime.Formatter.month ~D[2019-09-08], 3
"Sep"

iex> Cldr.DateTime.Formatter.month ~D[2019-09-08], 4
"September"

iex> Cldr.DateTime.Formatter.month ~D[2019-09-08], 5
"S"

@spec period_am_pm(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 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:

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

@spec period_flex(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 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:

Examples

iex> Cldr.DateTime.Formatter.period_flex %{hour: 11, minute: 5, second: 23}
"in the morning"

iex> Cldr.DateTime.Formatter.period_flex %{hour: 16, minute: 5, second: 23}
"in the afternoon"

iex> Cldr.DateTime.Formatter.period_flex %{hour: 23, minute: 5, second: 23}
"at night"

@spec period_noon_midnight(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 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:

Examples

iex> Cldr.DateTime.Formatter.period_noon_midnight %{hour: 12, minute: 0}
"noon"

iex> Cldr.DateTime.Formatter.period_noon_midnight %{hour: 0, minute: 0}
"midnight"

iex> Cldr.DateTime.Formatter.period_noon_midnight %{hour: 11, minute: 0}
"in the morning"

iex> Cldr.DateTime.Formatter.period_noon_midnight %{hour: 16, minute: 0}
"PM"

@spec quarter(Calendar.date(), integer(), Keyword.t()) ::
  String.t() | {:error, String.t()}

Returns the quarter (format symbol Q) 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 quarter

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

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

Format Symbol

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

Examples

iex> Cldr.DateTime.Formatter.quarter ~D[2017-04-01], 1
2

iex> Cldr.DateTime.Formatter.quarter ~D[2017-04-01], 2
"02"

iex> Cldr.DateTime.Formatter.quarter ~D[2017-04-01], 3
"Q2"

iex> Cldr.DateTime.Formatter.quarter ~D[2017-04-01], 4
"2nd quarter"

iex> Cldr.DateTime.Formatter.quarter ~D[2017-04-01], 5
"2"

@spec related_year(Calendar.date(), integer(), Keyword.t()) ::
  String.t() | {:error, String.t()}

Returns the related gregorian year (format symbol r) 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 quarter

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

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

Format Symbol

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

This corresponds to the extended Gregorian year in which the calendar’s year begins. Related Gregorian years are often displayed, for example, when formatting dates in the Japanese calendar — e.g. “2012(平成24)年1月15日” — or in the Chinese calendar — e.g. “2012壬辰年腊月初四”. The related Gregorian year is usually displayed using the ":latn" numbering system, regardless of what numbering systems may be used for other parts of the formatted date.

If the calendar’s year is linked to the solar year (perhaps using leap months), then for that calendar the ‘r’ year will always be at a fixed offset from the ‘u’ year.

For the Gregorian calendar, the ‘r’ year is the same as the ‘u’ year. For ‘r’, all field lengths specify a minimum number of digits; there is no special interpretation for “rr”.

@spec second(Calendar.time(), integer(), Keyword.t()) ::
  String.t() | {:error, String.t()}

Returns the :second of a time or datetime (format symbol s) as number in string format. The number of s's in the format determines the formatting.

Arguments

• time is 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 valid locale name returned by Cldr.known_locale_names/0 or a Cldr.LanguageTag struct. The default is Cldr.get_locale/0

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

Format Symbol

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

Examples

iex> Cldr.DateTime.Formatter.second %{second: 23}, 1
"23"

iex> Cldr.DateTime.Formatter.second %{second: 4}, 2
"04"

@spec standalone_day_of_week(Calendar.date(), integer(), Keyword.t()) ::
  String.t() | {:error, String.t()}

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

Arguments

• 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 valid locale name returned by Cldr.known_locale_names/0 or a Cldr.LanguageTag struct. The default is Cldr.get_locale/0

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

Notes

This is the same as weekday_number/4 except that it is intended for use without the associated d format symbol.

Format Symbol

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

Examples

iex> Cldr.DateTime.Formatter.standalone_day_of_week ~D[2017-08-15], 3
"Tue"

iex> Cldr.DateTime.Formatter.standalone_day_of_week ~D[2017-08-15], 4
"Tuesday"

iex> Cldr.DateTime.Formatter.standalone_day_of_week ~D[2017-08-15], 5
"T"

iex> Cldr.DateTime.Formatter.standalone_day_of_week ~D[2017-08-15], 6
"Tu"

@spec standalone_month(Calendar.date(), integer(), Keyword.t()) ::
  String.t() | {:error, String.t()}

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

Arguments

• date is 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 valid locale name returned by Cldr.known_locale_names/0 or a Cldr.LanguageTag struct. The default is Cldr.get_locale/0

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

Format Symbol

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

Examples

iex> Cldr.DateTime.Formatter.standalone_month ~D[2019-09-08]
"9"

iex> Cldr.DateTime.Formatter.standalone_month ~D[2019-09-08], 2
"09"

iex> Cldr.DateTime.Formatter.standalone_month ~D[2019-09-08], 3
"Sep"

iex> Cldr.DateTime.Formatter.standalone_month ~D[2019-09-08], 4
"September"

iex> Cldr.DateTime.Formatter.standalone_month ~D[2019-09-08], 5
"S"

@spec standalone_quarter(Calendar.date(), integer(), Keyword.t()) ::
  String.t() | {:error, String.t()}

Returns the standalone quarter (format symbol a) 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 quarter

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

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

Format Symbol

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

Examples

iex> Cldr.DateTime.Formatter.standalone_quarter ~D[2019-06-08], 1
2

iex> Cldr.DateTime.Formatter.standalone_quarter ~D[2019-06-08], 2
"02"

iex> Cldr.DateTime.Formatter.standalone_quarter ~D[2019-06-08], 3
"Q2"

iex> Cldr.DateTime.Formatter.standalone_quarter ~D[2019-06-08], 4
"2nd quarter"

iex> Cldr.DateTime.Formatter.standalone_quarter ~D[2019-06-08], 5
"2"

@spec time(Calendar.time(), integer(), Keyword.t()) ::
  String.t() | {:error, {module(), String.t()}}

Returns a formatted time.

DateTime formats are defined in CLDR using substitution rules whereby the Date and/or Time are substituted into a format string. Therefore this function crafts a time format string which is then inserted into the overall format being requested.

@spec week_aligned_year(Calendar.date(), 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 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:

The result may differ from calendar year ‘y’ near a year transition. This numeric year designation is used in conjunction with pattern character ‘w’ in the ISO year-week calendar as defined by ISO 8601, but can be used in non-Gregorian based calendar systems where week date processing is desired.

The field length is interpreted in the same was as for y; that is, yy specifies use of the two low-order year digits, while any other field length specifies a minimum number of digits to display.

Examples

iex> Cldr.DateTime.Formatter.week_aligned_year ~D[2017-01-04], 1
"2017"

iex> Cldr.DateTime.Formatter.week_aligned_year ~D[2017-01-04], 2
"17"

iex> Cldr.DateTime.Formatter.week_aligned_year ~D[2017-01-04], 3
"2017"

iex> Cldr.DateTime.Formatter.week_aligned_year ~D[2017-01-04], 4
"2017"

iex> Cldr.DateTime.Formatter.week_aligned_year ~D[2017-01-04], 5
"02017"

@spec week_of_month(Calendar.date(), integer(), Keyword.t()) ::
  String.t() | {:error, String.t()}

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

Arguments

• 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 between 1 and 4 that determines the format of the week of the month

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

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

Format Symbol

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

Examples

iex> import Cldr.Calendar.Sigils
Cldr.Calendar.Sigils
iex> Cldr.DateTime.Formatter.week_of_month ~D[2019-01-07], 1
"2"
iex> Cldr.DateTime.Formatter.week_of_month ~d[2019-W04-1], 1
"4"

@spec week_of_year(Calendar.date(), integer(), Keyword.t()) ::
  String.t() | {:error, String.t()}

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

Arguments

• 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 valid locale name returned by Cldr.known_locale_names/0 or a Cldr.LanguageTag struct. The default is Cldr.get_locale/0

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

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:

Examples

iex> import Cldr.Calendar.Sigils
Cldr.Calendar.Sigils
iex> Cldr.DateTime.Formatter.week_of_year ~D[2019-01-07], 1
"2"
iex> Cldr.DateTime.Formatter.week_of_year ~d[2019-W04-1], 2
"04"

@spec year(Calendar.date(), integer(), Keyword.t()) ::
  String.t() | {:error, String.t()}

Returns the year (format symbol y) of a date as an integer. The y format returns the year as a simple integer in string format.

The format yy is a special case which requests just the two low-order digits of the year, zero-padded as necessary. For most use cases, y or yy should be adequate.

Arguments

• date is 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 struct. The default is Cldr.get_locale/0

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

Format Symbol

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

In most cases the length of the y field specifies the minimum number of digits to display, zero-padded as necessary; more digits will be displayed if needed to show the full year.

Examples

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

iex> Cldr.DateTime.Formatter.year %{year: 2017, calendar: Calendar.ISO}, 2
"17"

iex> Cldr.DateTime.Formatter.year %{year: 2017, calendar: Calendar.ISO}, 3
"2017"

iex> Cldr.DateTime.Formatter.year %{year: 2017, calendar: Calendar.ISO}, 4
"2017"

iex> Cldr.DateTime.Formatter.year %{year: 2017, calendar: Calendar.ISO}, 5
"02017"

@spec zone_basic(Calendar.time(), integer(), Keyword.t()) ::
  String.t() | {:error, String.t()}

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

The ISO8601 basic format with hours, minutes and optional seconds fields. The format is equivalent to RFC 822 zone format (when optional seconds field is absent). This is equivalent to the "xxxx" specifier.

Arguments

• time is 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 valid locale name returned by Cldr.known_locale_names/0 or a Cldr.LanguageTag struct. The default is Cldr.get_locale/0

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

Format Symbol

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

Examples

iex> Cldr.DateTime.Formatter.zone_basic %{time_zone: "Etc/UTC",
...>   utc_offset: 3600, std_offset: 0}, 1
"+0100"

iex> Cldr.DateTime.Formatter.zone_basic %{time_zone: "Etc/UTC",
...>   utc_offset: 3610, std_offset: 0}, 4
"GMT+01:00"

iex> Cldr.DateTime.Formatter.zone_basic %{time_zone: "Etc/UTC",
...>   utc_offset: 0, std_offset: 0}, 5
"Z"

iex> Cldr.DateTime.Formatter.zone_basic %{time_zone: "Etc/UTC",
...>   utc_offset: 3610, std_offset: 0}, 5
"+01:00:10"

@spec zone_generic(Calendar.time(), integer(), Keyword.t()) ::
  String.t() | {:error, String.t()}

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

Since Elixir does not provide full time zone support, we return here only the :time_zone element of the provided DateTime or other struct without any localization.

Arguments

• time is 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 valid locale name returned by Cldr.known_locale_names/0 or a Cldr.LanguageTag struct. The default is Cldr.get_locale/0

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

Format Symbol

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

Examples

iex> Cldr.DateTime.Formatter.zone_generic %{time_zone: "Etc/UTC",
...>   utc_offset: 0, std_offset: 0}, 4
"GMT"

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

@spec zone_gmt(Calendar.time(), integer(), Keyword.t()) ::
  String.t() | {:error, String.t()}

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

Arguments

• time is 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 valid locale name returned by Cldr.known_locale_names/0 or a Cldr.LanguageTag struct. The default is Cldr.get_locale/0

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

Format Symbol

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

Examples

iex> Cldr.DateTime.Formatter.zone_gmt %{time_zone: "Etc/UTC",
...>   utc_offset: 3610, std_offset: 0}, 1
"GMT+1"

iex> Cldr.DateTime.Formatter.zone_gmt %{time_zone: "Etc/UTC",
...>   utc_offset: 3610, std_offset: 0}, 4
"GMT+01:00"

@spec zone_id(Calendar.time(), integer(), Keyword.t()) ::
  String.t() | {:error, String.t()}

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

For now the short timezone name, exemplar city and generic location formats are not supported and therefore return the fallbacks defined in CLDR.

Arguments

• time is 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 valid locale name returned by Cldr.known_locale_names/0 or a Cldr.LanguageTag struct. The default is Cldr.get_locale/0

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

Format Symbol

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

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"

@spec zone_iso(Calendar.time(), integer(), Keyword.t()) ::
  String.t() | {:error, String.t()}

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

This is the ISO8601 format with hours, minutes and optional seconds fields but with no "Z" as the identifier if the timezone offset is 0.

Arguments

• time is 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 valid locale name returned by Cldr.known_locale_names/0 or a Cldr.LanguageTag struct. The default is Cldr.get_locale/0

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

Format Symbol

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

Examples

iex> Cldr.DateTime.Formatter.zone_iso %{time_zone: "Etc/UTC",
...>   utc_offset: 3610, std_offset: 0}, 1
"+01"

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

iex> Cldr.DateTime.Formatter.zone_iso %{time_zone: "Etc/UTC",
...>   utc_offset: 3610, std_offset: 0}, 3
"+01:00"

iex> Cldr.DateTime.Formatter.zone_iso %{time_zone: "Etc/UTC",
...>   utc_offset: 3610, std_offset: 0}, 4
"+010010"

iex> Cldr.DateTime.Formatter.zone_iso %{time_zone: "Etc/UTC",
...>   utc_offset: 3610, std_offset: 0}, 5
"+01:00:10"

iex> Cldr.DateTime.Formatter.zone_iso %{time_zone: "Etc/UTC",
...>   utc_offset: 0, std_offset: 0}, 5
"+00:00"

iex> Cldr.DateTime.Formatter.zone_iso %{time_zone: "Etc/UTC",
...>   utc_offset: 0, std_offset: 0}, 4
"+0000"

iex> Cldr.DateTime.Formatter.zone_iso %{time_zone: "Etc/UTC",
...>   utc_offset: 0, std_offset: 0}, 3
"+00:00"

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

iex> Cldr.DateTime.Formatter.zone_iso %{time_zone: "Etc/UTC",
...>   utc_offset: 0, std_offset: 0}, 1
"+00"

@spec zone_iso_z(Calendar.time(), integer(), Keyword.t()) ::
  String.t() | {:error, String.t()}

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

This is the ISO8601 format with hours, minutes and optional seconds fields with "Z" as the identifier if the timezone offset is 0.

Arguments

• time is 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 valid locale name returned by Cldr.known_locale_names/0 or a Cldr.LanguageTag struct. The default is Cldr.get_locale/0

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

Format Symbol

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

Examples

iex> Cldr.DateTime.Formatter.zone_iso_z %{time_zone: "Etc/UTC",
...>   utc_offset: 3610, std_offset: 0}, 1
"+01"

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

iex> Cldr.DateTime.Formatter.zone_iso_z %{time_zone: "Etc/UTC",
...>   utc_offset: 3610, std_offset: 0}, 3
"+01:00:10"

iex> Cldr.DateTime.Formatter.zone_iso_z %{time_zone: "Etc/UTC",
...>   utc_offset: 3610, std_offset: 0}, 4
"+010010"

iex> Cldr.DateTime.Formatter.zone_iso_z %{time_zone: "Etc/UTC",
...>   utc_offset: 3610, std_offset: 0}, 5
"+01:00:10"

iex> Cldr.DateTime.Formatter.zone_iso_z %{time_zone: "Etc/UTC",
...>   utc_offset: 0, std_offset: 0}, 5
"Z"

iex> Cldr.DateTime.Formatter.zone_iso_z %{time_zone: "Etc/UTC",
...>   utc_offset: 0, std_offset: 0}, 4
"Z"

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

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

@spec zone_short(Calendar.time(), integer(), Keyword.t()) ::
  String.t() | {:error, String.t()}

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

Since Elixir does not provide full time zone support, we return here only the :time_zone element of the provided DateTime or other struct without any localization.

Arguments

• time is 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 valid locale name returned by Cldr.known_locale_names/0 or a Cldr.LanguageTag struct. The default is Cldr.get_locale/0

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

Format Symbol

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

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"