Guards

What guards are

A guard is a boolean expression attached to a clause with the when keyword. The clause runs only when its guard holds, and matching moves on to the next clause otherwise.

Guards keep the ugly type checks out of function bodies and push them to the edge of the clause.

-module(classify). -export([classify/1]). classify(N) when is_integer(N) -> integer; classify(X) -> {other, X}.

Guard BIFs

Only a safe subset of functions may run in guards: the type tests, the comparison operators, length, size, and a few arithmetic helpers. They are called guard BIFs.

The restriction is the point: guards must never fail or crash, so the runtime can test them cheaply.

-module(sizes). -export([size_ok/1]). size_ok(L) when length(L) < 10 -> small; size_ok(_) -> big.

Guard sequences

Several guard tests join with commas into a sequence that must all hold, and semicolons split alternative sequences where any one may hold.

Read the comma as and and the semicolon as or, and a complex guard becomes plain English.

-module(grades). -export([grade/1]). grade(N) when is_integer(N), N >= 90 -> a; grade(N) when is_integer(N); is_float(N) -> graded; grade(_) -> unknown.

What guards cannot do

Guards cannot call your own functions, send messages, or build new data. A guard that needs more power belongs in the clause body or a helper function.

The compiler catches most violations and points at the exact guard expression, so the learning curve is short.

erlc classify.erl
erlc sizes.erl
erlc grades.erl
erl

1> classify:classify(5).
integer
2> classify:classify(a).
{other,a}
3> sizes:size_ok([1, 2]).
small
4> sizes:size_ok(lists:seq(1, 10)).
big
5> grades:grade(95).
a
6> grades:grade(70).
graded
7> grades:grade(a).
unknown

Next: Records

Questions

A new set of questions in a new order every time. Choose one answer for each, then check.

  1. Which keyword attaches a guard to a clause?

    Answer

    when

    when separates the head of a clause from its guard tests.

  2. What happens when a guard fails?

    Answer

    Matching moves to the next clause

    A failed guard only rejects that clause; another clause may still match.

  3. Which functions may appear in a guard?

    Answer

    Only the safe guard BIFs and operators

    Guards use a safe subset such as type tests, comparisons, length and size.

  4. Why may guards not call your own functions?

    Answer

    A guard must never fail or crash

    The runtime must test guards cheaply and safely, so arbitrary calls are excluded.

  5. What does a comma between guard tests mean?

    Answer

    And

    All tests separated by commas must hold, as in is_integer(N), N >= 90.

  6. What does a semicolon between guard tests mean?

    Answer

    Or

    Semicolons separate alternatives, and any one of them may hold.

  7. What does classify:classify(5). return?

    Answer

    integer

    The first clause matches an integer, so its body integer is returned.

  8. What does classify:classify(a). return?

    Answer

    {other,a}

    The atom is not an integer, so the second clause catches it.

  9. What does sizes:size_ok(lists:seq(1, 10)). return?

    Answer

    big

    The list has ten items, so length(L) < 10 fails and the catch-all clause answers big.

  10. What does grades:grade(a). return?

    Answer

    unknown

    The atom is neither an integer nor a float, so the final clause answers unknown.

The examples on this page were compiled and run with Erlang/OTP 27 (erts-15.2.7.14) on Alpine Linux 3.24.3 (x86_64) in a Docker container.

Article author: Arthur Isaev

Banner image