Search documentation of bb

# BB.Cldr (bb v0.8.0)

View Source

Provides the core functions to retrieve and manage the CLDR data that supports formatting and localisation.

It provides the core functions to access formatted CLDR data, set and retrieve a current locale and validate certain core data types such as locales, currencies and territories.

# Summary

## Functions

available_locale_name?(locale_name)

See `Cldr.available_locale_name?/1`.

default_locale()

Returns the default `locale`.

default_territory()

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

ellipsis(string, options \\ [])

Add locale-specific ellipsis to a string.

get_locale()

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

known_calendars()

See `Cldr.known_calendars/0`.

known_currencies()

See `Cldr.known_currencies/0`.

known_gettext_locale_name(locale_name)

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

known_gettext_locale_name?(locale_name)

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

known_gettext_locale_names()

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.

known_locale_name(locale_name)

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

known_locale_name?(locale_name)

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

known_locale_names()

Returns a list of the known locale names.

known_number_system_types()

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

known_number_systems()

See `Cldr.known_number_systems/0`.

known_rbnf_locale_name(locale_name)

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

known_rbnf_locale_name?(locale_name)

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

known_rbnf_locale_names()

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

known_territories()

See `Cldr.known_territories/0`.

normalize_lenient_parse(string, scope, locale \\ get_locale())

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

put_locale(locale_name)

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

quote(string, options \\ [])

Add locale-specific quotation marks around a string.

unknown_locale_names()

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

validate_calendar(calendar)

See `Cldr.validate_calendar/1`.

validate_currency(currency)

See `Cldr.validate_currency/1`.

validate_locale(locale)

Normalise and validate a locale name.

validate_number_system(number_system)

See `Cldr.validate_number_system/1`.

validate_number_system_type(number_system_type)

Normalise and validate a number system type.

validate_territory(territory)

See `Cldr.validate_territory/1`.

with_locale(locale, fun)

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

# Functions

# available_locale_name?(locale_name)

See `Cldr.available_locale_name?/1`.

# default_locale()

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

Returns the default `locale`.

## Example

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

# default_territory()

    @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> BB.Cldr.default_territory()
    :"001"

# ellipsis(string, options \\ [])

    @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> BB.Cldr.ellipsis("And furthermore")
    "And furthermore…"

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

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

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

# get_locale()

    @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> BB.Cldr.put_locale("pl")
    iex> BB.Cldr.get_locale()
    %Cldr.LanguageTag{
       backend: Elixir.BB.Cldr,
       canonical_locale_name: "pl",
       cldr_locale_name: :pl,
       extensions: %{},
       gettext_locale_name: nil,
       language: "pl",
       locale: %{},
       private_use: [],
       rbnf_locale_name: :pl,
       territory: :PL,
       requested_locale_name: "pl",
       script: :Latn,
       transform: %{},
       language_variants: []
     }

# known_calendars()

See `Cldr.known_calendars/0`.

# known_currencies()

See `Cldr.known_currencies/0`.

# known_gettext_locale_name(locale_name)

    @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 `BB.Cldr.known_gettext_locale_names/0`

## Examples

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

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

# known_gettext_locale_name?(locale_name)

    @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 `BB.Cldr.known_locale_names/0`

## Examples

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

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

# known_gettext_locale_names()

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

# known_locale_name(locale_name)

    @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 `BB.Cldr.known_locale_names/0`

## Examples

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

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

# known_locale_name?(locale_name)

    @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 `BB.Cldr.known_locale_names/0`

## Examples

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

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

# known_locale_names()

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

# known_number_system_types()

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

## Example

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

# known_number_systems()

See `Cldr.known_number_systems/0`.

# known_rbnf_locale_name(locale_name)

    @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 `BB.Cldr.known_locale_names/0`

## Examples

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

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

# known_rbnf_locale_name?(locale_name)

    @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 `BB.Cldr.known_locale_names/0`

## Examples

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

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

# known_rbnf_locale_names()

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

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

# known_territories()

See `Cldr.known_territories/0`.

# normalize_lenient_parse(string, scope, locale \\ get_locale())

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

# put_locale(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 `BB.Cldr.known_locale_names/0` or a `t:Cldr.LanguageTag` struct returned by `BB.Cldr.Locale.new!/1`

See rfc5646 for the specification of a language tag.

## Examples

    iex> BB.Cldr.put_locale("en")
    {:ok,
     %Cldr.LanguageTag{
       backend: BB.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> BB.Cldr.put_locale("invalid-locale!")
    {:error, {Cldr.LanguageTag.ParseError,
      "Expected a BCP47 language tag. Could not parse the remaining \"!\" starting at position 15"}}

# quote(string, options \\ [])

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

- `:prefer` is one of `:default` or `:variant` with a default of `:default`. Some locales have alternative opening and closing quote marks and `:prefer` allows selecting a variant should one exist.

## Examples

    iex> BB.Cldr.quote("Quoted String", locale: :en)
    "“Quoted String”"

    iex> BB.Cldr.quote("Quoted String", prefer: :variant, locale: :de)
    "‚Quoted String‘"

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

# unknown_locale_names()

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

# validate_calendar(calendar)

See `Cldr.validate_calendar/1`.

# validate_currency(currency)

See `Cldr.validate_currency/1`.

# validate_locale(locale)

    @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 `BB.Cldr.known_locale_names/0` or a `Cldr.LanguageTag` struct returned by `BB.Cldr.Locale.new!/1`

## Returns

- `{:ok, language_tag}`

- `{:error, reason}`

## Notes

See rfc5646 for the specification of a language tag.

## Examples

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

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

# validate_number_system(number_system)

See `Cldr.validate_number_system/1`.

# validate_number_system_type(number_system_type)

    @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> BB.Cldr.validate_number_system_type(:default)
    {:ok, :default}

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

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

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

# validate_territory(territory)

See `Cldr.validate_territory/1`.

# with_locale(locale, fun)

(since 2.32.0)

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