Cldr.DateTime.Format (Cldr Dates & Times v2.23.0)

View Source

Manages the Date, Time and DateTime formats defined by CLDR.

The functions in Cldr.DateTime.Format are primarily concerned with encapsulating the data from CLDR in functions that are used during the formatting process.

Summary

Types

format_id()

A format_id is an atom that indexes into the map returned by Cldr.DateTime.Format.date_time_available_formats/3 to resolve a format string.

format_skeleton()

A format skeleton is a string consisting of format symbols which is used to find the best match from the list of formats returned by Cldr.DateTime.Format.date_time_available_formats/3

standard_formats()

The standard formats of :full, :long, :medium and :short are used to resolve standard formats in a locale independent way.

Functions

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

Find the best match for a requested format.

calendars_for(locale \\ Cldr.get_locale(), backend \\ Cldr.Date.default_backend())

Returns a list of calendars defined for a given locale.

common_date_time_format_names(backend \\ Cldr.Date.default_backend())

Returns a list of the date_time format types that are available in all known locales.

date_format(options \\ [])

Returns a date format for a given locale and format style.

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

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

Returns a map of the standard datetime "at" formats for a given locale and calendar.

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

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

date_time_format(options \\ [])

Returns a datetime format for a given locale and format style.

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

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

different_but_compatible(token_a, token_b)
different_types(token_a, token_b)
gmt_format(locale \\ Cldr.get_locale(), backend \\ Cldr.Date.default_backend())

Returns the GMT offset format list for a for a timezone offset for a given locale.

gmt_zero_format(locale \\ Cldr.get_locale(), backend \\ Cldr.Date.default_backend())

Returns the GMT format string for a for a timezone with an offset of zero for a given locale.

hour_format(locale \\ Cldr.get_locale(), backend \\ Cldr.Date.default_backend())

Returns the positive and negative hour format for a timezone offset for a given locale.

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

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

metazones(locale \\ Cldr.get_locale(), backend \\ Cldr.Date.default_backend())

Returns the metazone data for a locale.

same_types(token_a, token_b)
time_format(options \\ [])

Returns a date format for a given locale and format style.

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

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

timezones(locale \\ Cldr.get_locale(), backend \\ Cldr.Date.default_backend())

Returns the timezone display data for a locale.

zone_fallback_format(locale \\ Cldr.get_locale(), backend \\ Cldr.Date.default_backend())

Returns the time zone fallback format for formatting time zones.

zone_region_format(locale \\ Cldr.get_locale(), backend \\ Cldr.Date.default_backend())

Returns the regional format for formatting time zones.

Types

format_id()

@type format_id() :: atom()

A format_id is an atom that indexes into the map returned by Cldr.DateTime.Format.date_time_available_formats/3 to resolve a format string.

format_skeleton()

@type format_skeleton() :: atom()

A format skeleton is a string consisting of format symbols which is used to find the best match from the list of formats returned by Cldr.DateTime.Format.date_time_available_formats/3

standard_formats()

@type standard_formats() :: %{
  full: String.t(),
  long: String.t(),
  medium: String.t(),
  short: String.t()
}

The standard formats of :full, :long, :medium and :short are used to resolve standard formats in a locale independent way.

Functions

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

(since 2.19.0) 
@spec best_match(
  skeleton :: format_skeleton(),
  locale :: Cldr.Locale.locale_reference(),
  calendar :: Cldr.Calendar.calendar(),
  backend :: Cldr.backend()
) :: {:ok, format_id()} | {:error, {module(), String.t()}}

Find the best match for a requested format.

calendars_for(locale \\ Cldr.get_locale(), backend \\ Cldr.Date.default_backend())

@spec calendars_for(Cldr.Locale.locale_reference(), Cldr.backend()) ::
  {:ok, [Cldr.Calendar.calendar(), ...]} | {:error, {atom(), String.T}}

Returns a list of calendars defined for a given locale.

Arguments

Example

iex> Cldr.DateTime.Format.calendars_for(:en, MyApp.Cldr)
{:ok, [:buddhist, :chinese, :coptic, :dangi, :ethiopic, :ethiopic_amete_alem,
 :generic, :gregorian, :hebrew, :indian, :islamic, :islamic_civil,
 :islamic_rgsa, :islamic_tbla, :islamic_umalqura, :iso8601, :japanese, :persian, :roc]}

common_date_time_format_names(backend \\ Cldr.Date.default_backend())

@spec common_date_time_format_names(backend :: Cldr.backend()) :: [format_id()]

