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

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.

Format Definitions

Formatting a date, time or date_time requires an understanding of an end users expectations, the locale of the end user (cultural expectations) and the use case. Therefore the formatting implementataion needs to be flexible and powerful while at the same time be easy to understand and implement for a developer.

There are three ways to specify a format. They are summarized here from the most concrete and specific to the most high-level and abstract. Further details on each approach follow this section.

  • CLDR uses a format pattern to represent how a date, time and date_time should be formatted. Ultimately all format specifications are resolved to a format pattern into which a date, time and date_time is interpolated.

  • Since a format pattern represents a specific definition of how to format a date, time or date_time, a method of specifying a locale independent format is required. Such formats are called format skeletons. A format skeleton is an abstract way to express the contents of the desired format without knowing the concrete format pattern. Ultimately, a skeleton is resolved to a specific format pattern for a given locale and calendar.

  • Format patterns and format skeletons both require an understanding of format fields and format symbols which make up a format pattern. In many cases the formatting requirements are straight forward and can be reduced to the idea of "full", "long", "medium" and "short". Therefore, a format can be expressed using these terms with the reasonable expectation that the resulting formatted date/time/date_time will be acceptable. These are termed standard formats.

Hint

Formatting with the standard formats is recommended unless specific formatting requirements emerge.

Format Patterns

Format patterns are the foundation for expressing how a date or time is to be formatted. A format pattern is a string consisting of two types of elements:

  • Pattern fields, which repeat a specific pattern character one or more times. These fields are replaced with date and time data from a calendar when formatting. Currently, A..Z and a..z are reserved for use as pattern characters (unless they are quoted, see next item). The pattern characters currently defined, and the meaning of different fields lengths for then, are listed in the Date Field Symbol Table below.

  • Literal text, which is output as-is when formatting, and must closely match when parsing. Literal text can include:

    • Any characters other than A..Z and a..z, including spaces and punctuation.
    • Any text between single vertical quotes ('xxxx'), which may include A..Z and a..z as literal text.
    • Two adjacent single vertical quotes (''), which represent a literal single quote, either inside or outside quoted text.

The following are examples:

PatternResult (in a particular locale)
yyyy.MM.dd G 'at' HH:mm:ss zzz1996.07.10 AD at 15:08:56 PDT
EEE, MMM d, ''yyWed, July 10, '96
h:mm a12:08 PM
hh 'o''clock' a, zzzz12 o'clock PM, Pacific Daylight Time
K:mm a, z0:00 PM, PST.
yyyyy.MMMM.dd GGG hh:mm aaa01996.July.10 AD 12:08 PM

Format patterns are also defined for date_times however the format of those patterns is different from those for date and time. A date_time format pattern is a string with two placeholders into which the formatted date and formatted time are interpolated.

Format Skeletons

