See Cldr.available_locale_name?/1.

@spec default_locale() :: Cldr.LanguageTag.t() | no_return()

Returns the default locale.

Example

iex> MyApp.Cldr.default_locale()
%Cldr.LanguageTag{
  backend: MyApp.Cldr,
  canonical_locale_name: "en-001",
  cldr_locale_name: :"en-001",
  language_subtags: [],
  extensions: %{},
  gettext_locale_name: "en",
  language: "en",
  locale: %{},
  private_use: [],
  rbnf_locale_name: :en,
  requested_locale_name: "en-001",
  script: :Latn,
  territory: :"001",
  transform: %{},
  language_variants: []
}

@spec default_territory() ::
  Cldr.Locale.territory_code() | {:error, {module(), String.t()}}

Returns the default territory when a locale does not specify one and none can be inferred.

Example

iex> MyApp.Cldr.default_territory()
:"001"

@spec ellipsis(String.t() | [String.t()], Keyword.t()) ::
  String.t() | {:error, {module(), String.t()}}

Add locale-specific ellipsis to a string.

Arguments

• string is any String.t or a 2-element list of String.t between which the ellipsis is inserted.

• backend is any module that includes use Cldr and therefore is a Cldr backend module. The default is Cldr.default_backend!/0. Note that Cldr.default_backend!/0 will raise an exception if no :default_backend is configured under the :ex_cldr key in config.exs.

• options is a keyword list of options

Options

• :locale is any valid locale name returned by Cldr.known_locale_names/1. The default is Cldr.get_locale/0.

• :location determines where to place the ellipsis. The options are :after (the default for a single string argument), :between (the default and only valid location for an argument that is a list of two strings) and :before.

• :format formats based upon whether the ellipsis is inserted between words or sentences. The valid options are :word or :sentence. The default is :sentence.

Examples

iex> MyApp.Cldr.ellipsis("And furthermore")
"And furthermore…"

iex> MyApp.Cldr.ellipsis(["And furthermore", "there is much to be done"], locale: :ja)
"And furthermore…there is much to be done"

iex> MyApp.Cldr.ellipsis("And furthermore", format: :word)
"And furthermore …"

iex> MyApp.Cldr.ellipsis(["And furthermore", "there is much to be done"], locale: :ja, format: :word)
"And furthermore … there is much to be done"

@spec get_locale() :: Cldr.LanguageTag.t()

Return the current locale to be used for Cldr functions that take an optional locale parameter for which a locale is not supplied.

Example

iex> MyApp.Cldr.put_locale("pl")
iex> MyApp.Cldr.get_locale()
%Cldr.LanguageTag{
   backend: Elixir.MyApp.Cldr,
   canonical_locale_name: "pl",
   cldr_locale_name: :pl,
   extensions: %{},
   language: "pl",
   locale: %{},
   private_use: [],
   rbnf_locale_name: :pl,
   territory: :PL,
   requested_locale_name: "pl",
   script: :Latn,
   transform: %{},
   language_variants: []
 }

See Cldr.known_calendars/0.

See Cldr.known_currencies/0.

@spec known_gettext_locale_name(String.t()) :: String.t() | false

Returns either the Gettext locale_name in Cldr format or false based upon whether the locale name is configured in Gettext.

Arguments

• locale is any valid locale name returned by MyApp.Cldr.known_gettext_locale_names/0

Examples

iex> MyApp.Cldr.known_gettext_locale_name("en")
"en"

iex> MyApp.Cldr.known_gettext_locale_name("en-SA")
false

@spec known_gettext_locale_name?(String.t()) :: boolean()

Returns a boolean indicating if the specified locale name is configured and available in Gettext.

Arguments

• locale is any valid locale name returned by MyApp.Cldr.known_locale_names/0

Examples

iex> MyApp.Cldr.known_gettext_locale_name?("en")
true

iex> MyApp.Cldr.known_gettext_locale_name?("!!")
false

@spec known_gettext_locale_names() :: [String.t()]

Returns a list of Gettext locale names but in CLDR format with underscore replaced by hyphen in order to facilitate comparisons with Cldr locale names.

@spec known_locale_name(Cldr.Locale.locale_name()) :: String.t() | false

Returns either the locale_name or false based upon whether the locale name is configured in Cldr.

