Tuples

Pairs and more

Curly braces build a tuple, a fixed-size group of values. Tuples hold related items of different types, like a status with its payload.

The size is fixed at creation, so a tuple never grows or shrinks in place.

erl

1> {ok, 42}.
{ok,42}
2> {point, 1, 2}.
{point,1,2}
3> {}.
{}

Access by index

The element function reads a position starting from one, and tuple_size counts the items. The size function answers the same for tuples and lists.

Index access is fine for ad-hoc work, but pattern matching, the next section, reads better.

erl

1> T = {ok, 42}.
{ok,42}
2> element(2, T).
42
3> tuple_size(T).
2

Match inside

Tuples match deeply: a pattern with a tuple inside matches only tuples of the same shape. The values inside bind to names in the same move.

This is how Erlang unpacks results: match the tuple, and the parts arrive as variables.

erl

1> {ok, Value} = {ok, 42}.
{ok,42}
2> Value.
42
3> {error, _} = {ok, 42}.
** exception error: no match of right hand side value {ok,42}

The ok and error shape

Erlang functions answer expected failures with tuples instead of exceptions. Callers match {ok, Value} for success and {error, Reason} for failure, and the compiler checks nothing: the pattern does.

The convention is so common that it has a name: the ok tuple. Lesson 34 shows how a GenServer answers calls with the same shape.

-module(calc). -export([divide/2]). divide(_, 0) -> {error, div_by_zero}; divide(A, B) -> {ok, A / B}.

erlc calc.erl
erl

1> calc:divide(5, 2).
{ok,2.5}
2> calc:divide(1, 0).
{error,div_by_zero}

Next: Maps

Questions

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

  1. How do you write a tuple?

    Answer

    {ok, 42}

    Curly braces build a tuple, a fixed-size group of values.

  2. Can a tuple grow after it is created?

    Answer

    No, its size is fixed

    A tuple keeps the size it was built with; changing it means building a new tuple.

  3. From which number does element/2 count positions?

    Answer

    One

    Tuple positions start at one, so element(1, {ok, 42}) is ok.

  4. What does element(2, {ok, 42}). return?

    Answer

    42

    The second position of the tuple holds 42.

  5. What does tuple_size({ok, 42}). return?

    Answer

    2

    The tuple has two items, so its size is two.

  6. What does {ok, Value} = {ok, 42}. do?

    Answer

    Matches the tuple and binds Value to 42

    The pattern matches the shape and binds the name to the value inside.

  7. What happens for {error, _} = {ok, 42}.?

    Answer

    A badmatch exception is raised

    The tuple tags differ, so the match fails with no match of right hand side value.

  8. What does the {ok, Value} tuple mean by convention?

    Answer

    A successful result with its value

    Functions answer expected failures as {ok, Value} or {error, Reason} instead of raising.

  9. What does calc:divide(1, 0). return?

    Answer

    {error,div_by_zero}

    The first clause matches a zero denominator and returns the error tuple.

  10. Why does Erlang prefer the ok tuple to exceptions for expected failures?

    Answer

    The caller must handle the answer explicitly

    A tuple is an ordinary value, so the caller matches it and cannot forget the failure case.

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