# `Cldr.Unit.Additional`
[🔗](https://github.com/elixir-cldr/cldr_units/blob/v3.20.3/lib/cldr/unit/additional.ex#L1)

Additional domain-specific units can be defined
to suit application requirements. In the context
of `ex_cldr` there are two parts of configuring
additional units.

1. Configure the unit, base unit and conversion in
`config.exs`. This is a requirement since units are
compiled into code.

2. Configure the localizations for the additional
unit in a CLDR backend module.

Once configured, additional units act and behave
like any of the predefined units of measure defined
by CLDR.

## Configuring a unit in config.exs

Under the application `:ex_cldr_units` define
a key `:additional_units` with the required
unit definitions.  For example:
```elixir
config :ex_cldr_units, :additional_units,
  vehicle: [base_unit: :unit, factor: 1, offset: 0, sort_before: :all],
  person: [base_unit: :unit, factor: 1, offset: 0, sort_before: :all]
```
This example defines two additional units: `:vehicle` and
`:person`.  The keys `:base_unit`, and `:factor` are required.
The key `:offset` is optional and defaults to `0`. The
key `:sort_before` is optional and defaults to `:none`.

### Configuration keys

* `:base_unit` is the common denominator that is used
  to support conversion between like units. It can be
  any atom value. For example `:liter` is the base unit
  for volume units, `:meter` is the base unit for length
  units.

* `:factor` is used to convert a unit to its base unit in
  order to support conversion. When converting a unit to
  another compatible unit, the unit is first multiplied by
  this units factor then divided by the target units factor.

* `:offset` is added to a unit after applying its base factor
  in order to convert to another unit.

* `:sort_before` determines where in this *base unit* sorts
  relative to other base units.  Typically this is set to
  `:all` in which case this base unit sorts before all other
  base units or`:none` in which case this base unit sorted
  after all other base units. The default is `:none`. If in
  doubt, leave this key to its default.

* `:systems` is list of measurement systems to which this
  unit belongs. The known measurement systems are `:metric`,
  `:uksystem` and `:ussystem`. The default is
  `[:metric, :ussystem, :uksystem]`.

## Defining localizations

Localizations are defined in a backend module through adding
`use Cldr.Unit.Additional` to the top of the backend module
and invoking `Cldr.Unit.Additional.unit_localization/4` for
each localization.

See `Cldr.Unit.Additional.unit_localization/4` for further
information.

Note that one invocation of the macro is required for
each combination of locale, style and unit. An exception
will be raised at runtime is a localization is expected
but is not found.

# `merge_base_units`

# `unit_localization`
*macro* 

Although defining a unit in `config.exs` is enough to create,
operate on and serialize an additional unit, it cannot be
localised without defining localizations in an `ex_cldr`
backend module.  For example:
```elixir
defmodule MyApp.Cldr do
  use Cldr.Unit.Additional

  use Cldr,
    locales: ["en", "fr", "de", "bs", "af", "af-NA", "se-SE"],
    default_locale: "en",
    providers: [Cldr.Number, Cldr.Unit, Cldr.List]

  unit_localization(:person, "en", :long,
    one: "{0} person",
    other: "{0} people",
    display_name: "people"
  )

  unit_localization(:person, "en", :short,
    one: "{0} per",
    other: "{0} pers",
    display_name: "people"
  )

  unit_localization(:person, "en", :narrow,
    one: "{0} p",
    other: "{0} p",
    display_name: "p"
  )
end
```

Note the additions to a typical `ex_cldr`
backend module:

* `use Cldr.Unit.Additional` is required to
  define additional units

* use of the `unit_localization/4` macro in
  order to define a localization.

One invocation of `unit_localization` should
made for each combination of unit, locale and
style.

### Parameters to unit_localization/4

* `unit` is the name of the additional
unit as an `atom`.

* `locale` is the locale name for this
  localization. It should be one of the locale
  configured in this backend although this
  cannot currently be confirmed at compile time.

* `style` is one of `:long`, `:short`, or
  `:narrow`.

* `localizations` is a keyword like of localization
  strings. Two keys - `:display_name` and `:other`
  are mandatory. They represent the localizations for
  a non-count display name and `:other` is the
  localization for a unit when no other pluralization
  is defined.

### Localisations

Localization keyword list defines localizations that
match the plural rules for a given locale. Plural rules
for a given number in a given locale resolve to one of
six keys:

* `:zero`
* `:one` (singular)
* `:two` (dual)
* `:few` (paucal)
* `:many` (also used for fractions if they have a separate class)
* `:other` (required—general plural form—also used if the language only has a single form)

Only the `:other` key is required. For english,
providing keys for `:one` and `:other` is enough. Other
languages have different grammatical requirements.

The key `:display_name` is used by the function
`Cldr.Unit.display_name/1` which is primarily used
to support UI applications.

---

*Consult [api-reference.md](api-reference.md) for complete listing*