This is helpful when building a list of or expressions to return the first known locale name from a list.

Arguments

• locale is any valid locale name returned by MyApp.Cldr.known_locale_names/0

Examples

iex> MyApp.Cldr.known_locale_name(:"en-AU")
:"en-AU"

iex> MyApp.Cldr.known_locale_name(:"en-SA")
false

@spec known_locale_name?(Cldr.Locale.locale_name()) :: boolean()

Returns a boolean indicating if the specified locale name is configured and available in Cldr.

Arguments

• locale is any valid locale name returned by MyApp.Cldr.known_locale_names/0

Examples

iex> MyApp.Cldr.known_locale_name?(:en)
true

iex> MyApp.Cldr.known_locale_name?(:"!!")
false

Returns a list of the known locale names.

Known locales are those locales which are the subset of all CLDR locales that have been configured for use either in this module or in Gettext.

Returns a list of atoms representing the number systems types known to Cldr.

Example

iex> MyApp.Cldr.known_number_system_types()
[:default, :finance, :native, :traditional]

See Cldr.known_number_systems/0.

@spec known_rbnf_locale_name(Cldr.Locale.locale_name()) :: String.t() | false

Returns either the RBNF locale_name or false based upon whether the locale name is configured in Cldr and has RBNF rules defined.

Arguments

• locale is any valid locale name returned by MyApp.Cldr.known_locale_names/0

Examples

iex> MyApp.Cldr.known_rbnf_locale_name(:en)
:en

iex> MyApp.Cldr.known_rbnf_locale_name(:"en-SA")
false

@spec known_rbnf_locale_name?(Cldr.Locale.locale_name()) :: boolean()

Returns a boolean indicating if the specified locale name is configured and available in Cldr and supports rules based number formats (RBNF).

Arguments

• locale is any valid locale name returned by MyApp.Cldr.known_locale_names/0

Examples

iex> MyApp.Cldr.known_rbnf_locale_name?(:en)
true

iex> MyApp.Cldr.known_rbnf_locale_name?(:"!!")
false

@spec known_rbnf_locale_names() :: [Cldr.Locale.locale_name()]

Returns a list of locale names which have rules-based number formats (RBNF).

See Cldr.known_territories/0.

Normalizes a string by applying transliteration of common symbols in numbers, currencies and dates

@spec put_gettext_locale(Cldr.LanguageTag.t()) ::
  {:ok, binary() | nil} | {:error, {module(), String.t()}}

Set the current process's Gettext locale from a t:Cldr.LanguageTag.

Arguments

• locale is a Cldr.LanguageTag struct returned by Cldr.Locale.new!/2.

Returns

• {:ok, gettext_locale_name} or

• {:error, {exception, reason}}

Behaviour

1. If the locale.gettext_locale_name is nil then an error is returned.

2. The gettext locale for the gettext_backend configured for the CLDR backend defined by the t:Cldr.LanguageTag is set.

Examples

iex> import Cldr.LanguageTag.Sigil
iex> MyApp.Cldr.put_gettext_locale(~l"en")
{:ok, "en"}

iex> import Cldr.LanguageTag.Sigil
iex> MyApp.Cldr.put_gettext_locale(~l"de")
{
  :error,
  {
    Cldr.UnknownLocaleError,
    "Locale TestBackend.Cldr.Locale.new!(\"de-DE\") does not map to a known gettext locale name"
  }
}

@spec put_locale(Cldr.Locale.locale_reference()) ::
  {:ok, Cldr.LanguageTag.t()} | {:error, {module(), String.t()}}

Set the current locale to be used for Cldr functions that take an optional locale parameter for which a locale is not supplied.

Arguments

• locale is any valid locale name returned by MyApp.Cldr.known_locale_names/0 or a t:Cldr.LanguageTag struct returned by MyApp.Cldr.Locale.new!/1

See rfc5646 for the specification of a language tag.

Examples

iex> MyApp.Cldr.put_locale("en")
{:ok,
 %Cldr.LanguageTag{
   backend: MyApp.Cldr,
   canonical_locale_name: "en",
   cldr_locale_name: :en,
   language_subtags: [],
   extensions: %{},
   gettext_locale_name: "en",
   language: "en",
   locale: %{},
   private_use: [],
   rbnf_locale_name: :en,
   requested_locale_name: "en",
   script: :Latn,
   territory: :US,
   transform: %{},
   language_variants: []
 }}

