Expressions in guard clauses

Elixir imports and allows the following expressions in guards by default:

  • comparison operators (==, !=, ===, !==, >, >=, <, <=)
  • boolean operators (and, or, not)
  • arithmetic operations (+, -, *, /)
  • arithmetic unary operators (+, -)
  • the binary concatenation operator &lt;&gt;
  • the in operator as long as the right side is a range or a list
  • all the following type check functions:
    • is_atom/1
    • is_binary/1
    • is_bitstring/1
    • is_boolean/1
    • is_float/1
    • is_function/1
    • is_function/2
    • is_integer/1
    • is_list/1
    • is_map/1
    • is_nil/1
    • is_number/1
    • is_pid/1
    • is_port/1
    • is_reference/1
    • is_tuple/1
  • plus these functions:
    • abs(number)
    • binary_part(binary, start, length)
    • bit_size(bitstring)
    • byte_size(bitstring)
    • div(integer, integer)
    • elem(tuple, n)
    • hd(list)
    • length(list)
    • map_size(map)
    • node()
    • node(pid | ref | port)
    • rem(integer, integer)
    • round(number)
    • self()
    • tl(list)
    • trunc(number)
    • tuple_size(tuple)

Additionally, users may define their own guards. For example, the Bitwise module defines guards as functions and operators: bnot, ~~~, band, &&&, bor, |||, bxor, ^^^, bsl, <<<, bsr, >>>.

Note that while boolean operators such as and, or, not are allowed in guards, the more general and short-circuiting operators &&, || and ! are not.

Keep in mind errors in guards do not leak but simply make the guard fail:

iex> hd(1)
** (ArgumentError) argument error
    :erlang.hd(1)
iex> case 1 do
...>   x when hd(x) -> "Won't match"
...>   x -> "Got: #{x}"
...> end
"Got 1"

If none of the clauses match, an error is raised:

iex> case :ok do
...>   :error -> "Won't match"
...> end
** (CaseClauseError) no case clause matching: :ok

Note anonymous functions can also have multiple clauses and guards:

iex> f = fn
...>   x, y when x > 0 -> x + y
...>   x, y -> x * y
...> end
#Function<12.71889879/2 in :erl_eval.expr/5>
iex> f.(1, 3)
4
iex> f.(-1, 3)
-3

The number of arguments in each anonymous function clause needs to be the same, otherwise an error is raised.