Format patterns are very flexible but they are not locale independent. Format skeletons are therefore used to specify only what format fields are to be formatted. The skeleton is then best matched to an entry in the map returned from Cldr.DateTime.available_formats/3 (and the similar Cldr.Date.available_formats/3 and Cldr.Time.available_formats/3 functions.

Skeletons define what, not how

Standard formats are the best place to start, with format skeletons the more specific choice when required. Think of format skeletons as a way to specify what is to be formatted, not how. The how will be resolved from best matching against the map returned from Cldr.DateTime.available_formats/3.

A format skeleton is an atom containing only field information, and in a canonical order. Examples are :yMMMM for year + full month, or :MMMd for abbreviated month + day. In the examples, MMM is a format field and M is a format symbol. Therfore a format field consists of one or more format symbols. In particular:

  • The format fields are composed of format symbols from the Format Symbol Table.
  • The canonical order is from top to bottom in that table; that is, "yM" not "My".
  • Only one field of each type is allowed; that is, "Hh" is not valid.

When specifiying a formal skeleton as the :format parameter to Cldr.DateTime.to_string/3 (and the Cldr.Date.to_string/3 and Cldr.Time.to_string/3 equivalents), the skeleton fields will be sorted into canonical order. Then the best match for that requested skeleton will be found using Cldr.DateTine.Format.Match.best_match/4. For example, the full month and year may be needed for a calendar application; the requested format skeleton is :MMMMyyyy, but the best match may be :yMMMM or even GyyMMMM, depending on the locale and calendar.

This "best match" skeleton is known as a format ID since it is guaranteed to be a key in the map returned by Cldr.DateTime.available_formats/3. The value in that map is a format pattern tinto which the given date/time/date_time can be interpolated.

Standard Formats

Standard formats are defined for date and time which, in both cases, resolves to a format skeleton. For date_time, the resolved format is a string including placeholders.

Date and Time Standard Formats

Standard date and time formats are defined as an abstraction encapsulating a reasonable default choice for any locale. There are four standard formats:

  • :full (usually with weekday name),
  • :long (with wide month name),
  • :medium, and
  • :short (usually with numeric month).

Each of the date and time standard formats resolves to a format skeleton which is the same for every locale. The format skeleton is then resolved to the best match format ID for the desired locale and from there to a format pattern for interpolation.

DateTime Standard Formats

Standard date_time formats encapsulate how to combine a formatted date and a formatted time into a single formatted date_time. Like date and time standard formats, the four standard formats for a date_time are :full, :long, :medium and :short. However in this case the formats are strings containing placeholders into which the formatted date and formatted time are interpolated.

An example is "{1} 'at' {0}" where {1} will be replaced by the formatted date and {0} will be replaced by the formatted time.

Summary

Types

date_time_format_pattern()

A date_time format pattern is a string with placeholders for the date part and the time part in addition to literal text. For example, "{1} 'at' {0}" where {1} will be replaced by the formatted date and {0} will be replaced by the formatted time.

date_time_standard_formats()

The date_time standard formats of :full, :long, :medium and :short are used to resolve standard formats for a date_time in a locale independent way. They resolve to a string with placeholders into which a formatted date and a formatted time are interpolated.

format_id()

A format ID is a format skeleton that is guaranteed to be a valid key into the map returned by Cldr.DateTime.available_formats/3 (or Cldr.Date.available_formats/3 or Cldr.Time.available_formats/3 as appropriate).

format_pattern()

A format pattern for a date or time is a string which is composed of one or more format fields and possibly literal text.

format_skeleton()

A format skeleton is an atom consisting of one or more format fields that are themselves composed of one or more format symbols Format skeletons are used to find the best match format from the list of formats returned by Cldr.DateTime.Format.date_time_available_formats/3.

standard_formats()

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

Functions

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

Returns a list of CLDR calendars defined for a given locale.

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

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

common_date_time_format_names() deprecated

See Cldr.DateTime.Format.common_date_time_format_ids/0.

common_date_time_format_names(backend) deprecated

See Cldr.DateTime.Format.common_date_time_format_ids/1.

date_format(options \\ [])

Returns a format skeleton for a given date, locale and standard format.

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 date_time format for a given locale and standard format.

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.

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

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

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_unknown_format(locale \\ Cldr.get_locale(), backend \\ Cldr.Date.default_backend())

Returns the localized string for GMT for a for an unkown GMT offset.

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

Returns the localised string for GMT 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.

time_format(options \\ [])

Returns a format skeleton for a given time, locale and standard format.

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 time zone 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. This format is used to format a time zone such as "Pacific Time (Canada)".

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

Returns the regional format for formatting time zones. This data is used to format time zones such as "France Daylight Time" or "Japan Time".

Types

date_time_format_pattern()

@type date_time_format_pattern() :: String.t()

A date_time format pattern is a string with placeholders for the date part and the time part in addition to literal text. For example, "{1} 'at' {0}" where {1} will be replaced by the formatted date and {0} will be replaced by the formatted time.

date_time_standard_formats()

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

The date_time standard formats of :full, :long, :medium and :short are used to resolve standard formats for a date_time in a locale independent way. They resolve to a string with placeholders into which a formatted date and a formatted time are interpolated.

format_id()

@type format_id() :: format_skeleton()

A format ID is a format skeleton that is guaranteed to be a valid key into the map returned by Cldr.DateTime.available_formats/3 (or Cldr.Date.available_formats/3 or Cldr.Time.available_formats/3 as appropriate).

format_pattern()

@type format_pattern() :: String.t()

A format pattern for a date or time is a string which is composed of one or more format fields and possibly literal text.

In the example format pattern "yy/M/d", the format fields are yy, M and d and the two / are literals.

Each of the format fields is composed of one or more format symbols which in this example are y, M and d.

format_skeleton()

@type format_skeleton() :: atom()

A format skeleton is an atom consisting of one or more format fields that are themselves composed of one or more format symbols Format skeletons are used to find the best match format from the list of formats returned by Cldr.DateTime.Format.date_time_available_formats/3.

An example format skeleton is :yyMd which has the format fields yy, M and d. It can can be best-matched to a locale-specific format ID.

standard_formats()

@type standard_formats() :: %{
  full: format_skeleton(),
  long: format_skeleton(),
  medium: format_skeleton(),
  short: format_skeleton()
}

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

Functions

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 CLDR 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_ids(backend \\ Cldr.Date.default_backend())

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

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

The format IDs returned by common_date_time_format_ids/0 are guaranteed to be available in all known locales,

Example:

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

common_date_time_format_names()

This function is deprecated. Use common_date_time_format_ids/0.

See Cldr.DateTime.Format.common_date_time_format_ids/0.

common_date_time_format_names(backend)

This function is deprecated. Use common_date_time_format_ids/1.

See Cldr.DateTime.Format.common_date_time_format_ids/1.

date_format(options \\ [])

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

Returns a format skeleton for a given date, locale and standard format.

Arguments

  • options is a keyword list of options.

Options

Returns

  • {:ok, format_skeleton} or

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

Examples

iex> Cldr.DateTime.Format.date_format()
{:ok, :yMMMd}

iex> Cldr.DateTime.Format.date_format(format: :full)
{:ok, :yMMMMEEEEd}

iex> Cldr.DateTime.Format.date_format(locale: :de, format: :full)
{:ok, :yMMMMEEEEd}

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{
   short: :yyMd,
   medium: :yMMMd,
   long: :yMMMMd,
   full: :yMMMMEEEEd
 }}

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

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, date_time_standard_formats()} | {: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{
   short: "{1}, {0}",
   medium: "{1}, {0}",
   long: "{1} 'at' {0}",
   full: "{1} 'at' {0}"
 }}

iex> Cldr.DateTime.Format.date_time_at_formats(:en, :buddhist, MyApp.Cldr)
{:ok,
 %Cldr.DateTime.Formats{
   short: "{1}, {0}",
   medium: "{1}, {0}",
   long: "{1} 'at' {0}",
   full: "{1} 'at' {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,
 %{
   yQQQ: "QQQ y",
   yyMd: "M/d/yy",
   hmv: %{unicode: "h:mm a v", ascii: "h:mm a v"},
   Bh: "h B",
   y: "y",
   M: "L",
   MMMMW: %{
     other: "'week' W 'of' MMMM",
     one: "'week' W 'of' MMMM",
     pluralize: :week_of_month
   },
   Hv: "HH'h' v",
   hms: %{unicode: "h:mm:ss a", ascii: "h:mm:ss a"},
   hv: %{unicode: "h a v", ascii: "h a v"},
   hm: %{unicode: "h:mm a", ascii: "h:mm a"},
   Hmv: "HH:mm v",
   hmsv: %{unicode: "h:mm:ss a v", ascii: "h:mm:ss a v"},
   EBhm: "E h:mm B",
   ahmmss: %{unicode: "h:mm:ss a", ascii: "h:mm:ss a"},
   GyMMMEd: "E, MMM d, y G",
   Bhms: "h:mm:ss B",
   GyMEd: "E, M/d/y G",
   MMMMd: "MMMM d",
   Hm: "HH:mm",
   Ed: "d E",
   GyM: "M/y G",
   GyMMMd: "MMM d, y G",
   Bhm: "h:mm B",
   yMMMEd: "E, MMM d, y",
   h: %{unicode: "h a", ascii: "h a"},
   yMMMM: "MMMM y",
   yMEd: "E, M/d/y",
   Ehm: %{unicode: "E h:mm a", ascii: "E h:mm a"},
   MEd: "E, M/d",
   d: "d",
   EHms: "E HH:mm:ss",
   yQQQQ: "QQQQ y",
   yMMMMd: "MMMM d, y",
   yMMM: "MMM y",
   yMMMd: "MMM d, y",
   GyMMM: "MMM y G",
   Hmsv: "HH:mm:ss v",
   ahmm: %{unicode: "h:mm a", ascii: "h:mm a"},
   Md: "M/d",
   yMMMMEEEEd: "EEEE, MMMM d, y",
   yMd: "M/d/y",
   ahmmsszzzz: %{unicode: "h:mm:ss a zzzz", ascii: "h:mm:ss a zzzz"},
   EBhms: "E h:mm:ss B",
   ahmmssz: %{unicode: "h:mm:ss a z", ascii: "h:mm:ss a z"},
   ms: "mm:ss",
   yw: %{
     other: "'week' w 'of' Y",
     one: "'week' w 'of' Y",
     pluralize: :week_of_year
   },
   MMMd: "MMM d",
   Gy: "y G",
   GyMd: "M/d/y G",
   EHm: "E HH:mm",
   yM: "M/y",
   MMM: "LLL",
   H: "HH",
   Hms: "HH:mm:ss",
   EBh: "E h B",
   E: "ccc",
   Eh: %{unicode: "E h a", ascii: "E h a"},
   MMMEd: "E, MMM d",
   Ehms: %{unicode: "E h:mm:ss a", ascii: "E h:mm:ss a"}
 }}

date_time_format(options \\ [])

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

Returns a date_time format for a given locale and standard format.

Arguments

  • options is a keyword list of options.

Options

Returns

  • {:ok, date_time_format_pattern} 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, date_time_standard_formats()} | {: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}"
}}

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

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

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

Arguments

Examples:

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

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

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_unknown_format(locale \\ Cldr.get_locale(), backend \\ Cldr.Date.default_backend())

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

Returns the localized string for GMT for a for an unkown GMT offset.

Arguments

Example

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

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 localised string for GMT 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

time_format(options \\ [])

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

Returns a format skeleton for a given time, locale and standard format.

Arguments

  • options is a keyword list of options.

Options

Returns

  • {:ok, format_skeleton} or

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

Examples

iex> Cldr.DateTime.Format.time_format()
{:ok, :ahmmss}

iex> Cldr.DateTime.Format.time_format(format: :full)
{:ok, :ahmmsszzzz}

iex> Cldr.DateTime.Format.time_format(format: :full, locale: :ja)
{:ok, :Hmmsszzzz}

iex> Cldr.DateTime.Format.time_format(format: :full, prefer: :unicode)
{:ok, :ahmmsszzzz}

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{
   short: :ahmm,
   medium: :ahmmss,
   long: :ahmmssz,
   full: :ahmmsszzzz
 }}

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

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 time zone 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. This format is used to format a time zone such as "Pacific Time (Canada)".

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. This data is used to format time zones such as "France Daylight Time" or "Japan Time".

Arguments

Example

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