# `Localize.LanguageTag.U`
[🔗](https://github.com/elixir-localize/localize/blob/v1.2.0/lib/localize/language_tag/extensions/u.ex#L1)

Defines the struct for the BCP 47 `u` extension and provides a
standalone parser for `-u-` extension strings.

The `u` extension carries Unicode locale keywords such as the
calendar (`ca`), hour cycle (`hc`), numbering system (`nu`) and
collation options (`co`, `ks`, …). It is normally populated on a
`t:Localize.LanguageTag.t/0` by `Localize.validate_locale/1`;
`parse/1` parses an extension string on its own, for consumers
that receive the `-u-` subtags without a full locale identifier.

# `t`

```elixir
@type t() :: %Localize.LanguageTag.U{
  ca: atom(),
  cf: atom(),
  co: atom(),
  cu: atom(),
  dx: atom(),
  em: atom(),
  fw: atom(),
  hc: atom(),
  ka: atom(),
  kb: atom(),
  kc: atom(),
  kf: atom(),
  kh: atom(),
  kk: atom(),
  kn: atom(),
  kr: atom(),
  ks: atom(),
  kv: atom(),
  lb: atom(),
  lw: atom(),
  ms: atom(),
  mu: atom(),
  nu: atom(),
  rg: atom(),
  sd: atom(),
  ss: atom(),
  tz: atom(),
  va: atom(),
  vt: atom()
}
```

Defines the [BCP 47 `u` extension](https://unicode-org.github.io/cldr/ldml/tr35.html#u_Extension)
of a `t:Localize.LanguageTag`.

# `encode`

```elixir
@spec encode(t()) :: [{String.t(), String.t()}]
```

Encodes a `t:t/0` struct as canonical BCP 47 key/value pairs.

### Arguments

* `u_extension` is a `t:t/0` struct.

### Returns

* A list of `{key, value}` string tuples sorted by key, using the
  canonical BCP 47 forms (e.g. `:gregorian` encodes as
  `{"ca", "gregory"}`).

### Examples

    iex> {:ok, u} = Localize.LanguageTag.U.parse("hc-h23-ca-gregory")
    iex> Localize.LanguageTag.U.encode(u)
    [{"ca", "gregory"}, {"hc", "h23"}]

# `parse`

```elixir
@spec parse(String.t()) :: {:ok, t()} | {:error, Exception.t()}
```

Parses a standalone BCP 47 `u` extension string.

The keywords are validated and canonicalized exactly as they
would be by `Localize.validate_locale/1` on a full locale
identifier: keys are checked against the CLDR validity data,
aliases are resolved, and values are decoded to their canonical
atoms (e.g. `ca-gregory` decodes to `:gregorian`).

### Arguments

* `u_extension` is the extension subtags as a string, with or
  without the leading `u-` singleton (e.g. `"ca-gregory-hc-h23"`
  or `"u-ca-gregory-hc-h23"`).

### Returns

* `{:ok, u}` where `u` is a `t:t/0` struct with the decoded
  keywords set.

* `{:error, exception}` if the extension string cannot be parsed
  or a keyword fails validation.

### Examples

    iex> {:ok, u} = Localize.LanguageTag.U.parse("ca-gregory-hc-h23")
    iex> {u.ca, u.hc}
    {:gregorian, :h23}

    iex> {:ok, u} = Localize.LanguageTag.U.parse("u-nu-thai")
    iex> u.nu
    :thai

    iex> {:error, _} = Localize.LanguageTag.U.parse("not a u extension")

# `parse!`

```elixir
@spec parse!(String.t()) :: t()
```

Same as `parse/1` but raises on error.

### Arguments

* `u_extension` is the string content of a `-u-` extension.

### Returns

* A `t:Localize.LanguageTag.U.t/0` struct.

### Raises

* Raises an exception if the extension cannot be parsed.

### Examples

    iex> u = Localize.LanguageTag.U.parse!("ca-iso8601")
    iex> u.ca
    :iso8601

---

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