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

Provides localization and formatting of a time.

A time is any `t:Time.t/0` struct or any map with one or more of
the keys `:hour`, `:minute`, `:second` and optionally `:time_zone`,
`:zone_abbr`, `:utc_offset`, `:std_offset` and `:microsecond`.

`Cldr.Time` provides support for the built-in calendar
`Calendar.ISO` or any calendars defined with
[ex_cldr_calendars](https://hex.pm/packages/ex_cldr_calendars)

For information about specifying formats, see `Cldr.DateTime.Format`.

# `available_formats`

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

Returns a map of the available date formats for a
given locale and calendar.

### Arguments

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

* `calendar` is any calendar returned by `Cldr.DateTime.Format.calendars_for/1`
  The default is `:gregorian`.

* `backend` is any module that includes `use Cldr` and therefore
  is a `Cldr` backend module. The default is `Cldr.default_backend/0`.

### Examples:

    iex> Cldr.Time.available_formats(:en)
    {:ok,
     %{
       h: %{unicode: "h a", ascii: "h a"},
       ms: "mm:ss",
       Bhm: "h:mm B",
       H: "HH",
       Hm: "HH:mm",
       Bhms: "h:mm:ss B",
       Hms: "HH:mm:ss",
       hv: %{unicode: "h a v", ascii: "h a v"},
       Bh: "h B",
       hms: %{unicode: "h:mm:ss a", ascii: "h:mm:ss a"},
       hm: %{unicode: "h:mm a", ascii: "h:mm a"},
       Hv: "HH'h' v",
       hmv: %{unicode: "h:mm a v", ascii: "h:mm a v"},
       Hmv: "HH:mm v",
       hmsv: %{unicode: "h:mm:ss a v", ascii: "h:mm:ss a v"},
       Hmsv: "HH:mm:ss v",
       ahmmsszzzz: %{unicode: "h:mm:ss a zzzz", ascii: "h:mm:ss a zzzz"},
       ahmmss: %{unicode: "h:mm:ss a", ascii: "h:mm:ss a"},
       ahmmssz: %{unicode: "h:mm:ss a z", ascii: "h:mm:ss a z"},
       ahmm: %{unicode: "h:mm a", ascii: "h:mm a"}
     }}

# `formats`

```elixir
@spec formats(
  Cldr.Locale.locale_reference(),
  Cldr.Calendar.calendar(),
  Cldr.backend()
) ::
  {:ok, Cldr.DateTime.Format.standard_formats()}
  | {:error, {atom(), String.t()}}
```

Returns a map of the standard time formats for a given
locale and calendar.

### Arguments

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

* `calendar` is any calendar returned by `Cldr.DateTime.Format.calendars_for/1`
  The default is `:gregorian`.

* `backend` is any module that includes `use Cldr` and therefore
  is a `Cldr` backend module. The default is `Cldr.default_backend/0`.

### Examples:

    iex> Cldr.Time.formats(:en, :gregorian, MyApp.Cldr)
    {:ok,
     %Cldr.Time.Formats{
       short: :ahmm,
       medium: :ahmmss,
       long: :ahmmssz,
       full: :ahmmsszzzz
     }}

    iex> Cldr.Time.formats(:en, :buddhist, MyApp.Cldr)
    {:ok,
     %Cldr.Time.Formats{
       short: :ahmm,
       medium: :ahmmss,
       long: :ahmmssz,
       full: :ahmmsszzzz
     }}

# `hour_format_from_locale`

Return the preferred time format for a locale.

### Arguments

* `language_tag` is any language tag returned by `Cldr.Locale.new/2`
  or any `locale_name` returned by `Cldr.known_locale_names/1`

### Returns

* The hour format as an atom to be used for localization purposes. The
  return value is used as a function name in `Cldr.DateTime.Formatter`

### Notes

* The `hc` key of the `u` extension is honoured and will
  override the default preferences for a locale or territory.
  See the last example below.

* Different locales and territories present the hour
  of day in different ways. These are represented
  in `Cldr.DateTime.Formatter` in the following way:

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

### Examples

    iex> Cldr.Time.hour_format_from_locale("en-AU")
    :h12

    iex> Cldr.Time.hour_format_from_locale("fr")
    :h23

    iex> Cldr.Time.hour_format_from_locale("fr-u-hc-h12")
    :h12

# `hour_format_from_locale`

# `is_full_time`
*macro* 

# `to_string`

```elixir
@spec to_string(Cldr.Calendar.any_date_time(), Cldr.backend(), options()) ::
  {:ok, String.t()} | {:error, {module(), String.t()}}
@spec to_string(Cldr.Calendar.any_date_time(), options(), []) ::
  {:ok, String.t()} | {:error, {module(), String.t()}}
```

Formats a *time* according to a format as defined in CLDR and
described in [TR35](http://unicode.org/reports/tr35/tr35-dates.html).

### Returns

* `{:ok, formatted_time}` or

* `{:error, reason}`.

### Arguments

* `time` is a `t:Time.t/0` struct or any map that contains
  one or more of the keys `:hour`, `:minute`, `:second` and optionally `:microsecond`,
  `:time_zone`, `:zone_abbr`, `:utc_offset` and `:std_offset`.

* `backend` is any module that includes `use Cldr` and therefore
  is a `Cldr` backend module. The default is `Cldr.default_backend!/0`.

* `options` is a keyword list of options for formatting.

### Options

* `:format` is either a [standard format](Cldr.DateTime.Format.html#module-standard-formats)
  (one of `:short`, `:medium`, `:long`, `:full`), a [format skeleton](Cldr.DateTime.Format.html#module-format-skeletons)
  or a [format pattern](Cldr.DateTime.Format.html#module-format-patterns).

  * The default is `:medium` for full *times* (that is, *times* having `:hour`,
    `:minute` and `:second` and optionally `:microsecond`,
    `:time_zone`, `:zone_abbr`, `:utc_offset` and `:std_offset` fields).

  * The default for partial *times* is to derive a format skeleton from the
    *time* and find the best match from the formats returned by
    `Cldr.Date.available_formats/3`.

  * See `Cldr.DateTime.Format` for more information about specifying formats.

* `:locale` any locale returned by `Cldr.known_locale_names/1`.  The default is
  `Cldr.get_locale/0`.

* `:number_system` a number system into which the formatted datetime digits should
  be transliterated. See `Cldr.known_number_systems/0`. The default is
  the number system associated with the `:locale`.

* `:separators` selects which of the available symbol
  sets should be used when formatting fractional seconds (format
  character `S`).  The default is `:standard`. Some limited locales have an alternative `:us`
  variant that can be used. See `Cldr.Number.Symbol.number_symbols_for/3`
  for the symbols supported for a given locale and number system.

* `:prefer` expresses the preference for one of the possible alternative
  sub-formats. See the variant preference notes below.

* `period: :variant` will use a variant for the time period and flexible time period if
  one is available in the locale.  For example, in the `:en` locale, `period: :variant` will
  return "pm" instead of "PM".

### Variant Preference

* A small number of formats have one of two different alternatives, each with their own
  preference specifier. The preferences are specified with the `:prefer` option to
  `Cldr.Date.to_string/3`. The preference is expressed as an atom, or a list of one or two
  atoms with one atom being either `:unicode` or `:ascii` and one atom being either
  `:default` or `:variant`.

  * Some formats (at the time of publishng only time formats but that
    may change in the future) have `:unicode` and `:ascii` versions of the format. The
    difference is the use of ascii space (0x20) as a separateor in the `:ascii` verison
    whereas the `:unicode` version may use non-breaking or other space characters. The
    default is `:unicode` and this is the strongly preferred option. The `:ascii` format
    is primarily to support legacy use cases and is not recommended. See
    `Cldr.Time.available_formats/3` to see which formats have these variants.

  * Some formats (at the time of publishing, only date and datetime formats) have
    `:default` and `:variant` versions of the format. These variant formats are only
    included in a small number of locales. For example, the `:"en-CA"` locale, which has
    a `:default` format respecting typical Canadian formatting and a `:variant` that is
    more closely aligned to US formatting. The default is `:default`.

### Examples

    iex> Cldr.Time.to_string(~T[07:35:13.215217], MyApp.Cldr)
    {:ok, "7:35:13 AM"}

    iex> Cldr.Time.to_string(~T[07:35:13.215217], MyApp.Cldr, format: :short)
    {:ok, "7:35 AM"}

    iex> Cldr.Time.to_string(~T[07:35:13.215217], MyApp.Cldr, format: :short, period: :variant)
    {:ok, "7:35 am"}

    iex> Cldr.Time.to_string(~T[07:35:13.215217], MyApp.Cldr, format: :medium, locale: "fr")
    {:ok, "07:35:13"}

    iex> Cldr.Time.to_string(~T[07:35:13.215217], MyApp.Cldr, format: :medium)
    {:ok, "7:35:13 AM"}

    iex> {:ok, datetime} = DateTime.from_naive(~N[2000-01-01 23:59:59.0], "Etc/UTC")
    iex> Cldr.Time.to_string datetime, MyApp.Cldr, format: :long
    {:ok, "11:59:59 PM UTC"}

    # A partial time with a best match CLDR-defined format
    iex> Cldr.Time.to_string(%{hour: 23, minute: 11})
    {:ok, "11:11 PM"}

    # Sometimes the available time fields can't be mapped to an available
    # CLDR-defined format.
    iex> Cldr.Time.to_string(%{minute: 11})
    {:error,
     {Cldr.DateTime.UnresolvedFormat, "No available format resolved for :m"}}

# `to_string!`

```elixir
@spec to_string!(Cldr.Calendar.any_date_time(), Cldr.backend(), options()) ::
  String.t() | no_return()
@spec to_string!(Cldr.Calendar.any_date_time(), options(), []) ::
  String.t() | no_return()
```

Formats a *time* according to a format as defined in CLDR and
described in [TR35](http://unicode.org/reports/tr35/tr35-dates.html)
or raises an exception.

### Arguments

* `time` is a `t:Time.t/0` struct or any map that contains
  one or more of the keys `:hour`, `:minute`, `:second` and optionally `:microsecond`,
  `:time_zone`, `:zone_abbr`, `:utc_offset` and `:std_offset`.

* `backend` is any module that includes `use Cldr` and therefore
  is a `Cldr` backend module. The default is `Cldr.default_backend!/0`.

* `options` is a keyword list of options for formatting.

### Options

* `:format` is either a [standard format](Cldr.DateTime.Format.html#module-standard-formats)
  (one of `:short`, `:medium`, `:long`, `:full`), a [format skeleton](Cldr.DateTime.Format.html#module-format-skeletons)
  or a [format pattern](Cldr.DateTime.Format.html#module-format-patterns).

  * The default is `:medium` for full *times* (that is, *times* having `:hour`,
    `:minute` and `:second` and optionally `:microsecond`,
    `:time_zone`, `:zone_abbr`, `:utc_offset` and `:std_offset` fields).

  * The default for partial *times* is to derive a format skeleton from the
    *time* and find the best match from the formats returned by
    `Cldr.Date.available_formats/3`.

  * See `Cldr.DateTime.Format` for more information about specifying formats.

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

* `:number_system` a number system into which the formatted time digits should
  be transliterated.

* `:prefer` expresses the preference for one of the possible alternative
  sub-formats. See the variant preference notes below.

* `period: :variant` will use a variant for the time period and flexible time period if
  one is available in the locale.  For example, in the `:en` locale `period: :variant` will
  return "pm" instead of "PM".

### Variant Preference

* A small number of formats have one of two different alternatives, each with their own
  preference specifier. The preferences are specified with the `:prefer` option to
  `Cldr.Date.to_string/3`. The preference is expressed as an atom, or a list of one or two
  atoms with one atom being either `:unicode` or `:ascii` and one atom being either
  `:default` or `:variant`.

  * Some formats (at the time of publishng only time formats but that
    may change in the future) have `:unicode` and `:ascii` versions of the format. The
    difference is the use of ascii space (0x20) as a separateor in the `:ascii` verison
    whereas the `:unicode` version may use non-breaking or other space characters. The
    default is `:unicode` and this is the strongly preferred option. The `:ascii` format
    is primarily to support legacy use cases and is not recommended. See
    `Cldr.Time.available_formats/3` to see which formats have these variants.

  * Some formats (at the time of publishing, only date and datetime formats) have
    `:default` and `:variant` versions of the format. These variant formats are only
    included in a small number of locales. For example, the `:"en-CA"` locale, which has
    a `:default` format respecting typical Canadian formatting and a `:variant` that is
    more closely aligned to US formatting. The default is `:default`.

### Returns

* `formatted_time_string` or

* raises an exception.

### Examples

    iex> Cldr.Time.to_string!(~T[07:35:13.215217], MyApp.Cldr)
    "7:35:13 AM"

    iex> Cldr.Time.to_string!(~T[07:35:13.215217], MyApp.Cldr, format: :short)
    "7:35 AM"

    iex> Cldr.Time.to_string!(~T[07:35:13.215217], MyApp.Cldr, format: :short, period: :variant)
    "7:35 am"

    iex> Cldr.Time.to_string!(~T[07:35:13.215217], MyApp.Cldr, format: :medium, locale: "fr")
    "07:35:13"

    iex> Cldr.Time.to_string!(~T[07:35:13.215217], MyApp.Cldr, format: :medium)
    "7:35:13 AM"

    iex> {:ok, datetime} = DateTime.from_naive(~N[2000-01-01 23:59:59.0], "Etc/UTC")
    iex> Cldr.Time.to_string!(datetime, MyApp.Cldr, format: :long)
    "11:59:59 PM UTC"

    # A partial time with a best match CLDR-defined format
    iex> Cldr.Time.to_string!(%{hour: 23, minute: 11})
    "11:11 PM"

---

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