View Source Bonfire.Common.Localise.Cldr.Calendar (Bonfire v0.9.10-classic-beta.156)

Data functions to retrieve localised calendar information.

Cldr defines formats for several calendars, the names of which are returned by Cldr.known_calendars/0.

Currently this implementation only supports the :gregorian, :persian, :coptic and ethiopic calendars.

The :gregorian calendar aligns with the proleptic Gregorian calendar defined by Elixir, Calendar.ISO.

Summary

Functions

Link to this function

calendar_from_locale(locale)

View Source

Return the calendar module for a locale.

Arguments

  • :locale is any locale or locale name validated by Cldr.validate_locale/2. The default is Cldr.get_locale() which returns the locale set for the current process

Returns

  • {:ok, calendar_module} or

  • {:error, {exception, reason}}

Examples

iex> Bonfire.Common.Localise.Cldr.Calendar.calendar_from_locale "en-GB"
{:ok, Cldr.Calendar.GB}

iex> Bonfire.Common.Localise.Cldr.Calendar.calendar_from_locale "en-GB-u-ca-gregory"
{:ok, Cldr.Calendar.Gregorian}

iex> Bonfire.Common.Localise.Cldr.Calendar.calendar_from_locale "en"
{:ok, Cldr.Calendar.US}

iex> Bonfire.Common.Localise.Cldr.Calendar.calendar_from_locale "fa-IR"
{:ok, Cldr.Calendar.Persian}
Link to this function

calendar_from_territory(territory)

View Source

Returns the calendar module preferred for a territory.

Arguments

  • territory is any valid ISO3166-2 code as an String.t or upcased atom()

Returns

  • {:ok, calendar_module} or

  • {:error, {exception, reason}}

Examples

iex> Bonfire.Common.Localise.Cldr.Calendar.calendar_from_territory(:US)
{:ok, Cldr.Calendar.US}

iex> Bonfire.Common.Localise.Cldr.Calendar.calendar_from_territory :XX
{:error, {Cldr.UnknownTerritoryError, "The territory :XX is unknown"}}

Notes

The overwhelming majority of territories have :gregorian as their first preferred calendar and therefore Cldr.Calendar.Gregorian will be returned for most territories.

Returning any other calendar module would require:

  1. That another calendar is preferred over :gregorian for a territory

  2. That a calendar module is available to support that calendar.

As an example, Iran (territory :IR) prefers the :persian calendar. If the optional library ex_cldr_calendars_persian is installed, the calendar module Cldr.Calendar.Persian will be returned. If it is not installed, Cldr.Calendar.Gregorian will be returned as :gregorian is the second preference for :IR.

Link to this function

cyclic_years(locale \\ Bonfire.Common.Localise.Cldr.get_locale(), calendar \\ :gregorian)

View Source
Link to this function

day_periods(locale \\ Bonfire.Common.Localise.Cldr.get_locale(), calendar \\ :gregorian)

View Source
Link to this function

days(locale \\ Bonfire.Common.Localise.Cldr.get_locale(), calendar \\ :gregorian)

View Source
Link to this function

eras(locale \\ Bonfire.Common.Localise.Cldr.get_locale(), calendar \\ :gregorian)

View Source
Link to this function

localize(date)

View Source (since 1.25.0)
@spec localize(Cldr.Calendar.any_date_time()) ::
  {:ok, Date.t()}
  | {:error, :incompatible_calendars}
  | {:error, {module(), String.t()}}

Localize a date by converting it to calendar introspected from the provided or default locale.

Arguments

Options

Returns

  • {:ok, date} where date is converted into the calendar associated with the current or provided locale.

Examples

iex> Bonfire.Common.Localise.Cldr.Calendar.localize ~D[2022-06-09], locale: "fr"
{:ok, %Date{year: 2022, month: 6, day: 9, calendar: Cldr.Calendar.FR}}
Link to this function

localize(datetime, options)

View Source
@spec localize(Cldr.Calendar.any_date_time(), Keyword.t() | Cldr.Calendar.part()) ::
  {:ok, Date.t()}
  | {:error, :incompatible_calendars}
  | {:error, {module(), String.t()}}
Link to this function

localize(datetime, part, options \\ [])

View Source (since 1.25.0)
@spec localize(Cldr.Calendar.any_date_time(), Cldr.Calendar.part(), Keyword.t()) ::
  String.t()
  | {:error, :incompatible_calendars}
  | {:error, {module(), String.t()}}
@spec localize(
  datetime :: Cldr.Calendar.any_date_time(),
  part :: Cldr.Calendar.part(),
  options :: Keyword.t()
) ::
  String.t()
  | [Cldr.Calendar.day_of_week_to_binary()]
  | {:error, {module(), String.t()}}

