Search documentation of Localize

# Localize.Unit (Localize v0.39.0)

Copy Markdown View Source

Represents and formats CLDR units of measure.

A `Localize.Unit` struct holds the original unit name string, its parsed AST representation, and an optional numeric value. Units can be created with `new/3` and formatted with `to_string/2`.

## Unit names

Unit names follow the CLDR identifier syntax defined in TR35. Examples: `"meter"`, `"kilogram"`, `"meter-per-second"`, `"square-kilometer"`, `"liter-per-100-kilometer"`.

## Formatting

`to_string/2` produces locale-aware output with plural-sensitive patterns (e.g., `"1 kilometer"` vs `"3 kilometers"`) and supports `:long`, `:short`, and `:narrow` format styles.

## Usage preferences

CLDR defines measurement usage preferences by territory and category (e.g., road distances in the US use miles). The `:usage` field on the struct and the `:usage` option on `to_string/2` support automatic unit selection based on locale.

## Summary

### Types

t()
value()

### Functions

add(unit_1, unit_2)

Adds two convertible units.

compare(unit_1, unit_2)

Compares two convertible units.

compatible?(unit_1, unit_2)

Returns whether two units are convertible (same category).

convert(source, target)

Converts a unit to a different target unit.

convert!(unit, target)

Converts a unit to a different target unit, raising on error.

convert_measurement_system(unit, system)

Converts a unit to the preferred unit for a given measurement system.

decompose(unit, target_units, format_options \\ [])

Decomposes a unit into a list of units with the given target units.

define_unit(name, definition)

Registers a custom unit definition at runtime.

display_name(unit_or_name, options \\ [])

Returns the localized stand-alone display name of a unit.

div(unit, divisor)

Divides a unit by a scalar or another unit.

known_categories()

Returns a list of all known unit categories.

known_units_by_category()

Returns a map of unit categories to their member units.

known_usages()

Returns a list of valid usage types for unit preferences.

load_custom_units(path)

Loads custom unit definitions from an Elixir term file (`.exs`).

localize(unit, options \\ [])

Converts a unit into the locale-preferred unit set for a given usage.

measurement_system_for_territory(territory, category \\ :default)

Returns the preferred measurement system for a territory.

mult(unit, multiplier)

Multiplies a unit by a scalar or another unit.

negate(unit)

Negates a unit's value.

new(name)

Creates a new unit from a CLDR unit identifier string without a value.

new(amount, unit, options \\ [])

Creates a new unit with a value and a CLDR unit identifier string.

new!(name)

Creates a new unit from a CLDR unit identifier string, raising on error.

new!(amount, unit, options \\ [])

Creates a new unit with a value and a CLDR unit identifier string, raising on error.

sub(unit_1, unit_2)

Subtracts `unit_2` from `unit_1`.

to_iolist(unit, options \\ [])

Formats a unit as an iolist.

to_string(unit_or_units, options \\ [])

Formats a unit together with its value as a localized string.

to_string!(unit_or_units, options \\ [])

Same as `to_string/2` but raises on error.

unit_category(name)

Returns the CLDR category for a unit.

value(unit)

Returns the numeric value of a unit.

zero(unit)

Returns a zero-valued unit of the same type.

zero?(unit)

Returns true if the unit has a zero value.

## Types

# t()

    @type t() :: %Localize.Unit{
      format_options: Keyword.t(),
      name: String.t(),
      parsed: tuple(),
      usage: String.t() | nil,
      value: value()
    }

# value()

    @type value() :: number() | Decimal.t() | [number()] | nil

## Functions

# add(unit_1, unit_2)

    @spec add(t(), t()) :: {:ok, t()} | {:error, Exception.t() | String.t()}

Adds two convertible units.

The value of `unit_2` is converted to the unit type of `unit_1` before addition. The result retains the unit type of `unit_1`.

### Arguments

- `unit_1` is a `%Localize.Unit{}` struct with a value.

- `unit_2` is a `%Localize.Unit{}` struct with a value.

### Returns

- `{:ok, unit}` or `{:error, exception}`.

### Examples

    iex> {:ok, a} = Localize.Unit.new(1, "kilometer")
    iex> {:ok, b} = Localize.Unit.new(500, "meter")
    iex> {:ok, result} = Localize.Unit.add(a, b)
    iex> result.value
    1.5

