Pattern matching with variables and the pin operator

Is this expected behavior or am I missing something conceptually?

Erlang/OTP 24 [erts-12.1.2] [source] [64-bit] [smp:12:12] [ds:12:12:10] [async-threads:1] [jit]

Interactive Elixir (1.12.2) - press Ctrl+C to exit (type h() ENTER for help)
iex(1)> l = %{a: 1}
%{a: 1}
iex(2)> %{a: 1} = %{a: 1, b: 2}
%{a: 1, b: 2}
iex(3)> ^l = %{a: 1, b: 2}     
** (MatchError) no match of right hand side value: %{a: 1, b: 2}

I expected the last match to be successful. What misconception do I have?

I am not sure if this is addressed in any official documentation, but I couldn’t find any relevant discussion in the docs or the official guides.

You are trying to pattern match within the pin operator.

This is what is expected.

iex> ^l = %{a: 1} 
%{a: 1}

1 Like

I believe what it is trying to do is an exact match, so ^l = %{a: 1, b: 2} could be thought of like:

%{a: 1} == %{a: 1, b: 2}
1 Like

Pinning match is always exact equality (otherwise there would be no way to match %{} for example


I realized that it was performing an exact match. However, I cannot see why this is necessary. I thought that after the i = %{a: 1} match and binding that ^i = %{a: 1, b: 2} would involve a substitution of %{a: 1} for ^i resulting an the match %{a: 1} = %{a: 1, b: 2}, which should succeed.

Thank you for your reply.

Thank you for your reply. I still do not understand why an exact match is needed. Why would there be no way to match %{}?

In %{a: 1} = %{a: 1, b: 2}
We are matching the values inside the map. a in this case, and since they are both 1, it matches.

In ^l = %{a: 1, b: 2}
We are matching the entire map. Not only the k/v inside

I am sorry to carry on the issue but I understand that the match is exact. My question is why is the semantics of

^l = %{a: 1, b: 2}

different from

%{a: 1} = %{a: 1, b: 2}

even though ^l refers to the value of l which is %{a: 1}?

If this is the semantics by design, then I think it should be made explicit for novices like me as this is a bit confusing.
I can accept that the semantics is different but I don’t want to just know that they are semantically different I want to understand.

1 Like

Map matching is commonly used for destructuring a map, ie: %{key1: value} = %{key1: 1, key2: 2} will bind value to 1. So this has to be a partial match.

With a pin operator, there is no new binding of variable so it does not make sense to do partial match anymore.

Think this way, the partial match is a special case for convenience. The full match is the normal case.


to be fair, this is SUPER confusing because maps are the only datastructure which afford you inexplicit partial matching in elixir. Occasionally this causes problems when refactoring because in tests i often assert with matching instead asserting with equality.

in general, the map partial match %{a: a} = some_map should be thought of as the (“not legal code”) %{a: a, ...} = some_map

@olivierdevon in light of this, one way to explain is that from an experienced elixir dev’s pov, what you are expecting to happen is that the pin operator matching is a lexical match against the variable, but that’s not possible because in general lexical content is thrown away once the variable is assigned.

1 Like

The mismatch here is that the runtime value of %{a: 1} is not a pattern to match against. Patterns on the beam are not a datatype, but they’re compiled from code. You can only hardcode patterns (or do metaprograming on their AST), but you cannot create pattern matches from runtime values.

Patterns not being higher order is a limitation of the beam. This is the reason why a pinned variable can only ever be compared to be equal, but not be used as a pattern.


Thanks @LostKobrakai that’s the best answer I’ve seen to this question so far.

So the reason why this works:

iex(2)> one = 1
iex(3)> %{a: ^one} = %{a: 1, b: 2}
%{a: 1, b: 2}

But this one doesn’t:

iex(1)> map_with_one = %{a: 1}
%{a: 1}
iex(2)> ^map_with_one = %{a: 1, b: 2}
** (MatchError) no match of right hand side value: %{a: 1, b: 2}

Is because the pin operator can only be used for exact matches but not for partial ones, the reason being intrinsic limitations of the BEAM. Correct?

Yes, but I’d suggest not even trying to think of it like that. There’s (runtime) data assigned to a variable like map_with_one and there’s syntax, which can in some cases look exactly like the syntax used to define the data for map_with_one, but which forms a pattern for a pattern match. One is completely unrelated to the other. This becomes even more apparent when you consider the features of a match pattern, which a map of data doesn’t support, like _ for ignoring values or variable assignments %{a: a} = ….

The pin operator is a way to use data assigned to a variable to be equality matched within a pattern. Nothing more and nothing less. It does not become a pattern by itself. Patterns are compile time structures, which cannot be adjusted at runtime, stored in a variable or otherwise modified after compilation is done. Only patterns can be used for a pattern match on the left side of the match operator (=). When you put a variable on the left side it’s either an assignment, or if you use a pin an equality check to match the pattern.


Thanks! Excellent explanation :+1: