Localize.Inputs.Number.Unit (Localize.Inputs.Number v0.1.1)

Copy Markdown View Source

Locale-derived display data for unit form inputs.

Mirrors Localize.Inputs.Number.Symbols but for the unit picker — resolves the locale's measurement system, the preferred unit list for a category in that system, and the full list of all known units in the category. Unit display names are localized via Localize.Unit.display_name/2.

Categories come from Localize.Unit.known_categories/0 (e.g. "length", "volume", "mass"). The preferred-by-system map is a curated table per category — see @preferred_by_system — because CLDR's per-region preference data is keyed by usage (:person_height, :road, …) and value magnitude, not by a simple "units that belong to system X" predicate. The curated table covers the common categories; for everything else preferred_units/2 falls back to the full category list.

Prefixed units (SI prefixes like decimeter, kilo*, etc.) are filtered out by default — see :include_prefixed.

Summary

Types

t()

Locale display data resolved by unit_for_locale/2.

Functions

all_unit_names(category, include_prefixed \\ false)

Returns every known unit name in the given category.

known_categories()

Returns the list of unit categories known to CLDR.

preferred_unit_names(category, system)

Returns the curated preferred-unit names for the given (category, system) pair, or the full category list if no curation exists for that pair.

unit_for_locale(locale \\ nil, options)

Resolves picker display data for the given locale + category.

Types

t()

@type t() :: %Localize.Inputs.Number.Unit{
  all_units: [{String.t(), String.t()}],
  category: String.t(),
  language_tag: Localize.LanguageTag.t(),
  locale: atom(),
  measurement_system: atom(),
  preferred_units: [{String.t(), String.t()}],
  unit: String.t() | nil,
  unit_display_name: String.t() | nil
}

Locale display data resolved by unit_for_locale/2.

  • :locale — the canonical CLDR locale id (atom).

  • :language_tag — the full Localize.LanguageTag.t/0.

  • :category — the unit category as a string (e.g. "length").

  • :measurement_system — the locale's default measurement system as an atom (:metric, :us, :uk).

  • :unit — the selected unit name as a string, or nil if the caller didn't specify one.

  • :unit_display_name — the localized display name of the selected unit, or nil.

  • :preferred_units — list of {name, display_name} tuples, the units in this category that belong to the locale's measurement system. Sorted in roughly small-to-large order where the curated table provides it; alphabetical otherwise.

  • :all_units — list of {name, display_name} tuples, every known unit in the category. Alphabetical by name.

Functions

all_unit_names(category, include_prefixed \\ false)

@spec all_unit_names(String.t(), boolean()) :: [String.t()]

Returns every known unit name in the given category.

Arguments

  • category — a category string from known_categories/0.

  • include_prefixed — when true, includes SI-prefixed variants (e.g. decimeter, kilogram-square-meter). The default is false.

known_categories()

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

Returns the list of unit categories known to CLDR.

Returns

  • A list of strings such as ["acceleration", "angle", "area", "length", "mass", ...].

preferred_unit_names(category, system)

@spec preferred_unit_names(String.t(), atom()) :: [String.t()]

Returns the curated preferred-unit names for the given (category, system) pair, or the full category list if no curation exists for that pair.

Returns

  • A list of unit name strings.

unit_for_locale(locale \\ nil, options)

@spec unit_for_locale(
  Localize.LanguageTag.t() | atom() | String.t() | nil,
  Keyword.t()
) ::
  {:ok, t()} | {:error, Exception.t()}

Resolves picker display data for the given locale + category.

Arguments

Options

  • :category is a unit category string from Localize.Unit.known_categories/0 (e.g. "length"). Required.

  • :unit is a specific unit name to also resolve display data for. Optional.

  • :include_prefixed — when true, SI-prefixed unit variants (e.g. decimeter, kilogram-square-meter) are included in the :all_units list. The default is false to keep pickers manageable. The curated preferred lists are always used as-is.

Returns

  • {:ok, t()} on success.

  • {:error, Exception.t()} when the locale can't be parsed (Localize.InvalidLocaleError) or the category is unknown.

Examples

iex> {:ok, info} = Localize.Inputs.Number.Unit.unit_for_locale(:en, category: "length")
iex> info.measurement_system
:us

iex> {:ok, info} = Localize.Inputs.Number.Unit.unit_for_locale(:fr, category: "length")
iex> info.measurement_system
:metric

iex> {:ok, info} = Localize.Inputs.Number.Unit.unit_for_locale(:en, category: "length", unit: "meter")
iex> info.unit
"meter"