# compare(unit_1, unit_2)

    @spec compare(t(), t()) :: :lt | :eq | :gt | {:error, Exception.t()}

Compares two convertible units.

The value of `unit_2` is converted to the unit type of `unit_1` before comparison.

### Arguments

- `unit_1` is a `%Localize.Unit{}` struct with a value.

- `unit_2` is a `%Localize.Unit{}` struct with a value.

### Returns

- `:lt`, `:eq`, or `:gt`.

- `{:error, exception}` if the units are not convertible.

### Examples

    iex> {:ok, a} = Localize.Unit.new(1, "kilometer")
    iex> {:ok, b} = Localize.Unit.new(500, "meter")
    iex> Localize.Unit.compare(a, b)
    :gt

# compatible?(unit_1, unit_2)

    @spec compatible?(t() | String.t(), t() | String.t()) :: boolean()

Returns whether two units are convertible (same category).

### Arguments

- `unit_1` is a `%Localize.Unit{}` struct or a unit name string.

- `unit_2` is a `%Localize.Unit{}` struct or a unit name string.

### Returns

- `true` or `false`.

### Examples

    iex> Localize.Unit.compatible?("meter", "foot")
    true

    iex> Localize.Unit.compatible?("meter", "kilogram")
    false

# convert(source, target)

    @spec convert(t(), String.t()) :: {:ok, t()} | {:error, Exception.t()}

Converts a unit to a different target unit.

The source and target units must be convertible (same dimensional base unit). Returns a new unit struct with the converted value and the target unit type.

### Arguments

- `unit` is a `%Localize.Unit{}` struct with a value.

- `target` is the target unit identifier string (e.g., `"foot"`).

### Returns

- `{:ok, unit}` where `unit` is a new `%Localize.Unit{}` with the converted value and target unit type, or

- `{:error, reason}` if the unit has no value, the target cannot be parsed, or the units are not convertible.

### Examples

    iex> {:ok, meters} = Localize.Unit.new(1, "kilometer")
    iex> {:ok, result} = Localize.Unit.convert(meters, "meter")
    iex> result.value
    1000.0
    iex> result.name
    "meter"

# convert!(unit, target)

    @spec convert!(t(), String.t()) :: t() | no_return()

Converts a unit to a different target unit, raising on error.

Same as `convert/2` but returns the unit struct directly or raises `ArgumentError`.

### Arguments

- `unit` is a `%Localize.Unit{}` struct with a value.

- `target` is the target unit identifier string.

### Returns

- A `%Localize.Unit{}` struct with the converted value.

### Examples

    iex> unit = Localize.Unit.new!(1000, "meter")
    iex> result = Localize.Unit.convert!(unit, "kilometer")
    iex> result.value
    1.0

# convert_measurement_system(unit, system)

    @spec convert_measurement_system(t(), :metric | :us | :uk) ::
      {:ok, t()} | {:error, String.t()}

Converts a unit to the preferred unit for a given measurement system.

Looks up the CLDR unit preference data for the unit's quantity category and the specified measurement system, then converts to the first preferred unit for the "default" usage.

### Arguments

- `unit` is a `%Localize.Unit{}` struct with a value.

- `system` is the target measurement system: `:metric`, `:us`, or `:uk`.

### Returns

- `{:ok, unit}` where `unit` is a new `%Localize.Unit{}` with the converted value and the preferred unit for that system, or

- `{:error, reason}` if the unit has no value, the measurement system is invalid, or no preference is found.

### Examples

    iex> {:ok, meters} = Localize.Unit.new(100, "meter")
    iex> {:ok, result} = Localize.Unit.convert_measurement_system(meters, :us)
    iex> result.name
    "mile"

# decompose(unit, target_units, format_options \\ [])

    @spec decompose(t(), [String.t()], Keyword.t()) ::
      {:ok, [t()]} | {:error, Exception.t()}

Decomposes a unit into a list of units with the given target units.

This is used for mixed-unit formatting, for example converting 1.75 meters into `[1 meter, 75 centimeters]` or 5.25 feet into `[5 feet, 3 inches]`.

