3/8/2016
Pattern matching - Elixir
HOME
INSTALL
GETTING STARTED
LEARNING
DOCS
BLOG
PACKAGES
Pattern matching
News: Elixir v1.2 released
Search...
1 The match operator
2 Pattern matching
3 The pin operator
In this chapter, we will show how the = operator in Elixir is actually a match
G ETTI N G ST A RTED
1. Introduction
2. Basic types
operator and how to use it to pattern match inside data structures. Finally, we
3. Basic operators
will learn about the pin operator ^ used to access previously bound values.
4. Pattern matching
5. case, cond and if
The match operator
6. Binaries, strings and char
We have used the = operator a couple times to assign variables in Elixir:
7. Keywords and maps
lists
8. Modules
iex> x = 1
1
iex> x
1
9. Recursion
10. Enumerables and streams
11. Processes
12. IO and the file system
In Elixir, the = operator is actually called thematchoperator. Lets see why:
13. alias, require and import
14. Module attributes
iex> 1 = x
15. Structs
16. Protocols
iex> 2 = x
** (MatchError) no match of right hand side value: 1
17. Comprehensions
18. Sigils
Notice that 1 = x is a valid expression, and it matched because both the left
19. try, catch and rescue
and right side are equal to 1. When the sides do not match, a MatchError is
20. Typespecs and behaviours
raised.
A variable can only be assigned on the left side of =:
21. Erlang libraries
22. Where to go next
M IX A N D OTP
iex> 1 = unknown
** (RuntimeError) undefined function: unknown/0
1. Introduction to Mix
2. Agent
http://elixir-lang.org/getting-started/pattern-matching.html
1/5
3/8/2016
Pattern matching - Elixir
Since there is no variable unknown previously defined, Elixir imagined you
were trying to call a function named unknown/0, but such a function does not
exist.
3. GenServer
4. Supervisor and Application
5. ETS
6. Dependencies and umbrella
Pattern matching
The match operator is not only used to match against simple values, but it is
apps
7. Task and gen-tcp
also useful for destructuring more complex data types. For example, we can
8. Docs, tests and with
pattern match on tuples:
9. Distributed tasks and
configuration
iex> {a, b, c} = {:hello, "world", 42}
{:hello, "world", 42}
iex> a
:hello
M ETA -PROG RA M MI N G I N
EL IX I R
iex> b
1. Quote and unquote
"world"
2. Macros
3. Domain Specific Languages
A pattern match will error in the case the sides cant match. This is, for example,
the case when the tuples have different sizes:
S PON SORS
iex> {a, b, c} = {:hello, "world"}
** (MatchError) no match of right hand side value: {:hello,
"world"}
And also when comparing different types:
EL IX I R RA D AR
A weekly Elixir email newsletter
with content curated by
iex> {a, b, c} = [:hello, "world", "!"]
** (MatchError) no match of right hand side value: [:hello,
"world", "!"]
More interestingly, we can match on specific values. The example below asserts
that the left side will only match the right side when the right side is a tuple that
starts with the atom :ok:
Plataformatec. Subscribe
below.
Elixir
Radar
weekly
Subscribe
now
newsletter
iex> {:ok, result} = {:ok, 13}
{:ok, 13}
iex> result
13
iex> {:ok, result} = {:error, :oops}
** (MatchError) no match of right hand side value: {:error,
:oops}
http://elixir-lang.org/getting-started/pattern-matching.html
2/5
3/8/2016
Pattern matching - Elixir
We can pattern match on lists:
iex> [a, b, c] = [1, 2, 3]
[1, 2, 3]
iex> a
1
A list also supports matching on its own head and tail:
iex> [head | tail] = [1, 2, 3]
[1, 2, 3]
iex> head
1
iex> tail
[2, 3]
Similar to the hd/1 and tl/1 functions, we cant match an empty list with a
head and tail pattern:
iex> [h|t] = []
** (MatchError) no match of right hand side value: []
The [head | tail] format is not only used on pattern matching but also for
prepending items to a list:
iex> list = [1, 2, 3]
[1, 2, 3]
iex> [0|list]
[0, 1, 2, 3]
Pattern matching allows developers to easily destructure data types such as
tuples and lists. As we will see in following chapters, it is one of the foundations
of recursion in Elixir and applies to other types as well, like maps and binaries.
The pin operator
Variables in Elixir can be rebound:
iex> x = 1
1
iex> x = 2
2
http://elixir-lang.org/getting-started/pattern-matching.html
3/5
3/8/2016
Pattern matching - Elixir
The pin operator ^ should be used when you want to pattern match against an
existing variables value rather than rebinding the variable:
iex> x = 1
1
iex> ^x = 2
** (MatchError) no match of right hand side value: 2
iex> {y, ^x} = {2, 1}
{2, 1}
iex> y
2
iex> {y, ^x} = {2, 2}
** (MatchError) no match of right hand side value: {2, 2}
Because we have assigned the value of 1 to the variable x, this last example could
also have been written as:
iex> {y, 1} = {2, 2}
** (MatchError) no match of right hand side value: {2, 2}
If a variable is mentioned more than once in a pattern, all references should
bind to the same pattern:
iex> {x, x} = {1, 1}
1
iex> {x, x} = {1, 2}
** (MatchError) no match of right hand side value: {1, 2}
In some cases, you dont care about a particular value in a pattern. It is a
common practice to bind those values to the underscore, _. For example, if
only the head of the list matters to us, we can assign the tail to underscore:
iex> [h|_] = [1, 2, 3]
[1, 2, 3]
iex> h
1
The variable _ is special in that it can never be read from. Trying to read from
it gives an unbound variable error:
iex> _
http://elixir-lang.org/getting-started/pattern-matching.html
4/5
3/8/2016
Pattern matching - Elixir
** (CompileError) iex:1: unbound variable _
Although pattern matching allows us to build powerful constructs, its usage is
limited. For instance, you cannot make function calls on the left side of a match.
The following example is invalid:
iex> length([1,[2],3]) = 3
** (CompileError) iex:1: illegal pattern
This finishes our introduction to pattern matching. As we will see in the next
chapter, pattern matching is very common in many language constructs.
Previous
Top
Next
2012-2016 Plataformatec. All rights reserved.
http://elixir-lang.org/getting-started/pattern-matching.html
5/5
