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

Defines a set of guards that can be used with
Elixir functions to test whether a codepoint is
a member of a Unicode set.

Each guard operates on a single integer codepoint
since the operators permitted in a guard clause are
restricted to simple comparisons that do not include
string comparators.

The data that underpins these guards is generated
from the Unicode character database and therefore
includes a broad range of scripts well beyond the
basic ASCII definitions.

### Usage

Import or require the module and use the guards in a
function clause `when` expression:

    defmodule MyModule do
      import Unicode.Guards

      def character_type(codepoint) when is_upper(codepoint), do: :upper
      def character_type(codepoint) when is_lower(codepoint), do: :lower
      def character_type(codepoint) when is_digit(codepoint), do: :digit
      def character_type(_codepoint), do: :other
    end

### Implementation

The guards are defined as macros. Each expands, at its call site, to a
membership test built as a balanced tree of comparisons over the ranges
of its Unicode set. Some sets are large (`is_graph/1` spans ~740 ranges),
so prefer using a guard in a single function clause rather than repeating
it at many `when` sites, since every use re-expands the membership test.

Because they are macros rather than `defguard/1` definitions, they can be
used in any `when` clause but cannot themselves be used to define another
`defguard`.

# `is_blank`
*macro* 

Guards whether a codepoint is a blank character.

Matches the space separators (`Zs`) together with the tab
character, matching the POSIX `[:blank:]` class.

### Examples

    iex> import Unicode.Guards
    iex> match?(codepoint when is_blank(codepoint), ?\t)
    true

# `is_currency_symbol`
*macro* 

Guards whether a codepoint is a currency symbol character.

Matches any currency symbol (general category `Sc`).

### Examples

    iex> import Unicode.Guards
    iex> match?(codepoint when is_currency_symbol(codepoint), ?$)
    true

# `is_digit`
*macro* 

Guards whether a codepoint is a decimal digit character.

Matches any decimal digit (general category `Nd`) from any
Unicode script, not only the ASCII digits.

### Examples

    iex> import Unicode.Guards
    iex> match?(codepoint when is_digit(codepoint), ?5)
    true
    iex> match?(codepoint when is_digit(codepoint), ?x)
    false

# `is_graph`
*macro* 

Guards whether a codepoint is a graphic character.

Graphic characters are those that are non-space, non-control,
non-surrogate and assigned, as modelled by the `:Graph` derived
general category.

### Examples

    iex> import Unicode.Guards
    iex> match?(codepoint when is_graph(codepoint), ?A)
    true
    iex> match?(codepoint when is_graph(codepoint), ?\s)
    false

# `is_lower`
*macro* 

Guards whether a codepoint is a lower case character.

Matches any codepoint that Unicode defines as a lower case letter
(general category `Ll`) in any script.

### Examples

    iex> import Unicode.Guards
    iex> match?(codepoint when is_lower(codepoint), ?a)
    true
    iex> match?(codepoint when is_lower(codepoint), ?A)
    false

# `is_print`
*macro* 

Guards whether a codepoint is a printing character.

Matches the combination of the graphic characters and the space
separators, matching the POSIX `[:print:]` class.

### Examples

    iex> import Unicode.Guards
    iex> match?(codepoint when is_print(codepoint), ?A)
    true
    iex> match?(codepoint when is_print(codepoint), ?\s)
    true

# `is_printable`
*macro* 

Guards whether a codepoint is printable.

Uses the same definition of printable as `String.printable?/1`.

### Examples

    iex> import Unicode.Guards
    iex> match?(codepoint when is_printable(codepoint), ?A)
    true

# `is_quote_mark`
*macro* 

Guards whether a codepoint is a quotation mark.

See also `Unicode.Category.QuoteMarks`.

### Examples

    iex> import Unicode.Guards
    iex> match?(codepoint when is_quote_mark(codepoint), ?")
    true

# `is_quote_mark_ambidextrous`
*macro* 

Guards whether a codepoint is a quotation mark that may be used
as either a left or right mark.

See also `Unicode.Category.QuoteMarks`.

### Examples

    iex> import Unicode.Guards
    iex> match?(codepoint when is_quote_mark_ambidextrous(codepoint), ?")
    true

# `is_quote_mark_double`
*macro* 

Guards whether a codepoint is a double quotation mark.

See also `Unicode.Category.QuoteMarks`.

### Examples

    iex> import Unicode.Guards
    iex> match?(codepoint when is_quote_mark_double(codepoint), ?")
    true

# `is_quote_mark_left`
*macro* 

Guards whether a codepoint is a left quotation mark.

See also `Unicode.Category.QuoteMarks`.

### Examples

    iex> import Unicode.Guards
    iex> match?(codepoint when is_quote_mark_left(codepoint), 0x00AB)
    true

# `is_quote_mark_right`
*macro* 

Guards whether a codepoint is a right quotation mark.

See also `Unicode.Category.QuoteMarks`.

### Examples

    iex> import Unicode.Guards
    iex> match?(codepoint when is_quote_mark_right(codepoint), 0x00BB)
    true

# `is_quote_mark_single`
*macro* 

Guards whether a codepoint is a single quotation mark.

See also `Unicode.Category.QuoteMarks`.

### Examples

    iex> import Unicode.Guards
    iex> match?(codepoint when is_quote_mark_single(codepoint), ?')
    true

# `is_separator`
*macro* 

Guards whether a codepoint is a space separator character.

Matches the Unicode `Zs` category.

### Examples

    iex> import Unicode.Guards
    iex> match?(codepoint when is_separator(codepoint), ?\s)
    true

# `is_upper`
*macro* 

Guards whether a codepoint is an upper case character.

Matches any codepoint that Unicode defines as an upper case letter
(general category `Lu`) in any script.

### Examples

    iex> import Unicode.Guards
    iex> match?(codepoint when is_upper(codepoint), ?A)
    true
    iex> match?(codepoint when is_upper(codepoint), ?a)
    false

# `is_whitespace`
*macro* 

Guards whether a codepoint is a whitespace character.

Matches the Unicode `Zs` category plus the range 0x09..0x0d
which includes tab, newline and carriage return.

### Examples

    iex> import Unicode.Guards
    iex> match?(codepoint when is_whitespace(codepoint), ?\s)
    true
    iex> match?(codepoint when is_whitespace(codepoint), ?\t)
    true

---

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