Each target unit receives the integer part of the remaining value, except the last unit which receives the remainder.

When the input value is a `Decimal`, the truncate/remainder math runs in `Decimal` arithmetic (not float), so precision is preserved through the decomposition.

Intermediate units whose integer part rounds to zero are skipped (so decomposing 1.5 m into `["meter", "kilometer", "centimeter"]` skips the kilometer entry). The trailing unit is also skipped if its value is zero.

When `format_options` is given, those options are attached to the final (trailing) unit's `:format_options` field — typically a `[round_nearest: N]` skeleton lifted from CLDR's preference data. `Localize.Unit.localize/2` uses this to thread CLDR's skeletons through to `to_string/2`.

### Arguments

- `unit` is a `%Localize.Unit{}` struct with a value.

- `target_units` is a list of unit name strings, ordered from largest to smallest (e.g., `["foot", "inch"]`).

- `format_options` is an optional keyword list attached to the final unit's `:format_options`. Defaults to `[]`.

### Returns

- `{:ok, units}` where `units` is a list of `%Localize.Unit{}` structs.

- `{:error, exception}` if conversion fails.

### Examples

    iex> {:ok, m} = Localize.Unit.new(1.75, "meter")
    iex> {:ok, parts} = Localize.Unit.decompose(m, ["meter", "centimeter"])
    iex> Enum.map(parts, fn u -> {u.name, u.value} end)
    [{"meter", 1}, {"centimeter", 75.0}]

    iex> {:ok, m} = Localize.Unit.new(Decimal.new("1.75"), "meter")
    iex> {:ok, parts} = Localize.Unit.decompose(m, ["meter", "centimeter"])
    iex> Enum.map(parts, fn u -> {u.name, u.value} end)
    [{"meter", 1}, {"centimeter", Decimal.new("75.0")}]

    iex> {:ok, m} = Localize.Unit.new(2.0, "meter")
    iex> {:ok, parts} = Localize.Unit.decompose(m, ["meter", "centimeter"])
    iex> Enum.map(parts, fn u -> u.name end)
    ["meter"]

    iex> {:ok, m} = Localize.Unit.new(0.5, "meter")
    iex> {:ok, parts} = Localize.Unit.decompose(m, ["meter", "centimeter"])
    iex> Enum.map(parts, fn u -> u.name end)
    ["centimeter"]

    iex> {:ok, m} = Localize.Unit.new(1.83, "meter")
    iex> {:ok, parts} = Localize.Unit.decompose(m, ["foot", "inch"], round_nearest: 1)
    iex> List.last(parts).format_options
    [round_nearest: 1]

# define_unit(name, definition)

    @spec define_unit(String.t(), map()) :: :ok | {:error, String.t()}

Registers a custom unit definition at runtime.

Custom units extend the built-in CLDR unit database with user-defined units. Each custom unit must specify a base unit it converts to, a conversion factor, and a category.

### Arguments

- `name` is a string unit identifier (e.g., `"smoot"`). Must start with a lowercase letter and contain only lowercase letters, digits, and hyphens.

- `definition` is a map with the following keys:

### Options

- `:base_unit` (required) — the CLDR base unit this custom unit converts to (e.g., `"meter"`, `"kilogram"`).

- `:factor` (required) — conversion multiplier: `1 custom_unit = factor * base_unit`.

- `:offset` (optional) — additive offset for temperature-like conversions. Defaults to `0.0`.

- `:category` (required) — the unit category (e.g., `"length"`, `"mass"`).

- `:display` (optional) — locale-specific display patterns. A nested map of `locale => style => plural_patterns`.

### Returns

- `:ok` on success.

- `{:error, reason}` if validation fails.

### Examples

    iex> Localize.Unit.define_unit("smoot", %{
    ...>   base_unit: "meter",
    ...>   factor: 1.7018,
    ...>   category: "length",
    ...>   display: %{en: %{long: %{one: "{0} smoot", other: "{0} smoots"}}}
    ...> })
    :ok

# display_name(unit_or_name, options \\ [])

    @spec display_name(t() | String.t(), Keyword.t()) ::
      {:ok, String.t()} | {:error, Exception.t()}

Returns the localized stand-alone display name of a unit.

