# `Unicode.GeneralCategory`
[🔗](https://github.com/elixir-unicode/unicode/blob/v2.0.0/lib/unicode/category.ex#L1)

Functions to introspect the Unicode general category property for binaries (Strings) and codepoints.

The primary API is `category/1` which returns the general category of a codepoint, or the list of general categories of a string.

The functions `fetch/1`, `get/1` and `count/1` provide introspection of the codepoint ranges belonging to a category. `categories/0`, `known_categories/0` and `aliases/0` return the underlying category data.

# `aliases`

Returns a map of aliases for Unicode categories.

An alias is an alternative name for referring to a category. Aliases are resolved by the `fetch/1` and `get/1` functions.

### Returns

* A map where the alias string is the key and the category name is the value.

### Examples

    iex> Unicode.GeneralCategory.aliases() |> Map.get("lowercaseletter")
    :Ll

# `categories`

Returns the map of Unicode character categories.

### Returns

* A map where the category name is the key and a list of codepoint ranges as 2-tuples is the value.

### Examples

    iex> Unicode.GeneralCategory.categories() |> Map.get(:Zl)
    [{8232, 8232}]

# `category`

Returns the category name(s) for the given binary or codepoint.

Only concrete general categories are considered. Derived categories (`:all`, `:ascii`, `:assigned` and so on) are not considered.

### Arguments

* `string_or_codepoint` is either a binary (String) or a codepoint in the range `0..0x10FFFF`.

### Returns

* For a codepoint, a single category name is returned.

* For a binary, a list of the distinct category names of the codepoints in the binary is returned.

### Examples

    iex> Unicode.GeneralCategory.category(?A)
    :Lu

    iex> Unicode.GeneralCategory.category("abc")
    [:Ll]

# `count`

Returns the count of characters in a given category.

Aliases are resolved by this function.

### Arguments

* `category` is any category name or alias, as an atom or string.

### Returns

* A non-negative integer count of the codepoints in the category.

* `:error` if the category is not known.

### Examples

    iex> Unicode.GeneralCategory.count(:Ll)
    2283

    iex> Unicode.GeneralCategory.count(:Nd)
    770

# `fetch`

Returns the Unicode codepoint ranges for a given category.

Aliases are resolved by this function.

### Arguments

* `category` is any category name or alias, as an atom or string.

### Returns

* `{:ok, range_list}` where `range_list` is a list of codepoint ranges as 2-tuples.

* `:error` if the category is not known.

### Examples

    iex> Unicode.GeneralCategory.fetch(:Zl)
    {:ok, [{8232, 8232}]}

    iex> Unicode.GeneralCategory.fetch(:invalid)
    :error

# `get`

Returns the Unicode codepoint ranges for a given category.

Aliases are resolved by this function.

### Arguments

* `category` is any category name or alias, as an atom or string.

### Returns

* A list of codepoint ranges as 2-tuples.

* `nil` if the category is not known.

### Examples

    iex> Unicode.GeneralCategory.get(:Zl)
    [{8232, 8232}]

    iex> Unicode.GeneralCategory.get(:invalid)
    nil

# `known_categories`

Returns a list of known Unicode category names.

This function does not return the names of any category aliases.

### Returns

* A list of atom category names.

### Examples

    iex> :Lu in Unicode.GeneralCategory.known_categories()
    true

---

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