Search documentation of Localize

# Localize.Unit.Data (Localize v0.39.0)

Copy Markdown View Source

Compile-time extraction of CLDR unit data from a pre-built ETF file.

This module loads unit data from `priv/unit/unit_data.etf`, which is generated by `scripts/extract_unit_data.exs` from the CLDR supplemental units XML and validity XML files. Run that script whenever the CLDR data is updated.

## Summary

### Functions

base_unit_order()

Returns the canonical ordering of base units from `unitQuantities`.

base_unit_to_quantity()

Returns a map from base unit string to its CLDR quantity name.

base_units()

Returns the list of known base unit names from CLDR conversion data.

categories()

Returns the list of known unit categories.

conversion_factors()

Returns the conversion factor and offset for each source unit.

conversions()

Returns a map from source unit name to its CLDR base unit string.

deprecated_unit_identifiers()

Returns all deprecated CLDR unit identifiers.

power_components()

Returns the list of power components.

prefix_components()

Returns the list of unit ID prefix components.

si_prefix_atom(name)

Returns the atom form of a parsed SI prefix string, or `nil` if the string is not a known SI prefix.

si_prefix_data()

Returns detailed SI prefix data including symbols and powers.

si_prefix_multipliers()

Returns SI prefix multipliers as a map of prefix name to numeric multiplier.

si_prefix_names()

Returns the list of SI prefix names.

simple_base_units()

Returns the list of fundamental (simple) base units.

suffix_components()

Returns the list of unit ID suffix components.

unit_constants()

Returns the resolved unit constants as a map of name to float value.

unit_preferences()

Returns the CLDR unit preference data.

valid_unit_identifiers()

Returns all valid CLDR unit identifiers with regular status.

## Functions

# base_unit_order()

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

Returns the canonical ordering of base units from `unitQuantities`.

This ordering is used to reconstruct canonical base unit strings.

### Returns

- A list of base unit strings in canonical order.

# base_unit_to_quantity()

    @spec base_unit_to_quantity() :: %{required(String.t()) => String.t()}

Returns a map from base unit string to its CLDR quantity name.

### Returns

- A map such as `%{"meter" => "length", "kilogram" => "mass", ...}`.

# base_units()

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

Returns the list of known base unit names from CLDR conversion data.

### Returns

- A list of strings such as `["meter", "kilogram", "second", ...]`.

# categories()

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

Returns the list of known unit categories.

### Returns

- A list of strings such as `["acceleration", "angle", "area", ...]`.

# conversion_factors()

    @spec conversion_factors() :: %{
      required(String.t()) => %{factor: float() | :special, offset: float()}
    }

Returns the conversion factor and offset for each source unit.

The conversion from source to base unit is: `base_value = value * factor + offset`.

### Returns

- A map such as `%{"foot" => %{factor: 0.3048, offset: 0.0}, ...}`.

# conversions()

    @spec conversions() :: %{required(String.t()) => String.t()}

Returns a map from source unit name to its CLDR base unit string.

### Returns

- A map such as `%{"foot" => "meter", "newton" => "kilogram-meter-per-square-second", ...}`.

# deprecated_unit_identifiers()

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

Returns all deprecated CLDR unit identifiers.

### Returns

- A list of strings.

# power_components()

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

Returns the list of power components.

### Returns

- A list of strings such as `["square", "cubic", "pow2", ...]`.

# prefix_components()

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

Returns the list of unit ID prefix components.

### Returns

- A list of strings such as `["arc", "british", "dessert", ...]`.

# si_prefix_atom(name)

    @spec si_prefix_atom(String.t()) :: atom() | nil

Returns the atom form of a parsed SI prefix string, or `nil` if the string is not a known SI prefix.

# si_prefix_data()

    @spec si_prefix_data() :: [
      %{
        type: String.t(),
        symbol: String.t(),
        power10: String.t(),
        power2: String.t()
      },
      ...
    ]

Returns detailed SI prefix data including symbols and powers.

### Returns

- A list of maps with keys `:type`, `:symbol`, `:power10`, and `:power2`.

# si_prefix_multipliers()

    @spec si_prefix_multipliers() :: %{required(String.t()) => float()}

Returns SI prefix multipliers as a map of prefix name to numeric multiplier.

### Returns

- A map such as `%{"kilo" => 1000.0, "milli" => 0.001, ...}`.

# si_prefix_names()

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

Returns the list of SI prefix names.

### Returns

- A list of strings such as `["kilo", "milli", "mega", ...]`.

# simple_base_units()

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

Returns the list of fundamental (simple) base units.

These are the units with `status='simple'` in the CLDR `unitQuantities` data and form the atoms of the dimensional decomposition system.

### Returns

- A list of strings such as `["candela", "kilogram", "meter", "second", ...]`.

# suffix_components()

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

Returns the list of unit ID suffix components.

### Returns

- A list of strings such as `["force", "imperial", ...]`.

# unit_constants()

    @spec unit_constants() :: %{required(String.t()) => float()}

Returns the resolved unit constants as a map of name to float value.

### Returns

- A map such as `%{"ft_to_m" => 0.3048, "lb_to_kg" => 0.45359237, ...}`.

# unit_preferences()

    @spec unit_preferences() :: [
      %{category: String.t(), usage: String.t(), preferences: [map(), ...]},
      ...
    ]

Returns the CLDR unit preference data.

Each entry specifies preferred units for a category/usage/region combination.

### Returns

- A list of maps with keys `:category`, `:usage`, and `:preferences`.

# valid_unit_identifiers()

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

Returns all valid CLDR unit identifiers with regular status.

### Returns

- A list of strings such as `["length-kilometer", "mass-kilogram", ...]`.