This is the CLDR `<displayName>` form — a bare label like "meters" or "Meter", suitable for headings, form-field labels, or column titles. It is distinct from the value-bearing inline forms returned by `to_string/2`, which are pluralised and grammatical-case aware (e.g., "5 meters"). If a `Localize.Unit.t/0` struct carrying a value is passed, the value is ignored.

### Arguments

- `unit` is a `%Localize.Unit{}` struct or a unit name string.

- `options` is a keyword list of options.

### Options

- `:locale` is a locale identifier. The default is `Localize.get_locale()`.

- `:format` is `:long`, `:short`, or `:narrow`. The default is `:long`.

### Returns

- `{:ok, name}` or `{:error, exception}`.

### Examples

    iex> Localize.Unit.display_name("meter", locale: :en)
    {:ok, "meters"}

    iex> Localize.Unit.display_name("meter", locale: :en, format: :short)
    {:ok, "m"}

# div(unit, divisor)

    @spec div(t(), number() | t()) :: {:ok, t()} | {:error, Exception.t()}

Divides a unit by a scalar or another unit.

When divided by a number, the value is scaled. When divided by another unit, a per-unit compound is produced (e.g., meter ÷ second).

### Arguments

- `unit` is a `%Localize.Unit{}` struct.

- `divisor` is a number or a `%Localize.Unit{}` struct.

### Returns

- `{:ok, unit}` or `{:error, exception}`.

### Examples

    iex> {:ok, m} = Localize.Unit.new(10, "meter")
    iex> {:ok, result} = Localize.Unit.div(m, 2)
    iex> result.value
    5.0

# known_categories()

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

Returns a list of all known unit categories.

### Returns

- A list of category name strings.

### Examples

    iex> cats = Localize.Unit.known_categories()
    iex> "length" in cats
    true

# known_units_by_category()

    @spec known_units_by_category() :: %{required(String.t()) => [String.t()]}

Returns a map of unit categories to their member units.

### Returns

- A map of `%{category_string => [unit_name_string]}`.

### Examples

    iex> by_cat = Localize.Unit.known_units_by_category()
    iex> is_list(by_cat["length"])
    true

# known_usages()

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

Returns a list of valid usage types for unit preferences.

### Returns

- A sorted list of usage atoms.

### Examples

    iex> usages = Localize.Unit.known_usages()
    iex> "default" in usages
    true

# load_custom_units(path)

    @spec load_custom_units(String.t()) :: {:ok, non_neg_integer()} | {:error, String.t()}

Loads custom unit definitions from an Elixir term file (`.exs`).

The file must evaluate to a list of maps, each with a `:unit` key and the standard definition fields (`:base_unit`, `:factor`, `:category`, and optionally `:display`).

#### Security

This function uses `Code.eval_file/1` to evaluate the given file, which executes arbitrary Elixir code. Only load files from trusted sources. Never call this function with unsanitised user input or paths derived from external data.

### Arguments

- `path` is the path to the `.exs` file.

### Returns

- `{:ok, count}` with the number of units loaded.

- `{:error, reason}` on failure.

# localize(unit, options \\ [])

    @spec localize(t(), Keyword.t()) :: {:ok, [t()]} | {:error, Exception.t()}

Converts a unit into the locale-preferred unit set for a given usage.

Resolves the preferred unit list with `Localize.Unit.Preference.preferred_units/2` (driven by `:usage` and `:territory`), then decomposes the value across that list. The result is a list of `Localize.Unit.t/0` structs ready to be rendered with `to_string/2`.

This is the convenience wrapper for the common preference-resolution → conversion → decomposition pipeline. Pass the returned list straight to `Localize.Unit.to_string/2` to render it as a localized unit list (e.g. `"6 feet, 0.047 inches"`).

### Arguments

- `unit` is a `Localize.Unit.t/0` struct with a value.

- `options` is a keyword list of options.

### Options

- `:usage` is the unit's intended usage. Accepts an atom (`:person_height`) or a CLDR-style string (`"person-height"`). If omitted, falls back to the struct's `:usage` field, then to `:default`.

- `:territory` is a territory code atom (e.g. `:US`, `:DE`). If omitted, derived from the current locale.

- `:locale` is a locale identifier used to derive `:territory` when `:territory` is not given.

