Pattern Matching

Struggling with nested data extraction? This guide teaches pattern matching techniques for destructuring complex structures, dispatching functions, validating data, and controlling program flow in Elixir.

Problem

Pattern matching is fundamental to Elixir, but beginners often:

Overuse explicit conditionals instead of pattern matching
Miss opportunities for function head dispatch
Struggle with nested structure extraction
Don’t leverage guards for validation
Write verbose code when patterns could be concise

Prerequisites

Quick Start Tutorial - Basic pattern matching
Beginner Tutorial - Data structures

Solution Overview

Pattern matching in Elixir:

Assignment: Binds values to variables
Assertion: Verifies structure matches pattern
Extraction: Pulls data from complex structures
Dispatch: Routes to different code paths

Basic Patterns

Simple Value Matching

{:ok, value} = {:ok, 42}

{:error, reason} = {:error, :not_found}

{:ok, result} = {:error, "fail"}

List Patterns

[head | tail] = [1, 2, 3, 4, 5]

[first, second | rest] = [1, 2, 3, 4]

[] = []

[a, b, c] = [1, 2, 3]

[x, y] = [1, 2, 3]

Map Patterns

%{name: name, age: age} = %{name: "Alice", age: 30, city: "NYC"}

%{id: id} = %{name: "Bob"}

%{status: :ok, data: data} = %{status: :ok, data: [1, 2, 3]}

Tuple Patterns

{:ok, value, timestamp} = {:ok, 42, ~U[2024-12-21 10:00:00Z]}

{:user, {name, age}, {city, country}} =
  {:user, {"Alice", 30}, {"NYC", "USA"}}

Advanced Patterns

Nested Structure Extraction

Problem: Extract data from deeply nested structures.

Solution:

defmodule UserExtractor do
  # Extract from nested API response
  def extract_user_data(response) do
    %{
      status: 200,
      body: %{
        user: %{
          id: id,
          profile: %{
            name: name,
            contacts: %{email: email, phone: phone}
          },
          settings: %{theme: theme}
        }
      }
    } = response

    %{
      id: id,
      name: name,
      email: email,
      phone: phone,
      theme: theme
    }
  end

  # With validation
  def extract_valid_user(response) do
    case response do
      %{
        status: 200,
        body: %{user: %{id: id, profile: %{name: name}} = user}
      } when is_integer(id) and is_binary(name) ->
        {:ok, user}

      %{status: status} when status >= 400 ->
        {:error, :http_error}

      _ ->
        {:error, :invalid_response}
    end
  end
end

response = %{
  status: 200,
  body: %{
    user: %{
      id: 123,
      profile: %{
        name: "Alice",
        contacts: %{email: "alice@example.com", phone: "555-1234"}
      },
      settings: %{theme: :dark}
    }
  }
}

UserExtractor.extract_user_data(response)

How It Works: Nested pattern matches entire structure. Binds only needed variables. Validates structure in one expression.

Function Head Dispatch

Problem: Handle different input types without conditionals.

Solution:

defmodule Calculator do
  # Pattern match on operation type
  def calculate({:add, a, b}), do: a + b
  def calculate({:subtract, a, b}), do: a - b
  def calculate({:multiply, a, b}), do: a * b
  def calculate({:divide, a, 0}), do: {:error, :division_by_zero}
  def calculate({:divide, a, b}), do: a / b

  # Handle errors
  def calculate(_), do: {:error, :unknown_operation}
end

Calculator.calculate({:add, 5, 3})        # => 8
Calculator.calculate({:divide, 10, 2})    # => 5.0
Calculator.calculate({:divide, 10, 0})    # => {:error, :division_by_zero}
Calculator.calculate({:unknown, 1, 2})    # => {:error, :unknown_operation}

defmodule EventHandler do
  # Different event types
  def handle_event(%{type: :user_created, data: %{name: name, email: email}}) do
    send_welcome_email(email, name)
  end

  def handle_event(%{type: :user_updated, data: %{id: id, changes: changes}}) do
    sync_user_changes(id, changes)
  end

  def handle_event(%{type: :user_deleted, data: %{id: id}}) do
    cleanup_user_data(id)
  end

  # Catch-all for unknown events
  def handle_event(event) do
    Logger.warn("Unknown event: #{inspect(event)}")
    :ok
  end

  defp send_welcome_email(_email, _name), do: :ok
  defp sync_user_changes(_id, _changes), do: :ok
  defp cleanup_user_data(_id), do: :ok
end

How It Works: Elixir tries function clauses top-to-bottom. First matching pattern executes. Specific patterns before general ones.

Pin Operator for Exact Matching

Problem: Match against existing variable value, not rebind.

Solution:

defmodule Validator do
  # Match expected value
  def validate_status(response, expected_status) do
    case response do
      %{status: ^expected_status, body: body} ->
        {:ok, body}

      %{status: other_status} ->
        {:error, "Expected #{expected_status}, got #{other_status}"}
    end
  end

  # Filter list by value
  def find_by_id(items, target_id) do
    Enum.filter(items, fn
      %{id: ^target_id} -> true
      _ -> false
    end)
  end

  # Validate matching fields
  def validate_passwords(%{password: pass, password_confirmation: pass}) do
    {:ok, pass}
  end

  def validate_passwords(_) do
    {:error, "Passwords do not match"}
  end
end

response = %{status: 200, body: "Success"}
Validator.validate_status(response, 200)

Validator.validate_status(response, 404)

target = :admin
users = [
  %{id: 1, role: :admin},
  %{id: 2, role: :user},
  %{id: 3, role: :admin}
]

for %{role: ^target} = user <- users, do: user

How It Works: ^var uses variable’s current value in pattern. Without pin, variable would rebind to new value.

Guards for Additional Validation

Problem: Pattern match with conditional checks.

Solution:

defmodule GuardExamples do
  # Type guards
  def process(value) when is_integer(value), do: {:int, value * 2}
  def process(value) when is_binary(value), do: {:string, String.upcase(value)}
  def process(value) when is_list(value), do: {:list, length(value)}

  # Range guards
  def categorize_age(age) when age < 13, do: :child
  def categorize_age(age) when age < 20, do: :teenager
  def categorize_age(age) when age < 65, do: :adult
  def categorize_age(_age), do: :senior

  # Multiple conditions
  def valid_user?(%{age: age, email: email})
      when is_integer(age) and age >= 18 and is_binary(email) do
    String.contains?(email, "@")
  end

  def valid_user?(_), do: false

  # Complex guards
  def can_vote?(%{age: age, country: country})
      when age >= 18 and country in ["USA", "UK", "Canada"] do
    true
  end

  def can_vote?(_), do: false

  # Guard with pattern
  def handle_result({:ok, value}) when is_integer(value) and value > 0 do
    {:valid, value}
  end

  def handle_result({:ok, value}) when is_integer(value) do
    {:invalid, "Value must be positive"}
  end

  def handle_result({:error, reason}) do
    {:error, reason}
  end
end

GuardExamples.process(42)           # => {:int, 84}
GuardExamples.process("hello")      # => {:string, "HELLO"}
GuardExamples.process([1, 2, 3])    # => {:list, 3}

GuardExamples.categorize_age(10)    # => :child
GuardExamples.categorize_age(15)    # => :teenager
GuardExamples.categorize_age(30)    # => :adult

GuardExamples.valid_user?(%{age: 25, email: "user@example.com"})

GuardExamples.can_vote?(%{age: 21, country: "USA"})

How It Works: Guards execute after pattern match succeeds. Limited to safe expressions (no side effects). Multiple conditions with and, or.