iex> MyApp.Cldr.put_locale("invalid-locale!")
{:error, {Cldr.LanguageTag.ParseError,
  "Expected a BCP47 language tag. Could not parse the remaining \"!\" starting at position 15"}}

@spec quote(String.t(), Keyword.t()) :: String.t() | {:error, {module(), String.t()}}

Add locale-specific quotation marks around a string.

Arguments

• string is any valid Elixir string

• options is a keyword list of options

Options

• locale is any valid locale name returned by Cldr.known_locale_names/1. The default is Cldr.get_locale/0

Examples

iex> MyApp.Cldr.quote("Quoted String")
"“Quoted String”"

iex> MyApp.Cldr.quote("Quoted String", locale: :ja)
"「Quoted String」"

@spec unknown_locale_names() :: [Cldr.Locale.locale_name()]

Returns a list of the locales names that are configured, but not known in CLDR.

Since there is a compile-time exception raised if there are any unknown locales this function should always return an empty list.

See Cldr.validate_calendar/1.

See Cldr.validate_currency/1.

@spec validate_locale(Cldr.Locale.locale_name() | Cldr.LanguageTag.t() | String.t()) ::
  {:ok, Cldr.LanguageTag.t()} | {:error, {module(), String.t()}}

Normalise and validate a locale name.

Arguments

• locale is any valid locale name returned by MyApp.Cldr.known_locale_names/0 or a Cldr.LanguageTag struct returned by MyApp.Cldr.Locale.new!/1

Returns

• {:ok, language_tag}

• {:error, reason}

Notes

See rfc5646 for the specification of a language tag.

Examples

iex> MyApp.Cldr.validate_locale(:en)
{:ok,
%Cldr.LanguageTag{
  backend: MyApp.Cldr,
  canonical_locale_name: "en",
  cldr_locale_name: :en,
  extensions: %{},
  gettext_locale_name: "en",
  language: "en",
  locale: %{},
  private_use: [],
  rbnf_locale_name: :en,
  requested_locale_name: "en",
  script: :Latn,
  territory: :US,
  transform: %{},
  language_variants: []
}}


iex> MyApp.Cldr.validate_locale MyApp.Cldr.default_locale()
{:ok,
%Cldr.LanguageTag{
  backend: MyApp.Cldr,
  canonical_locale_name: "en-001",
  cldr_locale_name: :"en-001",
  extensions: %{},
  gettext_locale_name: "en",
  language: "en",
  locale: %{},
  private_use: [],
  rbnf_locale_name: :en,
  requested_locale_name: "en-001",
  script: :Latn,
  territory: :"001",
  transform: %{},
  language_variants: []
}}

iex> MyApp.Cldr.validate_locale("zzz")
{:error, {Cldr.InvalidLanguageError, "The language \"zzz\" is invalid"}}

See Cldr.validate_number_system/1.

@spec validate_number_system_type(String.t() | atom()) ::
  {:ok, atom()} | {:error, {module(), String.t()}}

Normalise and validate a number system type.

Arguments

• number_system_type is any number system type returned by Cldr.known_number_system_types/1

Returns

• {:ok, normalized_number_system_type} or

• {:error, {exception, message}}

Examples

iex> MyApp.Cldr.validate_number_system_type(:default)
{:ok, :default}

iex> MyApp.Cldr.validate_number_system_type(:traditional)
{:ok, :traditional}

iex> MyApp.Cldr.validate_number_system_type(:latn)
{
  :error,
  {Cldr.UnknownNumberSystemTypeError, "The number system type :latn is unknown"}
}

iex> MyApp.Cldr.validate_number_system_type("bork")
{
  :error,
  {Cldr.UnknownNumberSystemTypeError, "The number system type \"bork\" is invalid"}
}

See Cldr.validate_territory/1.

@spec with_locale(Cldr.Locale.locale_reference(), (-> any())) :: any()

Execute a function with a locale ensuring that the current locale is restored after the function.

Arguments

• locale is any valid locale name returned by Cldr.known_locale_names/1.

• fun is any 0-arity function or function capture.

Returns

• The value returned by the function fun/0 or

• {:error, {exception, reason}} if the locale is invalid or

• raises an exception if the current locale cannot be identified.