### Returns

- `{:ok, units}` where `units` is a list of `Localize.Unit.t/0` structs, in preference order (largest unit first).

- `{:error, exception}` if preferences cannot be resolved or the decomposition fails.

### Examples

    iex> unit = Localize.Unit.new!(1.83, "meter")
    iex> {:ok, parts} = Localize.Unit.localize(unit, usage: :person_height, territory: :US)
    iex> Enum.map(parts, fn u -> u.name end)
    ["foot", "inch"]

    iex> unit = Localize.Unit.new!(2_000, "meter")
    iex> {:ok, [km]} = Localize.Unit.localize(unit, usage: :road, territory: :DE)
    iex> {km.name, km.value}
    {"kilometer", 2.0}

# measurement_system_for_territory(territory, category \\ :default)

    @spec measurement_system_for_territory(atom(), :default | :temperature | :paper_size) ::
      atom()

Returns the preferred measurement system for a territory.

### Arguments

- `territory` is a territory code atom (e.g., `:US`, `:GB`).

### Returns

- `:metric`, `:us`, or `:uk`.

### Examples

    iex> Localize.Unit.measurement_system_for_territory(:US)
    :us

    iex> Localize.Unit.measurement_system_for_territory(:FR)
    :metric

    iex> Localize.Unit.measurement_system_for_territory(:US, :temperature)
    :us

    iex> Localize.Unit.measurement_system_for_territory(:LR, :temperature)
    :metric

    iex> Localize.Unit.measurement_system_for_territory(:US, :paper_size)
    :us_letter

    iex> Localize.Unit.measurement_system_for_territory(:FR, :paper_size)
    :a4

# mult(unit, multiplier)

    @spec mult(t(), number() | t()) :: {:ok, t()} | {:error, Exception.t()}

Multiplies a unit by a scalar or another unit.

When multiplied by a number, the value is scaled. When multiplied by another unit, a compound unit is produced (e.g., meter × second).

### Arguments

- `unit` is a `%Localize.Unit{}` struct.

- `multiplier` is a number or a `%Localize.Unit{}` struct.

### Returns

- `{:ok, unit}` or `{:error, exception}`.

### Examples

    iex> {:ok, m} = Localize.Unit.new(5, "meter")
    iex> {:ok, result} = Localize.Unit.mult(m, 3)
    iex> result.value
    15

# negate(unit)

    @spec negate(t()) :: {:ok, t()} | {:error, Exception.t()}

Negates a unit's value.

### Arguments

- `unit` is a `%Localize.Unit{}` struct with a value.

### Returns

- `{:ok, unit}` or `{:error, exception}`.

# new(name)

    @spec new(String.t()) :: {:ok, t()} | {:error, Exception.t()}

Creates a new unit from a CLDR unit identifier string without a value.

### Arguments

- `name` is a unit identifier string such as `"meter-per-second"`.

### Returns

- `{:ok, unit}` where `unit` is a `%Localize.Unit{}` struct, or

- `{:error, reason}` if the identifier cannot be parsed.

### Examples

    iex> {:ok, unit} = Localize.Unit.new("meter")
    iex> unit.name
    "meter"

# new(amount, unit, options \\ [])

    @spec new(number() | Decimal.t(), String.t(), keyword()) ::
      {:ok, t()} | {:error, Exception.t()}

Creates a new unit with a value and a CLDR unit identifier string.

### Arguments

- `amount` is the numeric value (integer, float, or Decimal).

- `unit` is a unit identifier string such as `"meter-per-second"`.

- `options` is an optional keyword list.

### Options

- `:usage` is a string specifying the intended usage context for the unit. Valid values include `"default"`, `"person"`, `"person-height"`, `"road"`, `"food"`, `"vehicle-fuel"`, and others defined in the CLDR unit preference data. The usage affects which target unit is selected when calling `convert_measurement_system/2`.

### Returns

- `{:ok, unit}` where `unit` is a `%Localize.Unit{}` struct, or

- `{:error, reason}` if the value is not a valid number, the identifier cannot be parsed, or the usage is invalid.

