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

Provides localized and formatting of a `t:Date.t/0`
struct or any map with one or more of the keys `:year`, `:month`,
`:day` and optionally `:calendar`.

`Cldr.Date` 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.Date.available_formats(:en)
    {:ok,
     %{
       y: "y",
       d: "d",
       E: "ccc",
       M: "L",
       MMMEd: "E, MMM d",
       Ed: "d E",
       Md: "M/d",
       GyMMMd: "MMM d, y G",
       Gy: "y G",
       GyMMM: "MMM y G",
       GyMMMEd: "E, MMM d, y G",
       MMMd: "MMM d",
       GyMd: "M/d/y G",
       GyMEd: "E, M/d/y G",
       MMMMd: "MMMM d",
       GyM: "M/y G",
       MEd: "E, M/d",
       MMM: "LLL",
       yMd: "M/d/y",
       yMMMd: "MMM d, y",
       yMMMM: "MMMM y",
       yMMM: "MMM y",
       yMMMEd: "E, MMM d, y",
       yMEd: "E, M/d/y",
       yM: "M/y",
       yQQQQ: "QQQQ y",
       yQQQ: "QQQ y",
       yw: %{
         other: "'week' w 'of' Y",
         one: "'week' w 'of' Y",
         pluralize: :week_of_year
       },
       MMMMW: %{
         other: "'week' W 'of' MMMM",
         one: "'week' W 'of' MMMM",
         pluralize: :week_of_month
       },
       yMMMMd: "MMMM d, y",
       yMMMMEEEEd: "EEEE, MMMM d, y",
       yyMd: "M/d/yy"
     }}

# `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 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.Date.formats(:en, :gregorian, MyApp.Cldr)
    {:ok,
     %Cldr.Date.Formats{
       short: :yyMd,
       medium: :yMMMd,
       long: :yMMMMd,
       full: :yMMMMEEEEd
     }}

    iex> Cldr.Date.formats(:en, :buddhist, MyApp.Cldr)
    {:ok,
     %Cldr.Date.Formats{
       short: :GGGGGyMd,
       medium: :GyMMMd,
       long: :GyMMMMd,
       full: :GyMMMMEEEEd
     }}

# `is_full_date`
*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 *date* according to a format as defined in CLDR and
described in [TR35](http://unicode.org/reports/tr35/tr35-dates.html).

### Arguments

* `date` is a `t:Date.t/0` struct or any map that contains one or more
  of the keys `:year`, `:month`, `:day` and optionally `:calendar`.

* `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 *dates* (that is, *dates* having `:year`,
    `:month`, `:day` and `:calendar` fields).

  * The default for partial *dates* is to derive a format skeleton from the
    *date* 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`.

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

* `:era` which, if set to `:variant`, will use a variant for the era if one
  is available in the requested locale. In the `:en` locale, for example, `era: :variant`
  will return `CE` instead of `AD` and `BCE` instead of `BC`.

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

* `{:ok, formatted_string}` or

* `{:error, reason}`

### Examples

    # Full dates have the default format `:medium`
    iex> Cldr.Date.to_string(~D[2017-07-10], MyApp.Cldr, locale: :en)
    {:ok, "Jul 10, 2017"}

    iex> Cldr.Date.to_string(~D[2017-07-10], MyApp.Cldr, format: :medium, locale: :en)
    {:ok, "Jul 10, 2017"}

    iex> Cldr.Date.to_string(~D[2017-07-10], MyApp.Cldr, format: :full, locale: :en)
    {:ok, "Monday, July 10, 2017"}

    iex> Cldr.Date.to_string(~D[2017-07-10], MyApp.Cldr, format: :short, locale: :en)
    {:ok, "7/10/17"}

    iex> Cldr.Date.to_string(~D[2017-07-10], MyApp.Cldr, format: :short, locale: "fr")
    {:ok, "10/07/2017"}

    iex> Cldr.Date.to_string(~D[2024-03-01], format: :yMd, prefer: :variant, locale: "en-CA")
    {:ok, "1/3/2024"}

    # A partial date with a derived "best match" format
    iex> Cldr.Date.to_string(%{year: 2024, month: 6}, MyApp.Cldr, locale: "fr")
    {:ok, "6/2024"}

    # A partial date with a best match CLDR-defined format
    iex> Cldr.Date.to_string(%{year: 2024, month: 6}, MyApp.Cldr, format: :yMMM, locale: "fr")
    {:ok, "juin 2024"}

    # Sometimes the available date fields can't be mapped to an available
    # CLDR-defined format.
    iex> Cldr.Date.to_string(%{year: 2024, day: 3}, MyApp.Cldr, locale: "fr")
    {:error,
     {Cldr.DateTime.UnresolvedFormat, "No available format resolved for :dy"}}

# `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 *date* 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

* `date` is a `t:Date.t/0` struct or any map that contains one or more
  of the keys `:year`, `:month`, `:day` and optionally `:calendar`.

* `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 *dates* (that is, *dates* having `:year`,
    `:month`, `:day` and `:calendar` fields).

  * The default for partial *dates* is to derive a format skeleton from the
    *date* 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 date digits should
  be transliterated.

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

* `:era` which, if set to `:variant`, will use a variant for the era if one
  is available in the requested locale. In the `:en` locale, for example, `era: :variant`
  will return `CE` instead of `AD` and `BCE` instead of `BC`.

### 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.Date.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_date` or

* raises an exception.

### Examples

    iex> Cldr.Date.to_string!(~D[2017-07-10], MyApp.Cldr, locale: :en)
    "Jul 10, 2017"

    iex> Cldr.Date.to_string!(~D[2017-07-10], MyApp.Cldr, format: :medium, locale: :en)
    "Jul 10, 2017"

    iex> Cldr.Date.to_string!(~D[2017-07-10], MyApp.Cldr, format: :full, locale: :en)
    "Monday, July 10, 2017"

    iex> Cldr.Date.to_string!(~D[2017-07-10], MyApp.Cldr, format: :short, locale: :en)
    "7/10/17"

    iex> Cldr.Date.to_string!(~D[2017-07-10], MyApp.Cldr, format: :short, locale: "fr")
    "10/07/2017"

    iex> Cldr.Date.to_string!(~D[2024-03-01], format: :yMd, prefer: :variant, locale: "en-CA")
    "1/3/2024"

    # A partial date with a derived "best match" format
    iex> Cldr.Date.to_string!(%{year: 2024, month: 6}, MyApp.Cldr, locale: "fr")
    "6/2024"

    # A partial date with a best match CLDR-defined format
    iex> Cldr.Date.to_string!(%{year: 2024, month: 6}, MyApp.Cldr, format: :yMMM, locale: "fr")
    "juin 2024"

---

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