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}

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.

@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

• date is any Date.t/0.

• options is a Keyword.t/0 list of options. The default is [].

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 localize the era using the variant data. In the :en locale, this will produce CE and BCE rather than the default AD and BC.

• :am_pm will, if set to :variant localize the "AM"/"PM" time period indicator with the variant data. In the :en locale, this will produce am and pm rather than the default AM and PM.

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}}

@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"
"السبت"

Returns a keyword list of options than can be applied to Calendar.strftime/3.

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

Arguments

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

Options

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

• :calendar is the name of any known calendar. The default is Cldr.Calendar.Gregorian.

Notes

• Calendars are assumed to have a fixed 12 month cycle. This is because the callback functions have no context from which to determine the specific number of months in a given year.

Examples

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> Calendar.strftime ~D[2025-01-26 Cldr.Calendar.IL], "%a",
...>   MyApp.Cldr.Calendar.strftime_options!(calendar: Cldr.Calendar.IL, locale: "en")
"Sun"