Returns a list of the date_time format types that are available in all known locales.

The format types returned by common_date_time_format_names are guaranteed to be available in all known locales,

Example:

iex> Cldr.DateTime.Format.common_date_time_format_names()
[:Bh, :Bhm, :Bhms, :E, :EBhm, :EBhms, :EHm, :EHms, :Ed, :Ehm, :Ehms, :Gy,
 :GyMMM, :GyMMMEd, :GyMMMd, :GyMd, :H, :Hm, :Hms, :Hmsv, :Hmv, :M, :MEd, :MMM,
 :MMMEd, :MMMMW, :MMMMd, :MMMd, :Md, :d, :h, :hm, :hms, :hmsv, :hmv, :ms, :y,
 :yM, :yMEd, :yMMM, :yMMMEd, :yMMMM, :yMMMd, :yMd, :yQQQ, :yQQQQ, :yw]

date_format(options \\ [])

(since 2.23.0) 
@spec date_format(options :: Keyword.t()) ::
  {:ok, String.t()} | {:error, {module(), String.t()}}
@spec date_format(options :: Keyword.t()) ::
  {:ok, String.t()} | {:error, {module(), String.t()}}

Returns a date format for a given locale and format style.

Arguments

  • options is a keyword list of options.

Options

Returns

  • {:ok, format_string} or

  • {:error, {exception, reason}}.

Examples

iex> Cldr.DateTime.Format.date_format
{:ok, "MMM d, y"}

iex> Cldr.DateTime.Format.date_format format: :full
{:ok, "EEEE, MMMM d, y"}

iex> Cldr.DateTime.Format.date_format locale: :de, format: :full
{:ok, "EEEE, d. MMMM y"}

iex> Cldr.DateTime.Format.date_format locale: :de, format: :unknown
{:error,
 {Cldr.DateTime.UnresolvedFormat, "Unknown value for option format: :unknown"}}

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

@spec date_formats(
  Cldr.Locale.locale_reference(),
  Cldr.Calendar.calendar(),
  Cldr.backend()
) :: {:ok, standard_formats()} | {:error, {atom(), String.t()}}

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

Arguments

Examples:

iex> Cldr.DateTime.Format.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.DateTime.Format.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"
}}

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

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

Returns a map of the standard datetime "at" formats for a given locale and calendar.

An "at" format is one where the datetime is formatted with the date part separated from the time part by a localized version of "at".

Arguments

Examples:

iex> Cldr.DateTime.Format.date_time_at_formats(:en)
{:ok, %Cldr.DateTime.Formats{
  full: "{1} 'at' {0}",
  long: "{1} 'at' {0}",
  medium: "{1}, {0}",
  short: "{1}, {0}"}
}

iex> Cldr.DateTime.Format.date_time_at_formats(:en, :buddhist, MyApp.Cldr)
{:ok, %Cldr.DateTime.Formats{
  full: "{1} 'at' {0}",
  long: "{1} 'at' {0}",
  medium: "{1}, {0}",
  short: "{1}, {0}"}
}

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

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

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

Arguments

Examples:

iex> Cldr.DateTime.Format.date_time_available_formats(:en)
{:ok,
 %{
   yw: %{
     other: "'week' w 'of' Y",
     one: "'week' w 'of' Y",
     pluralize: :week_of_year
   },
   GyMMMEd: "E, MMM d, y G",
   Hms: "HH:mm:ss",
   MMMMW: %{
     other: "'week' W 'of' MMMM",
     one: "'week' W 'of' MMMM",
     pluralize: :week_of_month
   },
   E: "ccc",
   MMMd: "MMM d",
   yMEd: "E, M/d/y",
   yQQQ: "QQQ y",
   Ehm: %{unicode: "E h:mm a", ascii: "E h:mm a"},
   M: "L",
   hm: %{unicode: "h:mm a", ascii: "h:mm a"},
   yM: "M/y",
   GyMMMd: "MMM d, y G",
   GyMd: "M/d/y G",
   Gy: "y G",
   Hm: "HH:mm",
   EBhms: "E h:mm:ss B",
   d: "d",
   hms: %{unicode: "h:mm:ss a", ascii: "h:mm:ss a"},
   Ed: "d E",
   Ehms: %{unicode: "E h:mm:ss a", ascii: "E h:mm:ss a"},
   EHms: "E HH:mm:ss",
   Bh: "h B",
   h: %{unicode: "h a", ascii: "h a"},
   Bhms: "h:mm:ss B",
   Hmv: "HH:mm v",
   hmv: %{unicode: "h:mm a v", ascii: "h:mm a v"},
   yMd: "M/d/y",
   ms: "mm:ss",
   MMM: "LLL",
   y: "y",
   Bhm: "h:mm B",
   yMMM: "MMM y",
   yQQQQ: "QQQQ y",
   yMMMEd: "E, MMM d, y",
   yMMMM: "MMMM y",
   EBhm: "E h:mm B",
   Hmsv: "HH:mm:ss v",
   yMMMd: "MMM d, y",
   MEd: "E, M/d",
   EHm: "E HH:mm",
   GyMMM: "MMM y G",
   hmsv: %{unicode: "h:mm:ss a v", ascii: "h:mm:ss a v"},
   H: "HH",
   Md: "M/d",
   MMMEd: "E, MMM d",
   MMMMd: "MMMM d"
 }}

