Understanding Elixir's Pin Operator

April 28, 2020

The best way to understand Elixir’s pin operator ^ is with relatable examples.


Users are allowed to change their passwords before they do, they will have to provide a new password and their previous password.


In a language like JavaScript, we can write a naive solution like so

let current_password = 'secret-1';

const params = {
  new_password: 'secret-2',
  current_password: 'secret-2'

if (current_password !== params.current_password) {
  throw "Match Error"

The above will throw a Match Error because the user’s supplied password does not match their current password

Using Elixir’s pin operator we can write the above as

current_password = 'secret-1'

{ new_password, ^current_password } = { 'secret-2', 'secret-2'}

The above will also rais a MatchError exception


Use the pin operator ^ to pattern match against an existing variable’s value. In the Elixir’s example above, the variable new_password is bound to the first item in the tuple (Elixirs data structure represented with {}), rather than rebinding the current_password variable, we pattern match against its existing value.

Now this example from Elixir’s docs should make sense.

iex(1)> x = 1
iex(2)> ^x = 1 # Matches previous value 1
iex(3)> ^x = 2 # Does not match previous value 
** (MatchError) no match of right hand side value: 2

Damian Simon Peter

Hi, I am Damian Simon Peter a software developer based in Waterloo, Ontario. I have spent the past years working for early-stage startups, building backend and frontend applications primarily using Ruby and JavaScript. I own a System76 Galago Pro running Pop!_OS and absolutely love it.