Returns a localized string for a part of a Date.t/0.

Arguments

  • date is any Date.t/0.

  • part is one of :era, :quarter, :month, :day_of_week or :days_of_week.

  • options is a Keyword.t/0 list of options.

Options

  • :locale is any valid locale name in the list returned by Cldr.known_locale_names/1 or a Cldr.LanguageTag struct returned by Cldr.Locale.new!/2. The default is Cldr.get_locale().

  • :format is one of :wide, :abbreviated or :narrow. The default is :abbreviated.

  • :era will, if set to :variant will localize the era using the variant data. In the :en locale, this will produce CE and BCE rather than the default AD and BC.

Returns

  • A string representing the localized date part, or

  • A list of strings representing the days of the week for when part is :days_of_week. The days are in week order for the given date's calendar, or

  • {error, {exception, reason}} if an error is detected

Examples

iex> Bonfire.Common.Localise.Cldr.Calendar.localize ~D[2019-01-01], :era
"AD"

iex> Bonfire.Common.Localise.Cldr.Calendar.localize ~D[2019-01-01], :era, era: :variant
"CE"

iex> Bonfire.Common.Localise.Cldr.Calendar.localize ~D[2019-01-01], :day_of_week
"Tue"

iex> Bonfire.Common.Localise.Cldr.Calendar.localize ~D[0001-01-01], :day_of_week
"Mon"

iex> Bonfire.Common.Localise.Cldr.Calendar.localize ~D[2019-01-01], :days_of_week
[{1, "Mon"}, {2, "Tue"}, {3, "Wed"}, {4, "Thu"}, {5, "Fri"}, {6, "Sat"}, {7, "Sun"}]

iex> Bonfire.Common.Localise.Cldr.Calendar.localize ~D[2019-06-01], :era
"AD"

iex> Bonfire.Common.Localise.Cldr.Calendar.localize ~D[2019-06-01], :quarter
"Q2"

iex> Bonfire.Common.Localise.Cldr.Calendar.localize ~D[2019-06-01], :month
"Jun"

iex> Bonfire.Common.Localise.Cldr.Calendar.localize ~D[2019-06-01], :day_of_week
"Sat"

iex> Bonfire.Common.Localise.Cldr.Calendar.localize ~D[2019-06-01], :day_of_week, format: :wide
"Saturday"

iex> Bonfire.Common.Localise.Cldr.Calendar.localize ~D[2019-06-01], :day_of_week, format: :narrow
"S"

iex> Bonfire.Common.Localise.Cldr.Calendar.localize ~D[2019-06-01], :day_of_week, locale: "ar"
"السبت"
Link to this function

month_patterns(locale \\ Bonfire.Common.Localise.Cldr.get_locale(), calendar \\ :gregorian)

View Source
Link to this function

months(locale \\ Bonfire.Common.Localise.Cldr.get_locale(), calendar \\ :gregorian)

View Source
Link to this function

quarters(locale \\ Bonfire.Common.Localise.Cldr.get_locale(), calendar \\ :gregorian)

View Source
Link to this function

strftime_options!(locale \\ Bonfire.Common.Localise.Cldr.get_locale(), options \\ [])

View Source

Returns a keyword list of options than can be applied to NimbleStrftime.format/3.

The hex package nimble_strftime provides a format/3 function to format dates, times and datetimes. It takes a set of options that can return day, month and am/pm names.

strftime_options! returns a keyword list than can be used as these options to return localised names for days, months and am/pm.

Arguments

  • locale is any locale returned by MyApp.Cldr.known_locale_names/0. The default is MyApp.Cldr.get_locale/0

  • options is a set of keyword options. The default is []

Options

  • :calendar is the name of any known CLDR calendar. The default is :gregorian.

Example

iex: MyApp.Cldr.Calendar.strftime_options!()
[
  am_pm_names: #Function<0.32021692/1 in MyApp.Cldr.Calendar.strftime_options/2>,
  month_names: #Function<1.32021692/1 in MyApp.Cldr.Calendar.strftime_options/2>,
  abbreviated_month_names: #Function<2.32021692/1 in MyApp.Cldr.Calendar.strftime_options/2>,
  day_of_week_names: #Function<3.32021692/1 in MyApp.Cldr.Calendar.strftime_options/2>,
  abbreviated_day_of_week_names: #Function<4.32021692/1 in MyApp.Cldr.Calendar.strftime_options/2>
]

Typical usage

iex: NimbleStrftime.format(Date.utc_today(), MyApp.Cldr.Calendar.strftime_options!())