date_time_format(options \\ [])

(since 2.23.0) 
@spec date_time_format(options :: Keyword.t()) ::
  {:ok, String.t()} | {:error, {module(), String.t()}}

Returns a datetime format for a given locale and format style.

Arguments

  • options is a keyword list of options.

Options

Returns

  • {:ok, format_string} or

  • {:error, {exception, reason}}.

Examples

iex> Cldr.DateTime.Format.date_time_format
{:ok, "{1}, {0}"}

iex> Cldr.DateTime.Format.date_time_format format: :full
{:ok, "{1}, {0}"}

iex> Cldr.DateTime.Format.date_time_format locale: :de, format: :full
{:ok, "{1}, {0}"}

iex> Cldr.DateTime.Format.date_time_format locale: :de, format: :unknown
{:error,
 {Cldr.DateTime.UnresolvedFormat, "Unknown value for option format: :unknown"}}

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

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

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

Arguments

Examples:

iex> Cldr.DateTime.Format.date_time_formats(:en)
{:ok, %Cldr.DateTime.Formats{
  full: "{1}, {0}",
  long: "{1}, {0}",
  medium: "{1}, {0}",
  short: "{1}, {0}"
}}

iex> Cldr.DateTime.Format.date_time_formats(:en, :buddhist, MyApp.Cldr)
{:ok, %Cldr.DateTime.Formats{
  full: "{1}, {0}",
  long: "{1}, {0}",
  medium: "{1}, {0}",
  short: "{1}, {0}"
}}

different_but_compatible(token_a, token_b)

(macro)

different_types(token_a, token_b)

(macro)

gmt_format(locale \\ Cldr.get_locale(), backend \\ Cldr.Date.default_backend())

@spec gmt_format(Cldr.Locale.locale_reference(), Cldr.backend()) ::
  {:ok, [non_neg_integer() | String.t(), ...]}

Returns the GMT offset format list for a for a timezone offset for a given locale.

Arguments

Example

iex> Cldr.DateTime.Format.gmt_format(:en, MyApp.Cldr)
{:ok, ["GMT", 0]}

gmt_zero_format(locale \\ Cldr.get_locale(), backend \\ Cldr.Date.default_backend())

@spec gmt_zero_format(Cldr.Locale.locale_reference(), Cldr.backend()) ::
  {:ok, String.t()} | {:error, {atom(), String.t()}}

Returns the GMT format string for a for a timezone with an offset of zero for a given locale.

Arguments

Example

iex> Cldr.DateTime.Format.gmt_zero_format(:en, MyApp.Cldr)
{:ok, "GMT"}

hour_format(locale \\ Cldr.get_locale(), backend \\ Cldr.Date.default_backend())

@spec hour_format(Cldr.Locale.locale_reference(), Cldr.backend()) ::
  {:ok, {String.t(), String.t()}} | {:error, {atom(), String.t()}}

Returns the positive and negative hour format for a timezone offset for a given locale.

Arguments

Example

iex> Cldr.DateTime.Format.hour_format(:en, MyApp.Cldr)
{:ok, {"+HH:mm", "-HH:mm"}}

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

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

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

Arguments

Examples:

Cldr.DateTime.Format.interval_formats(:en, :gregorian, MyApp.Cldr)
=> {:ok,
 %{
   bh: %{b: ["h B", "h B"], h: ["h", "h B"]},
   bhm: %{b: ["h:mm B", "h:mm B"], h: ["h:mm", "h:mm B"], m: ["h:mm", "h:mm B"]},
   d: %{d: ["d", "d"]},
   gy: %{g: ["y G", "y G"], y: ["y", "y G"]},
   ...

metazones(locale \\ Cldr.get_locale(), backend \\ Cldr.Date.default_backend())

(since 2.33.0) 
@spec metazones(Cldr.Locale.locale_reference(), Cldr.backend()) ::
  {:ok, map()} | {:error, {atom(), String.t()}}

Returns the metazone data for a locale.

Arguments

same_types(token_a, token_b)

(macro)

time_format(options \\ [])

(since 2.23.0)

Returns a date format for a given locale and format style.

Arguments

  • options is a keyword list of options.

Options

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

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

  • :format is the format style requested. The valid values are :short, :medium, :long or :full. The default is :medium.

  • :prefer is either :unicode (the default) or :ascii. When a locale offers both a unicode and ascii variant of the requested format style, the preferred variant is returned if one is available for the given locale. If the preferred variant is not available then the ascii version is returned.

Returns

  • {:ok, format_string} or

  • {:error, {exception, reason}}.

Examples

iex> Cldr.DateTime.Format.time_format
{:ok, "h:mm:ss a"}

iex> Cldr.DateTime.Format.time_format(format: :full)
{:ok, "h:mm:ss a zzzz"}

iex> Cldr.DateTime.Format.time_format(format: :full, locale: :ja)
{:ok, "H時mm分ss秒 zzzz"}

iex> Cldr.DateTime.Format.time_format(format: :full, prefer: :unicode)
{:ok, "h:mm:ss a zzzz"}

iex> Cldr.DateTime.Format.time_format format: :unknown
{:error,
 {Cldr.DateTime.UnresolvedFormat, "Unknown value for option format: :unknown"}}

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

@spec time_formats(
  Cldr.Locale.locale_name() | String.t() | Cldr.LanguageTag,
  Cldr.Calendar.calendar(),
  Cldr.backend()
) :: {:ok, standard_formats()} | {:error, {atom(), String.t()}}

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

Arguments

Examples:

iex> Cldr.DateTime.Format.time_formats(:en)
{
  :ok,
  %Cldr.Time.Formats{
    full: %{unicode: "h:mm:ss a zzzz", ascii: "h:mm:ss a zzzz"},
    long: %{unicode: "h:mm:ss a z", ascii: "h:mm:ss a z"},
    medium: %{unicode: "h:mm:ss a", ascii: "h:mm:ss a"},
    short: %{unicode: "h:mm a", ascii: "h:mm a"}
  }
}

iex> Cldr.DateTime.Format.time_formats(:en, :buddhist)
{
  :ok,
  %Cldr.Time.Formats{
    full: %{unicode: "h:mm:ss a zzzz", ascii: "h:mm:ss a zzzz"},
    long: %{unicode: "h:mm:ss a z", ascii: "h:mm:ss a z"},
    medium: %{unicode: "h:mm:ss a", ascii: "h:mm:ss a"},
    short: %{unicode: "h:mm a", ascii: "h:mm a"}
  }
}

timezones(locale \\ Cldr.get_locale(), backend \\ Cldr.Date.default_backend())

(since 2.33.0) 
@spec timezones(Cldr.Locale.locale_reference(), Cldr.backend()) ::
  {:ok, map()} | {:error, {atom(), String.t()}}

Returns the timezone display data for a locale.

Arguments

zone_fallback_format(locale \\ Cldr.get_locale(), backend \\ Cldr.Date.default_backend())

(since 2.33.0) 
@spec zone_fallback_format(Cldr.Locale.locale_reference(), Cldr.backend()) ::
  {:ok, list()} | {:error, {atom(), String.t()}}

Returns the time zone fallback format for formatting time zones.

Arguments

Example

iex> Cldr.DateTime.Format.zone_fallback_format(:en, MyApp.Cldr)
{:ok, [1, " (", 0, ")"]}

zone_region_format(locale \\ Cldr.get_locale(), backend \\ Cldr.Date.default_backend())

(since 2.33.0) 
@spec zone_region_format(Cldr.Locale.locale_reference(), Cldr.backend()) ::
  {:ok, %{daylight: list(), generic: list(), standard: list()}}
  | {:error, {atom(), String.t()}}

Returns the regional format for formatting time zones.

Arguments

Example

iex> Cldr.DateTime.Format.zone_region_format(:en, MyApp.Cldr)
{:ok,
 %{
   standard: [0, " Standard Time"],
   generic: [0, " Time"],
   daylight: [0, " Daylight Time"]
 }}