Maps

Mix.install([
  {:jason, "~> 1.4"},
  {:kino, "~> 0.9", override: true},
  {:youtube, github: "brooklinjazz/youtube"},
  {:hidden_cell, github: "brooklinjazz/hidden_cell"}
])

Navigation

Home Report An Issue Keyword ListsShopping List

Review Questions

Upon completing this lesson, a student should be able to answer the following questions.

• What is a map? How do they differ from keyword lists?
• How do we create a map?
• How do we use dot notation and square bracket notation to access values in a map?
• How do we pattern match on maps?

Maps

Maps are another type of associative data structure. You can create a map using %{}. Maps can use almost any elixir term as a key. However, most commonly we use strings and atoms for map keys.

Maps have a key and a value separated by an arrow =>, which is an equals symbol = and a greater than symbol >.

# String Keys
%{"key" => "value"}

# Atom Keys
%{:key => "value"}

multiple key-value pairs are separated by a comma ,.

%{:key => "value", "key" => "value"}

Maps with only atoms as keys can use a special piece of syntax sugar that makes them more convenient to write and read. This is purely syntax sugar and does not change their behavior.

%{key1: "value", key2: "value"}

Maps are the common go-to for a key-value data structure. They are more expensive in terms of performance to create than keyword lists, however they are incredibly fast to access values. Unlike keyword lists, keys in a map must be unique. Also unlike keyword lists, maps also do not guarantee key order.

For these reasons, you’ll most often use maps for large amounts of data or when you want keys to be unique and do not care about order.

We often use maps to represent properties of something. For example, you might have a user map that represents information about a book.

%{
  title: "Name of the Wind",
  author: "Patrick Rothfuss",
  description: """
  The Name of the Wind is a fantasy novel by Patrick Rothfuss. It is the first book in the
  Kingkiller Chronicle series and tells the story of Kvothe, a young orphan who becomes a
  legendarily talented musician and magician. The novel is known for its intricate
  world-building, complex characters, and themes of power, love, and loss.
  """  
}

Elixir is very helpful and provides a warning to let us know we’re overriding a duplicate key.

%{duplicate_key: "value1", duplicate_key: "value2"}

As mentioned earlier, maps do not guarantee key order, which is why you’ll notice the returned value of the map below does not have the same order as the map returned by the Elixir cell.

%{one: "one", two: "two", three: "three"}

Maps can have any elixir term as a key, this makes them incredibly flexible.

%{1 => "value"}

%{[1, 2, 3] => "value"}

Accessing Map Values

Unlike the other data types, there aren’t specific map operators. To manipulate maps we use a different tool called the Map module, which you will learn more about in a future lesson.

For now, it’s enough to know that you can access values in an atom-key map using a few different methods.

You can retrieve values in a map using map.key notation like so. This only works for maps with atom keys.

%{key: "value"}.key

Alternatively, you can access the map value using square bracket notation map[key].

%{key: "value"}[:key]

Bracket notation is especially useful for maps with non-atom keys.

%{"key" => "value"}["key"]

%{1 => "value"}[1]

With map.key notation, your program will throw an error if your map doesn’t have the expected value.

%{}.key

Bracket notation will return nil if the key doesn’t exist rather than throwing an error.

%{}[:key]

We can access deeply nested values with both dot notation and bracket notation.

%{key1: %{key2: %{key3: "value"}}}.key1.key2.key3

%{1 => %{2 => %{3 => "value"}}}[1][2][3]

Bracket notation is especially useful for accessing deeply nested values without causing a crash if the value doesn’t exist.

%{}[1][2][3]

You can accomplish all of the same behavior above by binding the map to a variable rather than accessing values from the map directly.

map = %{key: "value"}
map.key

map = %{key: "value"}
map[:key]

Your Turn

In the Elixir cell below, access the :hello key in map. Retrieve the value using both map[key] and map.key notation.

Example solution

map.key notation.

map = %{hello: "world"}
map.hello

map[] notation.

map = %{hello: "world"}
map[:hello]

map = %{hello: "world"}

Updating Maps

You can update values in a map using %{initial_map | updated_values} syntax like so.

initial = %{key: "value"}

%{initial | key: "new value"}

Elixir does not allow you to mutate values. That means the variable initial is still %{key: "value"}

initial

You can instead store a new variable for the updated map.

updated = %{initial | key: "new value"}
updated

Or rebind the existing initial variable.

initial = %{initial | key: "new value"}
initial

You can only update existing atom key values in a map, otherwise it will cause an error.

initial = %{}
%{initial | new_key: "value"}

Your Turn

Use a map to represent a todo item The todo map should have :title and :completed keys.

• title: “finish maps exercises”, completed: false

Bind your map to a todo variable, and update the value so completed is true.

Example solution

todo = %{title: "finish maps exercise", completed: false}

%{todo | completed: true}

Pattern Matching

We can pattern match on values inside the map.

%{hello: my_variable} = %{hello: "world"}
my_variable

Unlike with keyword lists, we don’t have to match on every key/value pair when pattern matching with maps.

%{one: one} = %{one: 1, two: 2}
one

This also works with non-atom key maps.

%{"hello" => world} = %{"hello" => "world"}

We can only pattern match on the value in the map, not the key. Keys in maps must be literals such as atoms, strings, tuples, etc.

%{hello => world} = %{"hello" => "world"}

Pin Operator

You’ll notice that we can rebind variables using pattern matching.

name = "Jon"

%{name: name} = %{name: "Bill"}

name

If instead of re-binding the variable, we want to use the literal value of the variable, we can use the pin operator ^.

name = "Jon"

%{name: ^name} = %{name: "Bill"}

name

The above causes a MatchError because the left side and right side do not match. It’s the same as if we had written the following.

%{name: "Jon"} = %{name: "Bill"}

We might use this to confirm our map matches some shape.

Your Turn

Bind 2 and 4 in the following map to variables two and four.

Example solution

%{two: two, four: four} = %{one: 1, two: 2, three: 3, four: 4}

Enter your solution below.

%{one: 1, two: 2, three: 3, four: 4}

Further Reading

Consider the following resource(s) to deepen your understanding of the topic.

• Elixir Schools: Maps
• Exercism: Maps
• Elixir Lang: Pattern Matching
• Elixir Lang: Maps

Commit Your Progress

DockYard Academy now recommends you use the latest Release rather than forking or cloning our repository.

Run git status to ensure there are no undesirable changes. Then run the following in your command line from the curriculum folder to commit your progress.

$ git add .
$ git commit -m "finish Maps reading"
$ git push

We’re proud to offer our open-source curriculum free of charge for anyone to learn from at their own pace.

We also offer a paid course where you can learn from an instructor alongside a cohort of your peers. We will accept applications for the June-August 2023 cohort soon.

Navigation

Home Report An Issue Keyword ListsShopping List