### Examples

    iex> {:ok, unit} = Localize.Unit.new(100, "meter")
    iex> unit.value
    100
    iex> unit.name
    "meter"

    iex> {:ok, unit} = Localize.Unit.new(Decimal.new("3.14"), "kilogram")
    iex> unit.value
    Decimal.new("3.14")

    iex> {:ok, unit} = Localize.Unit.new(180, "centimeter", usage: "person-height")
    iex> unit.usage
    "person-height"

# new!(name)

    @spec new!(String.t()) :: t() | no_return()

Creates a new unit from a CLDR unit identifier string, raising on error.

Same as `new/1` but returns the struct directly or raises `ArgumentError`.

### Arguments

- `name` is a unit identifier string.

### Returns

- A `%Localize.Unit{}` struct.

### Examples

    iex> unit = Localize.Unit.new!("meter")
    iex> unit.name
    "meter"

# new!(amount, unit, options \\ [])

    @spec new!(number() | Decimal.t(), String.t(), keyword()) :: t() | no_return()

Creates a new unit with a value and a CLDR unit identifier string, raising on error.

Same as `new/2` but returns the struct directly or raises `ArgumentError`.

### Arguments

- `amount` is the numeric value (integer, float, or Decimal).

- `unit` is a unit identifier string.

### Returns

- A `%Localize.Unit{}` struct.

### Examples

    iex> unit = Localize.Unit.new!(42, "kilogram")
    iex> unit.value
    42

# sub(unit_1, unit_2)

    @spec sub(t(), t()) :: {:ok, t()} | {:error, Exception.t() | String.t()}

Subtracts `unit_2` from `unit_1`.

The value of `unit_2` is converted to the unit type of `unit_1`.

### Arguments

- `unit_1` is a `%Localize.Unit{}` struct with a value.

- `unit_2` is a `%Localize.Unit{}` struct with a value.

### Returns

- `{:ok, unit}` or `{:error, exception}`.

### Examples

    iex> {:ok, a} = Localize.Unit.new(5, "kilometer")
    iex> {:ok, b} = Localize.Unit.new(2000, "meter")
    iex> {:ok, result} = Localize.Unit.sub(a, b)
    iex> result.value
    3.0

# to_iolist(unit, options \\ [])

    @spec to_iolist(t(), Keyword.t()) :: {:ok, iolist()} | {:error, Exception.t()}

Formats a unit as an iolist.

Same as `to_string/2` but returns an iolist for efficient IO operations without an intermediate binary allocation.

### Arguments

- `unit` is a `%Localize.Unit{}` struct.

- `options` is a keyword list of formatting options (same as `to_string/2`).

### Returns

- `{:ok, iolist}` or `{:error, exception}`.

# to_string(unit_or_units, options \\ [])

    @spec to_string(t() | [t(), ...], Keyword.t()) ::
      {:ok, String.t()} | {:error, Exception.t()}

Formats a unit together with its value as a localized string.

Accepts either a single `Localize.Unit.t/0` struct or a list of them. A single unit is rendered inline with its value using the locale's pluralised pattern (e.g., `"5 meters"`). A list is rendered by formatting each element and joining via `Localize.List.to_string/2`, which is what produces mixed-unit output like `"6 feet, 0.047 inches"`.

When `:usage` is supplied for a single unit — or the unit's struct carries a non-`nil` `:usage` field set at `new/3` time — this function first calls `localize/2` to convert the value into the locale-preferred unit set, then formats the resulting list. This is the one-call shortcut for the preference-resolution → conversion → decomposition → format pipeline.

The territory used for preference resolution is derived from the `:locale` option (via `Localize.Territory.territory_from_locale/1`). There is no `:territory` option on `to_string/2`; if you need to override the territory independently of the locale, call `localize/2` directly and pipe the result back into `to_string/2`.

For the bare stand-alone unit label without a value, use `display_name/2`.

### Arguments

- `unit_or_units` is a `Localize.Unit.t/0` struct or a non-empty list of `Localize.Unit.t/0` structs.

- `options` is a keyword list of options.

### Options

- `:locale` is a locale identifier atom, string, or a `Localize.LanguageTag.t/0`. The default is the current process locale.

- `:format` is `:long`, `:short`, or `:narrow`. The default is `:long`.

