Cldr.Date (Cldr Dates & Times v2.24.2)

View Source

Provides localization and formatting of a 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.

CLDR provides standard format strings for Date.t/0 which are represented by the formats :short, :medium, :long and :full. This abstraction allows for locale-independent formatting since each locale and calendar may define the underlying format string as appropriate.

Summary

Functions

available_formats(locale \\ Cldr.get_locale(), calendar \\ Cldr.Calendar.default_cldr_calendar(), backend \\ Cldr.Date.default_backend())

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

formats(locale \\ Cldr.get_locale(), calendar \\ Cldr.Calendar.default_cldr_calendar(), backend \\ Cldr.Date.default_backend())

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

is_full_date(date)
to_string(date, backend \\ Cldr.Date.default_backend(), options \\ [])

Formats a date according to a format string as defined in CLDR and described in TR35.

to_string!(date, backend \\ Cldr.Date.default_backend(), options \\ [])

Formats a date according to a format string as defined in CLDR and described in TR35 or raises an exception.

Functions

available_formats(locale \\ Cldr.get_locale(), calendar \\ Cldr.Calendar.default_cldr_calendar(), backend \\ Cldr.Date.default_backend())

@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

Examples:

iex> Cldr.Date.available_formats(:en)
{:ok,
 %{
   d: "d",
   y: "y",
   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",
   MMMMd: "MMMM d",
   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",
     pluralize: :week_of_year,
     one: "'week' w 'of' Y"
   },
   MMMMW: %{
     other: "'week' W 'of' MMMM",
     pluralize: :week_of_month,
     one: "'week' W 'of' MMMM"
   }
 }}

formats(locale \\ Cldr.get_locale(), calendar \\ Cldr.Calendar.default_cldr_calendar(), backend \\ Cldr.Date.default_backend())

@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

Examples:

iex> Cldr.Date.formats(:en, :gregorian, MyApp.Cldr)
{:ok, %Cldr.Date.Formats{
  full: "EEEE, MMMM d, y",
  long: "MMMM d, y",
  medium: "MMM d, y",
  short: "M/d/yy"
}}

iex> Cldr.Date.formats(:en, :buddhist, MyApp.Cldr)
{:ok, %Cldr.Date.Formats{
  full: "EEEE, MMMM d, y G",
  long: "MMMM d, y G",
  medium: "MMM d, y G",
  short: "M/d/y GGGGG"
}}

is_full_date(date)

(macro)

to_string(date, backend \\ Cldr.Date.default_backend(), options \\ [])

@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 string as defined in CLDR and described in TR35.

Arguments

  • date is a 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 one of :short, :medium, :long, :full, or a format ID or a format string. 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 candidate format ID from the date and find the best match from the formats returned by Cldr.Date.available_formats/3. See here 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, "06/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!(date, backend \\ Cldr.Date.default_backend(), options \\ [])

@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 string as defined in CLDR and described in TR35 or raises an exception.

Arguments

  • date is a 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 one of :short, :medium, :long, :full, or a format ID or a format string. 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 candidate format from the date and find the best match from the formats returned by Cldr.Date.available_formats/3. See here for more information about specifying formats.

  • :locale is any valid locale name returned by Cldr.known_locale_names/0 or a 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")
"06/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"