Maps

Build a map

The hash syntax builds a map, a group of key-value pairs. Keys can be atoms, numbers, or binaries, and a map can hold any mix of values.

The empty map is the hash alone.

erl

1> #{name => "Ada", age => 36}.
#{name => "Ada",age => 36}
2> #{}.
#{}

Read a key

The maps module reads, lists, and removes keys. maps:get fails with a badmap or key error when the key is missing, so pair it with maps:find for optional keys.

Erlang has no dot access for maps: the dot belongs to records. Read a map with maps:get, or match the key in a pattern.

erl

1> M = #{name => "Ada"}.
#{name => "Ada"}
2> maps:get(name, M).
"Ada"
3> #{name := Who} = M.
#{name => "Ada"}
4> Who.
"Ada"

Update a key

The arrow in a map expression adds or replaces a key, and the double arrow updates a key that must already exist. Both return a new map; the old one stays intact.

Use the single arrow when a key may be new, and the double arrow when its presence is part of your logic.

erl

1> M = #{name => "Ada"}.
#{name => "Ada"}
2> M#{age => 36}.
#{name => "Ada",age => 36}
3> M#{name := "Grace"}.
#{name => "Grace"}

Keys and matching

Maps match on keys: a map pattern with a key in it matches any map that holds that key, and the value binds to the name beside it.

The double arrow inside a pattern demands the key, and the single arrow is not allowed there, so a match never invents a missing key.

erl

1> #{name := Who} = #{name => "Ada"}.
#{name => "Ada"}
2> Who.
"Ada"

Next: Functions and clauses

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 map with the key name?

    Answer

    #{name => "Ada"}

    A map literal starts with # and holds key-value pairs joined by =>.

  2. Which value is the empty map?

    Answer

    #{}

    The hash with no pairs is the empty map, distinct from the empty tuple and the empty list.

  3. What does maps:get(name, #{name => "Ada"}). return?

    Answer

    "Ada"

    maps:get/2 returns the value stored under the key.

  4. What happens when maps:get asks for a missing key?

    Answer

    It raises a key error

    maps:get/2 raises when the key is absent; maps:find/2 returns an error tuple instead.

  5. What does the single arrow => do in a map expression?

    Answer

    Adds or replaces a key

    => builds a pair, whether the key is new or already present.

  6. What does the double arrow := do in a map expression?

    Answer

    Updates a key that must already exist

    := updates an existing key and raises a badkey error when the key is absent.

  7. What does M#{age => 36}. do when M has no age key?

    Answer

    Returns a new map with age added

    The single arrow adds a missing key, and the original map stays untouched.

  8. What does #{name := Who} = #{name => "Ada"}. do?

    Answer

    Matches the key and binds Who to "Ada"

    The pattern demands the key name and binds its value to the name beside :=.

  9. Can a map key be a number or a binary?

    Answer

    Yes, any term can be a key

    Map keys are ordinary terms: atoms, numbers, binaries, tuples and more all work.

  10. How does Erlang read a map value with dot syntax, as in other languages?

    Answer

    There is no map dot access: use maps:get or a pattern

    The dot belongs to records; maps are read with maps:get/2 or matched in a pattern.

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