# `Cldr.DateTime.Formatter`
[🔗](https://github.com/elixir-cldr/cldr_dates_times/blob/v2.25.6/lib/cldr/format/date_time_formatter.ex#L1)

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](http://unicode.org/reports/tr35/tr35-dates.html#Date_Field_Symbol_Table)
defines a wide range of format symbols.  Most - but not
all - of these symbols are supported in `Cldr`.  The supported
symbols are described below.

### Format Symbol Table

| Element                | Symbol     | Example         | Cldr Format                        |
| :--------------------  | :--------  | :-------------- | :--------------------------------- |
| Era                    | G, GG, GGG | "AD"            | Abbreviated                        |
|                        | GGGG       | "Anno Domini"   | Wide                               |
|                        | GGGGG      | "A"             | Narrow                             |
| Year                   | y          | 7               | Minimum necessary digits           |
|                        | yy         | "17"            | Least significant 2 digits         |
|                        | yyy        | "017", "2017"   | Padded to at least 3 digits        |
|                        | yyyy       | "2017"          | Padded to at least 4 digits        |
|                        | yyyyy      | "02017"         | Padded to at least 5 digits        |
| ISOWeek Year           | Y          | 7               | Minimum necessary digits           |
|                        | YY         | "17"            | Least significant 2 digits         |
|                        | YYY        | "017", "2017"   | Padded to at least 3 digits        |
|                        | YYYY       | "2017"          | Padded to at least 4 digits        |
|                        | YYYYY      | "02017"         | Padded to at least 5 digits        |
| Related Gregorian Year | r, rr, rr+ | 2017            | Minimum necessary digits           |
| Cyclic Year            | U, UU, UUU | "甲子"           | Abbreviated                        |
|                        | UUUU       | "甲子" (for now) | Wide                               |
|                        | UUUUU      | "甲子" (for now) | Narrow                             |
| Extended Year          | u+         | 4601            | Minimum necessary digits           |
| Quarter                | Q          | 2               | Single digit                       |
|                        | QQ         | "02"            | Two digits                         |
|                        | QQQ        | "Q2"            | Abbreviated                        |
|                        | QQQQ       | "2nd quarter"   | Wide                               |
|                        | QQQQQ      | "2"             | Narrow                             |
| Standalone Quarter     | q          | 2               | Single digit                       |
|                        | qq         | "02"            | Two digits                         |
|                        | qqq        | "Q2"            | Abbreviated                        |
|                        | qqqq       | "2nd quarter"   | Wide                               |
|                        | qqqqq      | "2"             | Narrow                             |
| Month                  | M          | 9               | Single digit                       |
|                        | MM         | "09"            | Two digits                         |
|                        | MMM        | "Sep"           | Abbreviated                        |
|                        | MMMM       | "September"     | Wide                               |
|                        | MMMMM      | "S"             | Narrow                             |
| Standalone Month       | L          | 9               | Single digit                       |
|                        | LL         | "09"            | Two digits                         |
|                        | LLL        | "Sep"           | Abbreviated                        |
|                        | LLLL       | "September"     | Wide                               |
|                        | LLLLL      | "S"             | Narrow                             |
| Week of Year           | w          | 2, 22           | Single digit                       |
|                        | ww         | 02, 22          | Two digits, zero padded            |
| Week of Month          | W          | 2               | Single digit                       |
| Day of Year            | D          | 3, 33, 333      | Minimum necessary digits           |
|                        | DD         | 03, 33, 333     | Minimum of 2 digits, zero padded   |
|                        | DDD        | 003, 033, 333   | Minimum of 3 digits, zero padded   |
| Day of Month           | d          | 2, 22           | Minimum necessary digits           |
|                        | dd         | 02, 22          | Two digits, zero padded            |
|                        | ddd        | 2nd, 25th       | Ordinal day of month               |
| Day of Week            | E, EE, EEE | "Tue"           | Abbreviated                        |
|                        | EEEE       | "Tuesday"       | Wide                               |
|                        | EEEEE      | "T"             | Narrow                             |
|                        | EEEEEE     | "Tu"            | Short                              |
|                        | e          | 2               | Single digit                       |
|                        | ee         | "02"            | Two digits                         |
|                        | eee        | "Tue"           | Abbreviated                        |
|                        | eeee       | "Tuesday"       | Wide                               |
|                        | eeeee      | "T"             | Narrow                             |
|                        | eeeeee     | "Tu"            | Short                              |
| Standalone Day of Week | c, cc      | 2               | Single digit                       |
|                        | ccc        | "Tue"           | Abbreviated                        |
|                        | cccc       | "Tuesday"       | Wide                               |
|                        | ccccc      | "T"             | Narrow                             |
|                        | cccccc     | "Tu"            | Short                              |
| AM or PM               | a, aa, aaa | "am."           | Abbreviated                        |
|                        | aaaa       | "am."           | Wide                               |
|                        | aaaaa      | "am"            | Narrow                             |
| Noon, Mid, AM, PM      | b, bb, bbb | "mid."          | Abbreviated                        |
|                        | bbbb       | "midnight"      | Wide                               |
|                        | bbbbb      | "md"            | Narrow                             |
| Flexible time period   | B, BB, BBB | "at night"      | Abbreviated                        |
|                        | BBBB       | "at night"      | Wide                               |
|                        | BBBBB      | "at night"      | Narrow                             |
| Hour                   | h, K, H, k |                 | See the table below                |
| Minute                 | m          | 3, 10           | Minimum digits of minutes          |
|                        | mm         | "03", "12"      | Two digits, zero padded            |
| Second                 | s          | 3, 48           | Minimum digits of seconds          |
|                        | ss         | "03", "48"      | Two digits, zero padded            |
| Fractional Seconds     | S          | 3, 48           | Minimum digits of fractional seconds |
|                        | SS         | "03", "48"      | Two digits, zero padded            |
| Milliseconds            | A+         | 4000, 63241     | Minimum digits of milliseconds since midnight |
| Generic non-location TZ | v         | "Etc/UTC"       | `:time_zone` key, unlocalised      |
|                         | vvvv      | "unk"           | Generic timezone name.  Currently returns only "unk" |
| Specific non-location TZ | z..zzz   | "UTC"           | `:zone_abbr` key, unlocalised      |
|                         | zzzz      | "GMT"           | Delegates to `zone_gmt/4`          |
| Timezone ID             | V         | "unk"           | `:zone_abbr` key, unlocalised      |
|                         | VV        | "Etc/UTC        | Delegates to `zone_gmt/4`          |
|                         | VVV       | "Unknown Location" | Exemplar city.  Not supported.     |
|                         | VVVV      | "GMT"           | Delegates to `zone_gmt/4`          |
| ISO8601 Format          | Z..ZZZ    | "+0100"         | ISO8601 Basic Format with hours and minutes |
|                         | ZZZZ      | "+01:00"        | Delegates to `zone_gmt/4`          |
|                         | ZZZZZ     | "+01:00:10"     | ISO8601 Extended format with optional seconds |
| ISO8601 plus Z          | X         | "+01"           | ISO8601 Basic Format with hours and optional minutes or "Z" |
|                         | XX        | "+0100"         | ISO8601 Basic Format with hours and minutes or "Z"          |
|                         | XXX       | "+0100"         | ISO8601 Basic Format with hours and minutes, optional seconds or "Z" |
|                         | XXXX      | "+010059"       | ISO8601 Basic Format with hours and minutes, optional seconds or "Z" |
|                         | XXXXX     | "+01:00:10"     | ISO8601 Extended Format with hours and minutes, optional seconds or "Z" |
| ISO8601 minus Z         | x         | "+0100"         | ISO8601 Basic Format with hours and optional minutes |
|                         | xx        | "-0800"         | ISO8601 Basic Format with hours and minutes          |
|                         | xxx       | "+01:00"        | ISO8601 Extended Format with hours and minutes       |
|                         | xxxx      | "+010059"       | ISO8601 Basic Format with hours and minutes, optional seconds     |
|                         | xxxxx     | "+01:00:10"     | ISO8601 Extended Format with hours and minutes, optional seconds  |
| GMT Format              | O         | "+0100"         | Short localised GMT format        |
|                         | OOOO      | "+010059"       | Long localised GMT format         |

### Formatting symbols for hour of day

The hour of day can be formatted differently depending whether
a 12- or 24-hour day is being represented and depending on the
way in which midnight and noon are represented.  The following
table illustrates the differences:

| Symbol  | Midn.	|	Morning	| Noon |	Afternoon	| Midn. |
| :----:  | :---: | :-----: | :--: | :--------: | :---: |
|   h	    |  12	  | 1...11	|  12	 |   1...11   |  12   |
|   K	    |   0	  | 1...11	|   0	 |   1...11   |   0   |
|   H	    |   0	  | 1...11	|  12	 |  13...23   |   0   |
|   k	    |  24	  | 1...11	|  12	 |  13...23   |  24   |

### Fractional Seconds

The fractional seconds formatting code (`S`) formats *only*
the fraction of a second as represented by the `t:Time.t/0`
type which is a tuple of the form `{microseconds, precision}`.

If used standalone, `S` will be formatted as only the
fractional digits. For example:

    iex> t = ~T[10:00:07.002]
    ~T[10:00:07.002]
    iex> Cldr.Time.to_string(t, format: "SSS")
    {:ok, "002"}

If, however, fractional seconds (format code `S`) are formatted
immediately after seconds (format code `s`) then a decimal
separator is inserted between the `s` and `S`. The separator
will be that appropriate for the designated locale, number system
and selected separators.  For example:

    iex> t = ~T[10:00:07.002]
    ~T[10:00:07.002]
    iex> Cldr.Time.to_string t, format: "ssSSS"
    {:ok, "07.002"}

Lastly, the number of fractional seconds is truncated
to the count of the number of `S` format characters. And, if
required, will be zero filled to that width.

    iex> t = ~T[10:00:07.002]
    ~T[10:00:07.002]
    iex> Cldr.Time.to_string t, format: "ssS"
    {:ok, "07.0"}
    iex> Cldr.Time.to_string t, format: "ssSS"
    {:ok, "07.00"}
    iex> Cldr.Time.to_string t, format: "ssSSS"
    {:ok, "07.002"}
    iex> Cldr.Time.to_string t, format: "ssSSSS"
    {:ok, "07.0020"}

# `cyclic_year`

```elixir
@spec cyclic_year(Cldr.Calendar.any_date_time(), integer(), Keyword.t()) ::
  String.t() | {:error, String.t()}
```

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

**NOTE: In the current implementation, the cyclic year is
delegated to `Cldr.DateTime.Formatter.year/3`
(format symbol `y`) and does not return a localized
cyclic year.**

## Format Symbol

| Symbol     | Example         | Cldr Format     |
| :--------  | :-------------- | :-------------- |
| U, UU, UUU | "甲子"           | Abbreviated     |
| UUUU       | "甲子" (for now) | Wide            |
| UUUUU      | "甲子" (for now) | Narrow          |

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

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

# `cyclic_year`

```elixir
@spec cyclic_year(
  Cldr.Calendar.any_date_time(),
  integer(),
  Cldr.Locale.locale_reference(),
  Cldr.backend(),
  map()
) :: String.t() | {:error, String.t()}
```

# `date`

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

Returns a formatted date.

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

# `date`

```elixir
@spec date(
  Calendar.date(),
  integer(),
  Cldr.Locale.locale_reference(),
  Cldr.backend(),
  Keyword.t() | map()
) :: String.t() | {:error, {module(), String.t()}}
```

# `day_name`

```elixir
@spec day_name(Cldr.Calendar.any_date_time(), integer(), Keyword.t()) ::
  String.t() | {:error, String.t()}
```

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

## Arguments

* `date` is 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 `t:Cldr.LanguageTag.t/0` struct. The default is `Cldr.get_locale/0`

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

## Format Symbol

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

| Symbol     | Example         | Cldr Format     |
| :--------  | :-------------- | :-------------- |
| E, EE, EEE | "Tue"           | Abbreviated     |
| EEEE       | "Tuesday"       | Wide            |
| EEEEE      | "T"             | Narrow          |
| EEEEEE     | "Tu"            | Short           |

## Examples

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

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

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

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

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

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

# `day_name`

```elixir
@spec day_name(
  Cldr.Calendar.any_date_time(),
  integer(),
  Cldr.Locale.locale_reference(),
  Cldr.backend(),
  map()
) :: String.t() | {:error, String.t()}
```

# `day_of_month`

```elixir
@spec day_of_month(Cldr.Calendar.any_date_time(), integer(), Keyword.t()) ::
  String.t() | {:error, String.t()}
```

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

## Arguments

* `date` is 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 `t:Cldr.LanguageTag.t/0` struct. The default is `Cldr.get_locale/0`

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

| Symbol     | Example         | Cldr Format     |
| :--------  | :-------------- | :-------------- |
| d          | 2, 22           |                 |
| dd         | 02, 22          |                 |
| ddd        | 2nd, 22nd       |                 |

## Examples

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

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

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

# `day_of_month`

```elixir
@spec day_of_month(
  Cldr.Calendar.date(),
  integer(),
  Cldr.Locale.locale_reference(),
  Cldr.backend(),
  map()
) :: String.t() | {:error, String.t()}
```

# `day_of_week`

```elixir
@spec day_of_week(Cldr.Calendar.any_date_time(), integer(), Keyword.t()) ::
  String.t() | {:error, String.t()}
```

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

## Arguments

* `date` is 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 `t:Cldr.LanguageTag.t/0` struct. The default is `Cldr.get_locale/0`

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

| Symbol     | Example         | Cldr Format     |
| :--------  | :-------------- | :-------------- |
| e          | 2               | Single digit    |
| ee         | "02"            | Two digits      |
| eee        | "Tue"           | Abbreviated     |
| eeee       | "Tuesday"       | Wide            |
| eeeee      | "T"             | Narrow          |
| eeeeee     | "Tu"            | Short           |

## Examples

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

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

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

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

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

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

# `day_of_week`

```elixir
@spec day_of_week(
  Cldr.Calendar.any_date_time(),
  integer(),
  Cldr.Locale.locale_reference(),
  Cldr.backend(),
  map()
) :: String.t() | {:error, String.t()}
```

# `day_of_year`

```elixir
@spec day_of_year(Cldr.Calendar.any_date_time(), integer(), Keyword.t()) ::
  String.t() | {:error, String.t()}
```

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

## Arguments

* `date` is 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 `t:Cldr.LanguageTag.t/0` struct. The default is `Cldr.get_locale/0`

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

## Format Symbol

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

| Symbol     | Example         | Cldr Format     |
| :--------  | :-------------- | :-------------- |
| D          | 3, 33, 333      |                 |
| DD         | 03, 33, 333     |                 |
| DDD        | 003, 033, 333   |                 |

## Examples

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

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

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

# `day_of_year`

```elixir
@spec day_of_year(
  Cldr.Calendar.any_date_time(),
  integer(),
  Cldr.Locale.locale_reference(),
  Cldr.backend(),
  map()
) :: String.t() | {:error, String.t()}
```

# `decimal_separator`

```elixir
@spec decimal_separator(
  Cldr.Calendar.any_date_time(),
  atom(),
  Cldr.Locale.locale_reference(),
  Cldr.backend(),
  map()
) :: String.t() | {:error, String.t()}
```

Inserts the decimal separator appropriate for the
given locale, number system and separators.

# `era`

```elixir
@spec era(Cldr.Calendar.any_date_time(), pos_integer(), Keyword.t()) ::
  String.t() | {:error, String.t()}
```

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

## Arguments

* `date` is a `Date` struct or any map that contains at least the
  keys `:month` and `:calendar`

* `n` in an integer between 1 and 5 that determines the format of
  the year

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

* `options` is a `Keyword` list of options.  The only applicable
  option is `:era` with a value of either `nil` (the default) or
  `:variant` which will return the variant form of an era if one
  is available.

## Format Symbol

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

| Symbol     | Example         | Cldr Format                 |
| :--------  | :-------------- | :---------------------------|
| G, GG, GGG | "AD"            | Abbreviated                 |
| GGGG       | "Anno Domini    | Wide                        |
| GGGGG      | "A"             | Narrow                      |

## Examples

    iex> Cldr.DateTime.Formatter.era(~D[2017-12-01], 1)
    "AD"

    iex> Cldr.DateTime.Formatter.era(~D[2017-12-01], 4, "fr", MyApp.Cldr)
    "après Jésus-Christ"

    iex> Cldr.DateTime.Formatter.era(~D[2017-12-01], 4, "fr", MyApp.Cldr, era: :variant)
    "de l’ère commune"

# `era`

```elixir
@spec era(
  Cldr.Calendar.any_date_time(),
  pos_integer(),
  Cldr.Locale.locale_reference(),
  Cldr.backend(),
  map()
) :: String.t() | {:error, String.t()}
```

# `extended_year`

```elixir
@spec extended_year(Cldr.Calendar.any_date_time(), integer(), Keyword.t()) ::
  String.t() | {:error, String.t()}
```

Returns the Extended year (format symbol `u`).

## Arguments

* `date` is a `Date` struct or any map that contains at least the
  keys `:month` and `:calendar`

* `n` in an integer between 1 and 5 that determines the format of
  the year

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

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

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

## Format Symbol

| Symbol     | Example         | Cldr Format               |
| :--------  | :-------------- | :------------------------ |
| u+         | 4601            | Minimum necessary digits  |

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

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

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

# `extended_year`

```elixir
@spec extended_year(
  Calendar.date(),
  integer(),
  Cldr.Locale.locale_reference(),
  Cldr.backend(),
  map()
) ::
  String.t() | {:error, String.t()}
```

# `fractional_second`

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

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

## Arguments

* `time` is 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 `t:Cldr.LanguageTag.t/0` struct. The default is `Cldr.get_locale/0`

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

## Format Symbol

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

| Symbol | Results    | Description                                           |
| :----  | :--------- | :---------------------------------------------------- |
| S      | "4.0"      | Minimum digits of fractional seconds                  |
| SS     | "4.00"     | Number of seconds zero-padded to 2 fractional digits  |
| SSS    | "4.002"    | Number of seconds zero-padded to 3 fractional digits  |

## Examples

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

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

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

# `fractional_second`

```elixir
@spec fractional_second(
  Cldr.Calendar.time(),
  integer(),
  Cldr.Locale.locale_reference(),
  Cldr.backend(),
  map()
) :: String.t() | {:error, String.t()}
```

# `generic_non_location`

```elixir
@spec generic_non_location(Cldr.Calendar.date_time(), integer(), Keyword.t()) ::
  String.t() | {:error, String.t()}
```

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

## Arguments

* `time` is a `t:DateTime.t/0` 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 `t:Cldr.LanguageTag.t/0` struct. The default is `Cldr.get_locale/0`.

* `options` is a `Keyword` list of options.  There are no options used in
  `generic_non_location/4`

## Format Symbol

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

| Symbol | Results    | Description                                             |
| :----  | :--------- | :------------------------------------------------------ |
| v      | "PT"  | The short generic non-location format Where that is unavailable, falls back to the generic location format ("VVVV"), then the short localized GMT format as the final fallback |
| vvvv   | "Pacific Time" | The long generic non-location format. Where that is unavailable, falls back to generic location format ("VVVV"). |

## Examples

    iex> Cldr.DateTime.Formatter.generic_non_location %{time_zone: "Etc/UTC",
    ...>   utc_offset: 0, std_offset: 0}, 4
    "Coordinated Universal Time"

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

# `generic_non_location`

```elixir
@spec generic_non_location(
  Cldr.Calendar.date_time(),
  integer(),
  Cldr.Locale.locale_reference(),
  Cldr.backend(),
  map()
) :: String.t() | {:error, String.t()}
```

# `h11`

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

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

## Arguments

* `time` is 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 `t:Cldr.LanguageTag.t/0` struct. The default is `Cldr.get_locale/0`

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

## Format Symbol

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

| Symbol  | Midn.	|	Morning	| Noon |	Afternoon	| Midn. |
| :----:  | :---: | :-----: | :--: | :--------: | :---: |
|   K     |   0   | 1...11  |   0  |  1...11    |   0   |

## Examples

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

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

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

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

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

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

# `h11`

```elixir
@spec h11(
  Cldr.Calendar.time(),
  integer(),
  Cldr.Locale.locale_reference(),
  Cldr.backend(),
  map()
) ::
  String.t() | {:error, String.t()}
```

# `h12`

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

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

## Arguments

* `time` is 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 `t:Cldr.LanguageTag.t/0` struct. The default is `Cldr.get_locale/0`

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

## Format Symbol

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

| Symbol  | Midn.	|	Morning	| Noon |	Afternoon	| Midn. |
| :----:  | :---: | :-----: | :--: | :--------: | :---: |
|   h     |  12   | 1...11  |  12  |  1...11    |  12   |

## Examples

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

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

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

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

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

# `h12`

```elixir
@spec h12(
  Cldr.Calendar.time(),
  integer(),
  Cldr.Locale.locale_reference(),
  Cldr.backend(),
  map()
) ::
  String.t() | {:error, String.t()}
```

# `h23`

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

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

## Arguments

* `time` is 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 `t:Cldr.LanguageTag.t/0` struct. The default is `Cldr.get_locale/0`

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

## Format Symbol

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

| Symbol  | Midn.	|	Morning	| Noon |	Afternoon	| Midn. |
| :----:  | :---: | :-----: | :--: | :--------: | :---: |
|   H     |   0   | 1...11  |  12  |  13...23   |   0   |

## Examples:

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

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

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

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

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

# `h23`

```elixir
@spec h23(
  Cldr.Calendar.time(),
  integer(),
  Cldr.Locale.locale_reference(),
  Cldr.backend(),
  map()
) ::
  String.t() | {:error, String.t()}
```

# `h24`

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

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

## Arguments

* `time` is 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 `t:Cldr.LanguageTag.t/0` struct. The default is `Cldr.get_locale/0`

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

## Format Symbol

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

| Symbol  | Midn.	|	Morning	| Noon |	Afternoon	| Midn. |
| :----:  | :---: | :-----: | :--: | :--------: | :---: |
|   k     |  24   | 1...11  |  12  |  13...23   |  24   |

## Examples

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

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

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

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

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

# `h24`

```elixir
@spec h24(
  Cldr.Calendar.time(),
  integer(),
  Cldr.Locale.locale_reference(),
  Cldr.backend(),
  map()
) ::
  String.t() | {:error, String.t()}
```

# `has_year_and_month`
*macro* 

# `hour`

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

Returns the hour formatted in a locale-specific format

## Arguments

* `time` is 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 `t:Cldr.LanguageTag.t/0` struct. The default is `Cldr.get_locale/0`

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

# `hour`

```elixir
@spec hour(
  Cldr.Calendar.time(),
  integer(),
  Cldr.Locale.locale_reference(),
  Cldr.backend(),
  map()
) ::
  String.t() | {:error, String.t()}
```

# `is_date_time`
*macro* 

# `is_time`
*macro* 

# `literal`

```elixir
@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"

# `literal`

```elixir
@spec literal(
  any(),
  String.t(),
  Cldr.Locale.locale_reference(),
  Cldr.backend(),
  map()
) :: String.t()
```

# `maybe_wrap`

# `millisecond`

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

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

## Arguments

* `time` is 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 `t:Cldr.LanguageTag.t/0` struct. The default is `Cldr.get_locale/0`

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

## Format Symbol

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

| Symbol | Results    | Description                                             |
| :----  | :--------- | :------------------------------------------------------ |
| A+     | "4000"     | Minimum necessary digits of milliseconds since midnight |

## Examples

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

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

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

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

# `millisecond`

```elixir
@spec millisecond(
  Cldr.Calendar.time(),
  integer(),
  Cldr.Locale.locale_reference(),
  Cldr.backend(),
  map()
) :: String.t() | {:error, String.t()}
```

# `minute`

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

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

## Arguments

* `time` is 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 `t:Cldr.LanguageTag.t/0` struct. The default is `Cldr.get_locale/0`

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

## Format Symbol

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

| Symbol | Results    | Description                                           |
| :----  | :--------- | :---------------------------------------------------- |
| m      | 3, 10      | Minimum digits of minutes                             |
| mm     | "03", "12" | Number of minutes zero-padded to 2 digits             |

## Examples

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

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

# `minute`

```elixir
@spec minute(
  Cldr.Calendar.time(),
  integer(),
  Cldr.Locale.locale_reference(),
  Cldr.backend(),
  map()
) ::
  String.t() | {:error, String.t()}
```

# `month`

```elixir
@spec month(Cldr.Calendar.any_date_time(), integer(), Keyword.t()) ::
  String.t() | {:error, String.t()}
```

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

## Arguments

* `date` is 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 `t:Cldr.LanguageTag.t/0` struct. The default is `Cldr.get_locale/0`

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

## Format Symbol

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

| Symbol     | Example         | Cldr Format     |
| :--------  | :-------------- | :-------------- |
| M          | 9               | Single digit    |
| MM         | "09"            | Two digits      |
| MMM        | "Sep"           | Abbreviated     |
| MMMM       | "September"     | Wide            |
| MMMMM      | "S"             | Narrow          |

## Examples

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

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

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

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

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

# `month`

```elixir
@spec month(
  Cldr.Calendar.any_date_time(),
  integer(),
  Cldr.Locale.locale_reference(),
  Cldr.backend(),
  map()
) :: String.t() | {:error, String.t()}
```

# `period_am_pm`

```elixir
@spec period_am_pm(Cldr.Calendar.time(), integer(), Keyword.t()) ::
  String.t() | {:error, String.t()}
```

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

## Arguments

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

* `n` in an integer between 1 and 5 that determines the format of the
  time period

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

* `options` is a `Keyword` list of options.  The available option is
  `period: :variant` which will use a veriant of localised "am" or
  "pm" if one is available

## Notes

May be upper or lowercase depending on the locale and other options.
The wide form may be the same as the short form if the “real”
long form (eg ante meridiem) is not customarily used.

## Format Symbol

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

| Symbol     | Example         | Cldr Format     |
| :--------  | :-------------- | :-------------- |
| a, aa, aaa | "am."           | Abbreviated     |
| aaaa       | "am."           | Wide            |
| aaaaa      | "am"            | Narrow          |

## Examples

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

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

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

    iex> Cldr.DateTime.Formatter.period_am_pm %{hour: 21, minute: 0}, 5
    "p"

    iex> Cldr.DateTime.Formatter.period_am_pm %{hour: 21, minute: 0}, 5
    "p"

# `period_am_pm`

```elixir
@spec period_am_pm(
  Cldr.Calendar.time(),
  integer(),
  Cldr.Locale.locale_reference(),
  Cldr.backend(),
  map()
) :: String.t() | {:error, String.t()}
```

# `period_flex`

```elixir
@spec period_flex(Cldr.Calendar.time(), integer(), Keyword.t()) ::
  String.t() | {:error, String.t()}
```

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

## Arguments

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

* `n` in an integer between 1 and 5 that determines the format of the
  time period

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

* `options` is a `Keyword` list of options.  The available option is
  `period: :variant` which will use a veriant of localised flexible time
  period names if one is available

## Notes

The time period may be upper or lowercase depending on the locale and
other options.  Often there is only one width that is customarily used.

## Format Symbol

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

| Symbol     | Example         | Cldr Format     |
| :--------  | :-------------- | :-------------- |
| B, BB, BBB | "at night"      | Abbreviated     |
| BBBB       | "at night"      | Wide            |
| BBBBB      | "at night"      | Narrow          |

## Examples

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

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

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

# `period_flex`

```elixir
@spec period_flex(
  Cldr.Calendar.time(),
  integer(),
  Cldr.Locale.locale_reference(),
  Cldr.backend(),
  map()
) :: String.t() | {:error, String.t()}
```

# `period_noon_midnight`

```elixir
@spec period_noon_midnight(Cldr.Calendar.time(), integer(), Keyword.t()) ::
  String.t() | {:error, String.t()}
```

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

## Arguments

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

* `n` in an integer between 1 and 5 that determines the format of the
  time period

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

* `options` is a `Keyword` list of options.  The available option is
  `period: :variant` which will use a variant of localised "noon" and
  "midnight" if one is available

## Notes

If the language doesn't support "noon" or "midnight" then
`am`/`pm` is used for all time periods.

May be upper or lowercase depending on the locale and other options.
If the locale doesn't have the notion of a unique `noon == 12:00`,
then the PM form may be substituted. Similarly for `midnight == 00:00`
and the AM form.

## Format Symbol

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

| Symbol     | Example         | Cldr Format     |
| :--------  | :-------------- | :-------------- |
| b, bb, bbb | "mid."          | Abbreviated     |
| bbbb       | "midnight"      | Wide            |
| bbbbb      | "md"            | Narrow          |

## Examples

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

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

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

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

# `period_noon_midnight`

```elixir
@spec period_noon_midnight(
  Cldr.Calendar.time(),
  integer(),
  Cldr.Locale.locale_reference(),
  Cldr.backend(),
  map()
) :: String.t() | {:error, String.t()}
```

# `quarter`

```elixir
@spec quarter(Cldr.Calendar.any_date_time(), integer(), Keyword.t()) ::
  String.t() | {:error, String.t()}
```

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

## Arguments

* `date` is 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 `t:Cldr.LanguageTag.t/0` struct. The default is `Cldr.get_locale/0`

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

## Format Symbol

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

| Symbol     | Example         | Cldr Format     |
| :--------  | :-------------- | :-------------- |
| Q          | 2               | Single digit    |
| QQ         | "02"            | Two digits      |
| QQQ        | "Q2"            | Abbreviated     |
| QQQQ       | "2nd quarter"   | Wide            |
| QQQQQ      | "2"             | Narrow          |

## Examples

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

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

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

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

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

# `quarter`

```elixir
@spec quarter(
  Cldr.Calendar.any_date_time(),
  integer(),
  Cldr.Locale.locale_reference(),
  Cldr.backend(),
  map()
) :: String.t() | {:error, String.t()}
```

# `related_year`

```elixir
@spec related_year(Cldr.Calendar.any_date_time(), 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 `t:Cldr.LanguageTag.t/0` struct. The default is `Cldr.get_locale/0`

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

## Format Symbol

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

| Symbol     | Example         | Cldr Format     |
| :--------  | :-------------- | :-------------- |
| r+         | 2017            |                 |

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

# `related_year`

```elixir
@spec related_year(
  Cldr.Calendar.date(),
  integer(),
  Cldr.Locale.locale_reference(),
  Cldr.backend(),
  map()
) :: String.t() | {:error, String.t()}
```

# `second`

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

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

## Arguments

* `time` is 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 `t:Cldr.LanguageTag.t/0` struct. The default is `Cldr.get_locale/0`

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

## Format Symbol

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

| Symbol | Results    | Description                                           |
| :----  | :--------- | :---------------------------------------------------- |
| s      | 3, 48      | Minimum digits of seconds                             |
| ss     | "03", "48" | Number of seconds zero-padded to 2 digits             |

## Examples

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

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

# `second`

```elixir
@spec second(
  Cldr.Calendar.time(),
  integer(),
  Cldr.Locale.locale_reference(),
  Cldr.backend(),
  map()
) ::
  String.t() | {:error, String.t()}
```

# `specific_non_location`

```elixir
@spec specific_non_location(Cldr.Calendar.date_time(), integer(), Keyword.t()) ::
  String.t() | {:error, String.t()}
```

Returns the specific non-location timezone format
(format symbol `V`) part of a `DateTime` or `Time`.

## Arguments

* `time` is a `t:DateTime.t/0` struct or any map that contains at least the `:time_zone`
  key set to a known IANA time zone name.

* `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 `t:Cldr.LanguageTag.t/0` struct. The default is `Cldr.get_locale/0`

* `options` is a `Keyword` list of options.  There are no options used in
 `specific_non_location/4`

## Format Symbol

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

| Symbol | Results        | Description                                             |
| :----  | :------------- | :------------------------------------------------------ |
| V      | "UTC"          | Short specific non-location format                      |
| VV     | "Etc/UTC       | The `:time_zone` field of `time`,                       |
| VVV    | "Unknown City" | Examplar city, or localized "Unknown location"          |
| VVVV   | "GMT"          | Delegates to `zone_gmt/4`                               |

## Examples

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

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

    iex> Cldr.DateTime.Formatter.specific_non_location(%{time_zone: "Etc/UTC",
    ...>   utc_offset: 0, std_offset: 0}, 3)
    "Unknown Location"

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

# `specific_non_location`

```elixir
@spec specific_non_location(
  Cldr.Calendar.date_time(),
  integer(),
  Cldr.Locale.locale_reference(),
  Cldr.backend(),
  map()
) :: String.t() | {:error, String.t()}
```

# `standalone_day_of_week`

```elixir
@spec standalone_day_of_week(Cldr.Calendar.any_date_time(), integer(), Keyword.t()) ::
  String.t() | {:error, String.t()}
```

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

## Arguments

* `date` is 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 `t:Cldr.LanguageTag.t/0` struct. The default is `Cldr.get_locale/0`

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

| Symbol     | Example         | Cldr Format     |
| :--------  | :-------------- | :-------------- |
| c, cc      | 2               | Single digit    |
| ccc        | "Tue"           | Abbreviated     |
| cccc       | "Tuesday"       | Wide            |
| ccccc      | "T"             | Narrow          |
| cccccc     | "Tu"            | Short           |

## Examples

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

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

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

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

# `standalone_day_of_week`

```elixir
@spec standalone_day_of_week(
  Cldr.Calendar.date(),
  integer(),
  Cldr.Locale.locale_reference(),
  Cldr.backend(),
  map()
) :: String.t() | {:error, String.t()}
```

# `standalone_month`

```elixir
@spec standalone_month(Cldr.Calendar.any_date_time(), integer(), Keyword.t()) ::
  String.t() | {:error, String.t()}
```

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

## Arguments

* `date` is 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 `t:Cldr.LanguageTag.t/0` struct. The default is `Cldr.get_locale/0`

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

## Format Symbol

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

| Symbol     | Example         | Cldr Format     |
| :--------  | :-------------- | :-------------- |
| L          | 9               | Single digit    |
| LL         | "09"            | Two digits      |
| LLL        | "Sep"           | Abbreviated     |
| LLLL       | "September"     | Wide            |
| LLLLL      | "S"             | Narrow          |

## Examples

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

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

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

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

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

# `standalone_month`

```elixir
@spec standalone_month(
  Cldr.Calendar.date(),
  integer(),
  Cldr.Locale.locale_reference(),
  Cldr.backend(),
  map()
) :: String.t() | {:error, String.t()}
```

# `standalone_quarter`

```elixir
@spec standalone_quarter(Cldr.Calendar.any_date_time(), integer(), Keyword.t()) ::
  String.t() | {:error, String.t()}
```

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

## Arguments

* `date` is 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 `t:Cldr.LanguageTag.t/0` struct. The default is `Cldr.get_locale/0`

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

## Format Symbol

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

| Symbol     | Example         | Cldr Format     |
| :--------  | :-------------- | :-------------- |
| q          | 2               | Single digit    |
| qq         | "02"            | Two digits      |
| qqq        | "Q2"            | Abbreviated     |
| qqqq       | "2nd quarter"   | Wide            |
| qqqqq      | "2"             | Narrow          |

## Examples

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

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

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

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

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

# `standalone_quarter`

```elixir
@spec standalone_quarter(
  Cldr.Calendar.date(),
  integer(),
  Cldr.Locale.locale_reference(),
  Cldr.backend(),
  map()
) :: String.t() | {:error, String.t()}
```

# `time`

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

Returns a formatted time.

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

# `time`

```elixir
@spec time(
  Cldr.Calendar.time(),
  integer(),
  Cldr.Locale.locale_reference(),
  Cldr.backend(),
  Keyword.t() | map()
) :: String.t() | {:error, String.t()} | {:error, {module(), String.t()}}
```

# `week_aligned_year`

```elixir
@spec week_aligned_year(Cldr.Calendar.any_date_time(), integer(), Keyword.t()) ::
  String.t() | {:error, String.t()}
```

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

## Arguments

* `date` is a `Date` struct or any map that contains at least the
  keys `:month` and `:calendar`

* `n` in an integer between 1 and 5 that determines the format of
  the year

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

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

## Format Symbol

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

| Symbol     | Example         | Cldr Format                 |
| :--------  | :-------------- | :---------------------------|
| Y          | 7               | Minimum necessary digits    |
| YY         | "17"            | Least significant 2 digits  |
| YYY        | "017", "2017"   | Padded to at least 3 digits |
| YYYY       | "2017"          | Padded to at least 4 digits |
| YYYYY      | "02017"         | Padded to at least 5 digits |

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

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

## Examples

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

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

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

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

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

# `week_aligned_year`

```elixir
@spec week_aligned_year(
  Cldr.Calendar.date(),
  integer(),
  Cldr.Locale.locale_reference(),
  Cldr.backend(),
  map()
) :: String.t() | {:error, String.t()}
```

# `week_of_month`

```elixir
@spec week_of_month(Cldr.Calendar.any_date_time(), integer(), Keyword.t()) ::
  String.t() | {:error, String.t()}
```

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

## Arguments

* `date` is 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 `t:Cldr.LanguageTag.t/0` struct. The default is `Cldr.get_locale/0`

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

## Format Symbol

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

| Symbol     | Example         | Cldr Format     |
| :--------  | :-------------- | :-------------- |
| W          | 2               |                 |

## Examples

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

# `week_of_month`

```elixir
@spec week_of_month(
  Cldr.Calendar.date(),
  integer(),
  Cldr.Locale.locale_reference(),
  Cldr.backend(),
  map()
) :: String.t() | {:error, String.t()}
```

# `week_of_year`

```elixir
@spec week_of_year(Cldr.Calendar.any_date_time(), integer(), Keyword.t()) ::
  String.t() | {:error, String.t()}
```

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

## Arguments

* `date` is 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 `t:Cldr.LanguageTag.t/0` struct. The default is `Cldr.get_locale/0`

* `options` is a `Keyword` list of options.  There are no options
  used in `week_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:

| Symbol     | Example         | Cldr Format     |
| :--------  | :-------------- | :-------------- |
| w          | 2, 22           |                 |
| ww         | 02, 22          |                 |

## Examples

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

# `week_of_year`

```elixir
@spec week_of_year(
  Cldr.Calendar.date(),
  integer(),
  Cldr.Locale.locale_reference(),
  Cldr.backend(),
  map()
) :: String.t() | {:error, String.t()}
```

# `year`

```elixir
@spec year(Cldr.Calendar.any_date_time(), integer(), Keyword.t()) ::
  String.t() | {:error, String.t()}
```

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

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

## Arguments

* `date` is 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 `t:Cldr.LanguageTag.t/0` struct. The default is `Cldr.get_locale/0`

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

## Format Symbol

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

| Symbol     | Example         | Cldr Format                 |
| :--------  | :-------------- | :---------------------------|
| y          | 7               | Minimum necessary digits    |
| yy         | "17"            | Least significant 2 digits  |
| yyy        | "017", "2017"   | Padded to at least 3 digits |
| yyyy       | "2017"          | Padded to at least 4 digits |
| yyyyy      | "02017"         | Padded to at least 5 digits |

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

## Examples

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

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

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

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

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

# `year`

```elixir
@spec year(
  Cldr.Calendar.any_date_time(),
  integer(),
  Cldr.Locale.locale_reference(),
  Cldr.backend(),
  map()
) :: String.t() | {:error, String.t()}
```

# `zone_basic`

```elixir
@spec zone_basic(Cldr.Calendar.date_time(), integer(), Keyword.t()) ::
  String.t() | {:error, String.t()}
```

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

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

## Arguments

* `time` is a `t:DateTime.t/0` 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 `t:Cldr.LanguageTag.t/0` struct. The default is `Cldr.get_locale/0`

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

## Format Symbol

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

| Symbol | Results        | Description                                             |
| :----  | :------------- | :------------------------------------------------------ |
| Z..ZZZ | "+0100"        | ISO8601 Basic Format with hours and minutes             |
| ZZZZ   | "+01:00"       | Delegates to `zone_gmt/4`                               |
| ZZZZZ  | "+01:00:10"    | ISO8601 Extended format with optional seconds           |

## Examples

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

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

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

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

# `zone_basic`

```elixir
@spec zone_basic(
  Cldr.Calendar.date_time(),
  integer(),
  Cldr.Locale.locale_reference(),
  Cldr.backend(),
  map()
) :: String.t() | {:error, String.t()}
```

# `zone_gmt`

```elixir
@spec zone_gmt(Cldr.Calendar.date_time(), integer(), Keyword.t()) ::
  String.t() | {:error, String.t()}
```

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

## Arguments

* `time` is a `t:DateTime.t/0` 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 `t:Cldr.LanguageTag.t/0` struct. The default is `Cldr.get_locale/0`

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

## Format Symbol

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

| Symbol | Results        | Description                                                     |
| :----  | :------------- | :-------------------------------------------------------------- |
| O      | "GMT+1"        | Short localised GMT format                                      |
| OOOO   | "GMT+01:00"    | Long localised GMT format                                       |

## Examples

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

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

# `zone_gmt`

```elixir
@spec zone_gmt(
  Cldr.Calendar.date_time(),
  integer(),
  Cldr.Locale.locale_reference(),
  Cldr.backend(),
  map()
) :: String.t() | {:error, String.t()}
```

# `zone_iso`

```elixir
@spec zone_iso(Cldr.Calendar.date_time(), integer(), Keyword.t()) ::
  String.t() | {:error, String.t()}
```

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

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

## Arguments

* `time` is a `t:DateTime.t/0` 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 `t:Cldr.LanguageTag.t/0` struct. The default is `Cldr.get_locale/0`

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

## Format Symbol

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

| Symbol | Results        | Description                                                       |
| :----  | :------------- | :---------------------------------------------------------------- |
| x      | "+0100"        | ISO8601 Basic Format with hours and optional minutes              |
| xx     | "-0800"        | ISO8601 Basic Format with hours and minutes                       |
| xxx    | "+01:00"       | ISO8601 Extended Format with hours and minutes                    |
| xxxx   | "+010059"      | ISO8601 Basic Format with hours and minutes, optional seconds     |
| xxxxx  | "+01:00:10"    | ISO8601 Extended Format with hours and minutes, optional seconds  |

## Examples

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

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

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

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

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

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

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

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

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

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

# `zone_iso`

```elixir
@spec zone_iso(
  Cldr.Calendar.date_time(),
  integer(),
  Cldr.Locale.locale_reference(),
  Cldr.backend(),
  map()
) :: String.t() | {:error, String.t()}
```

# `zone_iso_z`

```elixir
@spec zone_iso_z(Cldr.Calendar.date_time(), integer(), Keyword.t()) ::
  String.t() | {:error, String.t()}
```

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

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

## Arguments

* `time` is a `t:DateTime.t/0` 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 `t:Cldr.LanguageTag.t/0` struct. The default is `Cldr.get_locale/0`

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

## Format Symbol

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

| Symbol | Results        | Description                                                              |
| :----  | :------------- | :----------------------------------------------------------------------- |
| X      | "+01"          | ISO8601 Basic Format with hours and optional minutes or "Z"              |
| XX     | "+0100"        | ISO8601 Basic Format with hours and minutes or "Z"                       |
| XXX    | "+0100"        | ISO8601 Basic Format with hours and minutes, optional seconds or "Z"     |
| XXXX   | "+010059"      | ISO8601 Basic Format with hours and minutes, optional seconds or "Z"     |
| XXXXX  | "+01:00:10"    | ISO8601 Extended Format with hours and minutes, optional seconds or "Z"  |

## Examples

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

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

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

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

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

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

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

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

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

# `zone_iso_z`

```elixir
@spec zone_iso_z(
  Cldr.Calendar.date_time(),
  integer(),
  Cldr.Locale.locale_reference(),
  Cldr.backend(),
  map()
) :: String.t() | {:error, String.t()}
```

# `zone_short`

```elixir
@spec zone_short(Cldr.Calendar.date_time(), integer(), Keyword.t()) ::
  String.t() | {:error, String.t()}
```

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

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

## Arguments

* `time` is a `t:DateTime.t/0` 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 `t:Cldr.LanguageTag.t/0` struct. The default is `Cldr.get_locale/0`

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

## Format Symbol

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

| Symbol | Results    | Description                                             |
| :----  | :--------- | :------------------------------------------------------ |
| z..zzz | "UTC"      | `:zone_abbr` key, unlocalised                           |
| zzzz   | "GMT"      | Delegates to `zone_gmt/4`                               |

## Examples

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

    iex> Cldr.DateTime.Formatter.zone_short %{time_zone: "Etc/GMT",
    ...>   utc_offset: 0, std_offset: 0}, 4
    "Greenwich Mean Time"

# `zone_short`

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

---

*Consult [api-reference.md](api-reference.md) for complete listing*