- `:usage` (single unit only) is the unit's intended usage. When given, triggers `localize/2` before formatting. Accepts an atom (`:person_height`) or a CLDR-style string (`"person-height"`). If the option is omitted but the struct's `:usage` field is set, `localize/2` is still triggered using that value.

- `:list_options` is a keyword list passed to `Localize.List.to_string/2` when rendering a unit list. Use it to pick a unit-specific list style (e.g. `list_options: [list_style: :unit_short]`).

- `:grammatical_case` selects a case-keyed pattern variant for the unit (e.g. `:nominative`, `:dative`, `:genitive`). Defaults to `:nominative`.

- `:grammatical_gender` is accepted on the public API for cldr_units parity. Only meaningful for compound-unit patterns (`compound_unit_pattern` keyed by gender); for simple units the gender is a fixed property of the unit in CLDR data and the option has no effect on output.

- `:backend` is `:nif` or `:elixir`. When `:nif` is specified and the NIF is available, ICU4C is used for formatting. Otherwise falls back to the pure-Elixir formatter. The default is `:elixir`.

### Returns

- `{:ok, formatted_string}` on success.

- `{:error, exception}` if the unit cannot be formatted.

### Examples

    iex> {:ok, unit} = Localize.Unit.new(42, "meter")
    iex> Localize.Unit.to_string(unit)
    {:ok, "42 meters"}

    iex> {:ok, unit} = Localize.Unit.new(1, "meter")
    iex> Localize.Unit.to_string(unit)
    {:ok, "1 meter"}

    iex> {:ok, unit} = Localize.Unit.new(42, "meter")
    iex> Localize.Unit.to_string(unit, format: :short)
    {:ok, "42 m"}

    iex> unit = Localize.Unit.new!(1.83, "meter")
    iex> Localize.Unit.to_string(unit, usage: :person_height, locale: "en-US")
    {:ok, "6 feet and 0.047 inches"}

    iex> unit = Localize.Unit.new!(2_000, "meter")
    iex> Localize.Unit.to_string(unit, usage: :road, locale: "de-DE")
    {:ok, "2 Kilometer"}

# to_string!(unit_or_units, options \\ [])

    @spec to_string!(t() | [t(), ...], Keyword.t()) :: String.t()

Same as `to_string/2` but raises on error.

### Arguments

- `unit_or_units` is a `Localize.Unit.t/0` struct or a non-empty list of `Localize.Unit.t/0` structs.

- `options` is a keyword list of options.

### Returns

- A formatted string.

### Raises

- Raises an exception if the unit cannot be formatted.

# unit_category(name)

    @spec unit_category(t() | String.t()) :: {:ok, String.t()} | {:error, Exception.t()}

Returns the CLDR category for a unit.

### Arguments

- `unit` is a `%Localize.Unit{}` struct or a unit name string.

### Returns

- `{:ok, category}` where category is a string like `"length"`, or

- `{:error, exception}`.

### Examples

    iex> {:ok, m} = Localize.Unit.new(1, "meter")
    iex> Localize.Unit.unit_category(m)
    {:ok, "length"}

    iex> Localize.Unit.unit_category("kilogram")
    {:ok, "mass"}

# value(unit)

    @spec value(t()) :: value()

Returns the numeric value of a unit.

### Arguments

- `unit` is a `%Localize.Unit{}` struct.

### Returns

- The value (number, Decimal, or nil).

### Examples

    iex> {:ok, m} = Localize.Unit.new(42, "meter")
    iex> Localize.Unit.value(m)
    42

# zero(unit)

    @spec zero(t()) :: t()

Returns a zero-valued unit of the same type.

### Arguments

- `unit` is a `%Localize.Unit{}` struct.

### Returns

- A new `%Localize.Unit{}` with value `0`.

### Examples

    iex> {:ok, m} = Localize.Unit.new(42, "meter")
    iex> z = Localize.Unit.zero(m)
    iex> z.value
    0

# zero?(unit)

    @spec zero?(t()) :: boolean()

Returns true if the unit has a zero value.

### Arguments

- `unit` is a `%Localize.Unit{}` struct.

### Returns

- `true` or `false`.

### Examples

    iex> {:ok, m} = Localize.Unit.new(0, "meter")
    iex> Localize.Unit.zero?(m)
    true