Definition

Pattern matching is a language feature that checks a value against a structural pattern and, if successful, destructures the value by binding its components to variables. In Elixir, pattern matching replaces most conditional logic with declarative multi-clause function definitions, case expressions, and the match operator (=). It is the primary control flow mechanism in the language, enabling concise, self-documenting code that handles different data shapes explicitly through separate function clauses rather than nested if/else chains.

Unlike equality checks or switch statements in imperative languages, pattern matching simultaneously performs three operations: it tests whether data conforms to an expected shape, it extracts components from the data by binding them to variables, and it selects the appropriate code path based on the match result. This unification of testing, extraction, and dispatch into a single syntactic construct makes Elixir code remarkably dense yet readable. A function with five clauses communicates five distinct cases and their handling in a format that is both machine-checkable and human-readable.

Pattern matching interacts deeply with Elixir's other core features. Immutability guarantees that matched data will not change during or after the match. The pipe operator chains functions that use pattern matching internally. Behaviours define callback signatures that are implemented through multi-clause pattern-matched functions. Ecto queries use pattern matching for result destructuring. Pattern matching is not merely a feature of Elixir -- it is the idiom through which all Elixir code is organized.

The Match Operator

The = operator in Elixir is the match operator, not an assignment operator. It attempts to match the left-hand side pattern against the right-hand side value:

# Simple binding (trivially matches any value)
x = 42

# Structure matching -- binds 'name' and 'role' from the map
%{name: name, role: role} = %{name: "Alice", role: :admin, id: 1}
# name = "Alice", role = :admin

# Tuple matching -- the standard Elixir result convention
{:ok, result} = {:ok, %{score: 850}}
# result = %{score: 850}

# Failure case -- MatchError raised when pattern doesn't match
# {:ok, result} = {:error, :not_found}
# ** (MatchError) no match of right hand side value: {:error, :not_found}

# Nested matching -- extracts deeply nested values
%{security: %{rating: %{grade: grade}}} = assessment
# grade bound to whatever value is at that path

The Pin Operator

The pin operator (^) forces a variable to be treated as its current value rather than a new binding. This is essential for matching against existing values:

expected_domain = "example.com"

# Without pin: 'domain' would be rebound to whatever value is in the map
%{domain: domain} = %{domain: "other.com"}
# domain = "other.com" (rebound)

# With pin: matches ONLY if domain equals "example.com"
%{domain: ^expected_domain} = %{domain: "example.com"}
# Succeeds -- value matches pinned variable

# %{domain: ^expected_domain} = %{domain: "other.com"}
# ** (MatchError) -- fails because "other.com" != "example.com"

Multi-Clause Function Definitions

Pattern matching's most powerful application is multi-clause function definitions, where different clauses handle different input shapes:

defmodule SecurityGrade do
  @spec assign(float()) :: atom()
  def assign(score) when score >= 800.0, do: :A
  def assign(score) when score >= 650.0, do: :B
  def assign(score) when score >= 500.0, do: :C
  def assign(score) when score >= 350.0, do: :D
  def assign(_score), do: :F
end

defmodule ResultHandler do
  # Each clause handles a different result shape
  def handle({:ok, %{data: data, meta: meta}}) do
    process_success(data, meta)
  end

  def handle({:ok, data}) when is_list(data) do
    process_batch(data)
  end

  def handle({:error, %{code: :not_found, resource: resource}}) do
    log_missing(resource)
    {:error, :not_found}
  end

  def handle({:error, %{code: :timeout}}) do
    {:retry, :exponential_backoff}
  end

  def handle({:error, reason}) do
    log_error(reason)
    {:error, reason}
  end
end

Guards

Guards extend pattern matching with additional constraints that go beyond structural shape. Guards appear in when clauses and support a restricted set of expressions that are guaranteed to be side-effect-free:

defmodule Validator do
  # Guards refine matches with type checks and comparisons
  def validate_score(score) when is_float(score) and score >= 300.0 and score <= 900.0 do
    {:ok, score}
  end

  def validate_score(score) when is_float(score) do
    {:error, :out_of_range}
  end

  def validate_score(_), do: {:error, :invalid_type}

  # Custom guard (defined with defguard for reuse)
  defguard is_valid_port(port) when is_integer(port) and port >= 1 and port <= 65535

  def validate_endpoint(host, port) when is_binary(host) and is_valid_port(port) do
    {:ok, {host, port}}
  end
end

Guard Category	Examples	Use Case
Type Checks	`is_atom/1`, `is_binary/1`, `is_map/1`, `is_list/1`	Dispatch on type
Comparisons	`>`, `<`, `>=`, `<=`, `==`, `!=`	Range validation
Boolean	`and`, `or`, `not`	Combining conditions
Arithmetic	`+`, `-`, `*`, `/`, `rem/2`, `abs/1`	Numeric constraints
Map/Tuple	`map_size/1`, `tuple_size/1`, `elem/2`	Structure size checks
String	`byte_size/1`, `bit_size/1`	Binary constraints
Custom	`defguard` macros	Domain-specific guards