View Source Cldr.DateTime.Format (Cldr Dates & Times v2.20.3)

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

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.

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

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

Functions

Returns a list of calendars defined for a given locale.

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

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

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

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

Types

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

@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

@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

Link to this function

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

View Source (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.

Link to this function

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

View Source
@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, :japanese, :persian, :roc]}
Link to this function

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

View Source
@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]
Link to this function

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

View Source
@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"
}}
Link to this function

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

View Source
@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}"}
}
Link to this function

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

View Source
@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"
 }}
Link to this function

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

View Source
@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}"
}}
Link to this macro

different_but_compatible(token_a, token_b)

View Source (macro)
Link to this macro

different_types(token_a, token_b)

View Source (macro)
Link to this function

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

View Source
@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]}
Link to this function

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

View Source
@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"}
Link to this function

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

View Source
@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"}}
Link to this function

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

View Source
@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"]},
   ...
Link to this macro

same_types(token_a, token_b)

View Source (macro)
Link to this function

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

View Source
@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: "h:mm:ss a zzzz",
  long: "h:mm:ss a z",
  medium: "h:mm:ss a",
  short: "h:mm a"
}}

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