DEV Community: João Paulo Abreu

Learning Elixir: Error Handling Basics

João Paulo Abreu — Tue, 31 Mar 2026 19:36:59 +0000

I like to think of error handling in Elixir as a reliable postal service.
Every package either arrives successfully with its contents ({:ok, value}) or comes back with a clear note explaining the delivery failure ({:error, reason}).
Unlike languages that use exceptions as their primary error mechanism, Elixir treats errors as values that flow through your code like any other value.
That makes control flow explicit and easier to reason about, especially when you are learning.
In this article, we'll explore how this pattern works, why it's idiomatic Elixir, and how to use it to build reliable and readable programs.

Note: The examples in this article use Elixir 1.19.5. While most operations should work across different versions, some functionality might vary.

Introduction
The Ok/Error Tuple Pattern
Returning Results from Functions
Handling Results at the Call Site
Chaining Operations with with
The Bang Convention
Practical Patterns
Best Practices
Conclusion
Further Reading
Next Steps

Introduction

Elixir encourages a style of error handling where functions return explicit values for success and failure.
I like to think of {:ok, value} and {:error, reason} as two lanes: your code stays in the success lane when things are fine, or moves to the error lane when something goes wrong.
The Elixir standard library, as well as most popular libraries, follow this convention consistently.

The Ok/Error Tuple Pattern

The Core Convention

One way I learned to read Elixir code is this: if a function can fail, it often returns a tuple with a status atom as the first element.

# Successful result
{:ok, "some value"}
{:ok, 42}
{:ok, %{name: "Alice", age: 30}}

# Error result
{:error, :not_found}
{:error, "invalid input"}
{:error, {:validation_failed, [:name, :email]}}

Testing in IEx:

iex> {:ok, "hello"}
{:ok, "hello"}

iex> {:error, :not_found}
{:error, :not_found}

iex> elem({:ok, 42}, 0)
:ok

iex> elem({:ok, 42}, 1)
42

Why Tagged Tuples?

I found this pattern especially useful because it integrates naturally with pattern matching:

# Without tagged tuples, you might check for nil
defmodule BadExample do
  def find_user(id) do
    # Returns nil on failure - ambiguous!
    if id == 1, do: %{name: "Alice"}, else: nil
  end
end

# With tagged tuples, the intent is clear
defmodule GoodExample do
  def find_user(1), do: {:ok, %{name: "Alice"}}
  def find_user(_id), do: {:error, :not_found}
end

Testing in IEx:

iex> GoodExample.find_user(1)
{:ok, %{name: "Alice"}}

iex> GoodExample.find_user(99)
{:error, :not_found}

iex> {:ok, user} = GoodExample.find_user(1)
{:ok, %{name: "Alice"}}
iex> "Found: #{user.name}"
"Found: Alice"

Standard Library Examples

I keep seeing this convention across the Elixir standard library:

defmodule StandardLibraryExamples do
  def demonstrate_file_read do
    case File.read("existing_file.txt") do
      {:ok, contents} -> IO.puts("File contents: #{contents}")
      {:error, :enoent} -> IO.puts("File does not exist")
      {:error, reason} -> IO.puts("Error reading file: #{inspect(reason)}")
    end
  end

  def demonstrate_integer_parse do
    case Integer.parse("42") do
      {number, ""} -> {:ok, number}
      {number, _rest} -> {:ok, number}  # partial parse
      :error -> {:error, "not a number"}
    end
  end

  def demonstrate_map_access do
    map = %{name: "Alice"}
    case Map.fetch(map, :name) do
      {:ok, name} -> "Name is: #{name}"
      :error -> "Key not found"
    end
  end
end

Testing in IEx:

iex> StandardLibraryExamples.demonstrate_file_read()
File does not exist
:ok

iex> StandardLibraryExamples.demonstrate_integer_parse()
{:ok, 42}

iex> StandardLibraryExamples.demonstrate_map_access()
"Name is: Alice"

# Direct module function calls for comparison:
iex> File.read("definitely_missing_file.txt")
{:error, :enoent}

iex> Map.fetch(%{name: "Alice"}, :name)
{:ok, "Alice"}

iex> Map.fetch(%{name: "Alice"}, :email)
:error

iex> Integer.parse("42")
{42, ""}

iex> Integer.parse("not a number")
:error

iex> Integer.parse("42abc")
{42, "abc"}

Returning Results from Functions

Basic Function Patterns

defmodule UserRepository do
  @users %{
    1 => %{id: 1, name: "Alice", email: "alice@example.com", active: true},
    2 => %{id: 2, name: "Bob", email: "bob@example.com", active: false}
  }

  def find(id) do
    case Map.fetch(@users, id) do
      {:ok, user} -> {:ok, user}
      :error -> {:error, :not_found}
    end
  end

  def find_active(id) do
    case find(id) do
      {:ok, %{active: true} = user} -> {:ok, user}
      {:ok, %{active: false}} -> {:error, :user_inactive}
      {:error, reason} -> {:error, reason}
    end
  end

  def list_all do
    {:ok, Map.values(@users)}
  end
end

Testing in IEx:

iex> UserRepository.find(1)
{:ok, %{id: 1, name: "Alice", email: "alice@example.com", active: true}}

iex> UserRepository.find(99)
{:error, :not_found}

iex> UserRepository.find_active(1)
{:ok, %{id: 1, name: "Alice", email: "alice@example.com", active: true}}

iex> UserRepository.find_active(2)
{:error, :user_inactive}

Validation Functions

defmodule UserValidator do
  def validate_email(email) when is_binary(email) do
    if String.contains?(email, "@") and String.contains?(email, ".") do
      {:ok, String.downcase(email)}
    else
      {:error, {:invalid_email, email}}
    end
  end

  def validate_email(_other) do
    {:error, :email_must_be_string}
  end

  def validate_age(age) when is_integer(age) and age >= 0 and age <= 150 do
    {:ok, age}
  end

  def validate_age(age) when is_integer(age) do
    {:error, {:age_out_of_range, age}}
  end

  def validate_age(_other) do
    {:error, :age_must_be_integer}
  end

  def validate_name(name) when is_binary(name) and byte_size(name) > 0 do
    trimmed = String.trim(name)
    if byte_size(trimmed) > 0 do
      {:ok, trimmed}
    else
      {:error, :name_cannot_be_blank}
    end
  end

  def validate_name(_other) do
    {:error, :name_must_be_string}
  end
end

Testing in IEx:

iex> UserValidator.validate_email("alice@example.com")
{:ok, "alice@example.com"}

iex> UserValidator.validate_email("ALICE@EXAMPLE.COM")
{:ok, "alice@example.com"}

iex> UserValidator.validate_email("not-an-email")
{:error, {:invalid_email, "not-an-email"}}

iex> UserValidator.validate_age(25)
{:ok, 25}

iex> UserValidator.validate_age(-5)
{:error, {:age_out_of_range, -5}}

iex> UserValidator.validate_name("  Alice  ")
{:ok, "Alice"}

iex> UserValidator.validate_name("   ")
{:error, :name_cannot_be_blank}

Enriching Error Reasons

Error reasons can carry as much context as needed:

defmodule DataParser do
  def parse_config(raw_config) when is_map(raw_config) do
    with {:ok, host} <- extract_host(raw_config),
         {:ok, port} <- extract_port(raw_config),
         {:ok, timeout} <- extract_timeout(raw_config) do
      {:ok, %{host: host, port: port, timeout: timeout}}
    end
  end

  def parse_config(_other) do
    {:error, {:invalid_input, "config must be a map"}}
  end

  defp extract_host(%{"host" => host}) when is_binary(host) and byte_size(host) > 0 do
    {:ok, host}
  end

  defp extract_host(%{"host" => host}) do
    {:error, {:invalid_field, :host, "must be a non-empty string, got: #{inspect(host)}"}}
  end

  defp extract_host(_map) do
    {:error, {:missing_field, :host}}
  end

  defp extract_port(%{"port" => port}) when is_integer(port) and port > 0 and port <= 65535 do
    {:ok, port}
  end

  defp extract_port(%{"port" => port}) do
    {:error, {:invalid_field, :port, "must be integer 1-65535, got: #{inspect(port)}"}}
  end

  defp extract_port(_map) do
    {:ok, 4000}  # default port
  end

  defp extract_timeout(%{"timeout" => timeout}) when is_integer(timeout) and timeout > 0 do
    {:ok, timeout}
  end

  defp extract_timeout(%{"timeout" => timeout}) do
    {:error, {:invalid_field, :timeout, "must be a positive integer, got: #{inspect(timeout)}"}}
  end

  defp extract_timeout(_map) do
    {:ok, 5000}  # default timeout
  end
end

Testing in IEx:

iex> DataParser.parse_config(%{"host" => "localhost", "port" => 8080})
{:ok, %{host: "localhost", port: 8080, timeout: 5000}}

iex> DataParser.parse_config(%{"host" => "localhost"})
{:ok, %{host: "localhost", port: 4000, timeout: 5000}}

iex> DataParser.parse_config(%{"host" => "", "port" => 8080})
{:error, {:invalid_field, :host, "must be a non-empty string, got: \"\""}}

iex> DataParser.parse_config(%{"port" => 8080})
{:error, {:missing_field, :host}}

iex> DataParser.parse_config("not a map")
{:error, {:invalid_input, "config must be a map"}}

Handling Results at the Call Site

Using case

The most explicit way to handle a result is with case:

defmodule UserController do
  def show_user(user_id) do
    case UserRepository.find(user_id) do
      {:ok, user} ->
        IO.puts("Found user: #{user.name} (#{user.email})")

      {:error, :not_found} ->
        IO.puts("Error: User #{user_id} does not exist")

      {:error, reason} ->
        IO.puts("Unexpected error: #{inspect(reason)}")
    end
  end

  def create_user(params) do
    case validate_and_create(params) do
      {:ok, user} ->
        IO.puts("Created user: #{inspect(user)}")
        {:ok, user}

      {:error, :validation_failed, errors} ->
        IO.puts("Validation failed: #{inspect(errors)}")
        {:error, :validation_failed, errors}

      {:error, reason} ->
        IO.puts("Failed to create user: #{inspect(reason)}")
        {:error, reason}
    end
  end

  defp validate_and_create(%{name: name, email: email}) do
    with {:ok, valid_name} <- UserValidator.validate_name(name),
         {:ok, valid_email} <- UserValidator.validate_email(email) do
      {:ok, %{name: valid_name, email: valid_email}}
    end
  end

  defp validate_and_create(_params) do
    {:error, :missing_required_fields}
  end
end

Testing in IEx:

iex> UserController.show_user(1)
Found user: Alice (alice@example.com)
:ok

iex> UserController.show_user(99)
Error: User 99 does not exist
:ok

iex> UserController.create_user(%{name: "Charlie", email: "charlie@example.com"})
Created user: %{email: "charlie@example.com", name: "Charlie"}
{:ok, %{email: "charlie@example.com", name: "Charlie"}}

iex> UserController.create_user(%{name: "", email: "charlie@example.com"})
Failed to create user: :name_must_be_string
{:error, :name_must_be_string}

Pattern Matching in Function Clauses

You can also handle results directly through function clause pattern matching:

defmodule ResultProcessor do
  # Handle success
  def process_result({:ok, value}) do
    "Success: #{inspect(value)}"
  end

  # Handle specific errors
  def process_result({:error, :not_found}) do
    "The requested item was not found"
  end

  def process_result({:error, :unauthorized}) do
    "You do not have permission to perform this action"
  end

  # Handle generic errors
  def process_result({:error, reason}) do
    "An error occurred: #{inspect(reason)}"
  end

  # Batch processing
  def process_many(results) do
    Enum.map(results, fn result ->
      case result do
        {:ok, value} -> {:processed, value}
        {:error, reason} -> {:failed, reason}
      end
    end)
  end

  # Separate successes from errors
  def partition_results(results) do
    Enum.split_with(results, fn
      {:ok, _} -> true
      {:error, _} -> false
    end)
  end
end

Testing in IEx:

iex> ResultProcessor.process_result({:ok, %{id: 1, name: "Alice"}})
"Success: %{id: 1, name: \"Alice\"}"

iex> ResultProcessor.process_result({:error, :not_found})
"The requested item was not found"

iex> ResultProcessor.process_result({:error, :something_else})
"An error occurred: :something_else"

iex> results = [{:ok, 1}, {:error, :bad}, {:ok, 2}, {:error, :worse}, {:ok, 3}]
[{:ok, 1}, {:error, :bad}, {:ok, 2}, {:error, :worse}, {:ok, 3}]

iex> ResultProcessor.partition_results(results)
{[{:ok, 1}, {:ok, 2}, {:ok, 3}], [{:error, :bad}, {:error, :worse}]}

Extracting Values Safely

Sometimes it's useful to extract values directly or apply transformations:

defmodule SafeExtractor do
  # Extract the value or return a default
  def unwrap_or({:ok, value}, _default), do: value
  def unwrap_or({:error, _reason}, default), do: default

  # Transform the value inside {:ok, _}
  def map({:ok, value}, fun), do: {:ok, fun.(value)}
  def map({:error, _} = error, _fun), do: error
end

Testing in IEx:

iex> SafeExtractor.unwrap_or({:ok, "value"}, "default")
"value"

iex> SafeExtractor.unwrap_or({:error, :not_found}, "default")
"default"

iex> SafeExtractor.map({:ok, 5}, fn x -> x * 2 end)
{:ok, 10}

iex> SafeExtractor.map({:error, :bad}, fn x -> x * 2 end)
{:error, :bad}

Chaining Operations with with

I found with very helpful for chaining operations that return {:ok, value} or {:error, reason}. It stops at the first failure, which keeps the flow easy to follow.

Basic with Usage

defmodule RegistrationService do
  def register_user(params) do
    with {:ok, name} <- UserValidator.validate_name(params[:name]),
         {:ok, email} <- UserValidator.validate_email(params[:email]),
         {:ok, age} <- UserValidator.validate_age(params[:age]),
         {:ok, user} <- create_user_record(name, email, age) do
      {:ok, user}
    end
  end

  defp create_user_record(name, email, age) do
    # Simulate saving to database
    user = %{id: :rand.uniform(1000), name: name, email: email, age: age}
    {:ok, user}
  end
end

Testing in IEx:

iex> RegistrationService.register_user(%{name: "Alice", email: "alice@example.com", age: 28})
{:ok, %{id: 742, name: "Alice", email: "alice@example.com", age: 28}}

iex> RegistrationService.register_user(%{name: "", email: "alice@example.com", age: 28})
{:error, :name_cannot_be_blank}

iex> RegistrationService.register_user(%{name: "Alice", email: "not-valid", age: 28})
{:error, {:invalid_email, "not-valid"}}

iex> RegistrationService.register_user(%{name: "Alice", email: "alice@example.com", age: -5})
{:error, {:age_out_of_range, -5}}

with and Custom Error Handling

The else clause in with lets you handle errors in one place:

defmodule OrderService do
  def place_order(user_id, product_id, quantity) do
    with {:ok, user} <- UserRepository.find_active(user_id),
         {:ok, product} <- find_product(product_id),
         {:ok, stock} <- check_stock(product, quantity),
         {:ok, order} <- create_order(user, product, stock, quantity) do
      {:ok, order}
    else
      {:error, :not_found} ->
        {:error, "User or product not found"}

      {:error, :user_inactive} ->
        {:error, "User account is not active"}

      {:error, {:insufficient_stock, available}} ->
        {:error, "Only #{available} items in stock"}

      {:error, reason} ->
        {:error, "Order failed: #{inspect(reason)}"}
    end
  end

  defp find_product(id) do
    products = %{
      101 => %{id: 101, name: "Elixir Book", price: 49.90, stock: 5},
      102 => %{id: 102, name: "Erlang Book", price: 39.90, stock: 0}
    }

    case Map.fetch(products, id) do
      {:ok, product} -> {:ok, product}
      :error -> {:error, :not_found}
    end
  end

  defp check_stock(%{stock: stock}, quantity) when stock >= quantity do
    {:ok, stock}
  end

  defp check_stock(%{stock: stock}, _quantity) do
    {:error, {:insufficient_stock, stock}}
  end

  defp create_order(user, product, _stock, quantity) do
    order = %{
      id: :rand.uniform(10000),
      user_id: user.id,
      product_id: product.id,
      quantity: quantity,
      total: product.price * quantity
    }

    {:ok, order}
  end
end

Testing in IEx:

iex> OrderService.place_order(1, 101, 2)
{:ok,
 %{
   id: 5839,
   user_id: 1,
   product_id: 101,
   quantity: 2,
   total: 99.8
 }}

iex> OrderService.place_order(99, 101, 2)
{:error, "User or product not found"}

iex> OrderService.place_order(2, 101, 2)
{:error, "User account is not active"}

iex> OrderService.place_order(1, 102, 1)
{:error, "Only 0 items in stock"}

Mixing Different Result Shapes

Sometimes you need to handle results from functions that don't return {:ok, _} / {:error, _}.
For example, a validator might return just :ok or {:error, _}. In these cases, you can tag the results in the with clauses:

defmodule MixedResultShapes do
  def process_data(data) do
    with {:validate, :ok} <- {:validate, validate_schema(data)},
         {:save, {:ok, result}} <- {:save, save_to_db(data)} do
      {:ok, result}
    else
      {:validate, {:error, errors}} -> {:error, {:validation_error, errors}}
      {:save, {:error, reason}} -> {:error, {:save_error, reason}}
    end
  end

  defp validate_schema(%{valid: true}), do: :ok
  defp validate_schema(_), do: {:error, ["validation failed"]}

  defp save_to_db(%{save_ok: true}), do: {:ok, %{saved: true}}
  defp save_to_db(_), do: {:error, :db_error}
end

Testing in IEx:

iex> MixedResultShapes.process_data(%{valid: true, save_ok: true})
{:ok, %{saved: true}}

iex> MixedResultShapes.process_data(%{valid: false, save_ok: true})
{:error, {:validation_error, ["validation failed"]}}

iex> MixedResultShapes.process_data(%{valid: true, save_ok: false})
{:error, {:save_error, :db_error}}

# Direct tuple examples for reference:
iex> {:validate, :ok}
{:validate, :ok}

iex> {:validate, {:error, ["name is required"]}}
{:validate, {:error, ["name is required"]}}

iex> {:save, {:ok, %{name: "Alice"}}}
{:save, {:ok, %{name: "Alice"}}}

The Bang Convention

Functions with ! Suffix

In Elixir, functions with a ! suffix usually raise an exception on failure instead of returning {:error, reason}. I use this when I expect success and want failures to surface quickly.

defmodule FileProcessor do
  # Returns {:ok, contents} or {:error, reason}
  def read_file(path) do
    File.read(path)
  end

  # Raises on failure
  def read_file!(path) do
    File.read!(path)
  end

  # Custom bang version
  def find_user(id) do
    case UserRepository.find(id) do
      {:ok, user} -> {:ok, user}
      {:error, reason} -> {:error, reason}
    end
  end

  def find_user!(id) do
    case find_user(id) do
      {:ok, user} -> user
      {:error, :not_found} -> raise "User #{id} not found"
      {:error, reason} -> raise "Failed to find user: #{inspect(reason)}"
    end
  end
end

Testing in IEx:

iex> FileProcessor.find_user(1)
{:ok, %{id: 1, name: "Alice", email: "alice@example.com", active: true}}
iex> FileProcessor.find_user(99)
{:error, :not_found}
iex> FileProcessor.find_user!(1)
%{id: 1, name: "Alice", email: "alice@example.com", active: true}
iex> FileProcessor.find_user!(99)
** (RuntimeError) User 99 not found

When to Use Each

I've found a simple rule helpful: I use the non-bang version when failure is an expected part of the business logic (for example, user not found or invalid input).
I use the bang version in initialization or setup code, where a failure means the program can't continue.

defmodule ConfigExample do
  # Non-bang: failure is expected and handled by the caller
  def find_config(key), do: Map.fetch(config(), key)

  # Bang: used in startup, failure is catastrophic
  def load_required_config!(key) do
    case find_config(key) do
      {:ok, value} -> value
      :error -> raise "Required config key #{inspect(key)} is missing"
    end
  end

  defp config do
    %{app_name: "blog_elixir", version: "1.0.0"}
  end
end

Testing in IEx:

iex> ConfigExample.find_config(:app_name)
{:ok, "blog_elixir"}

iex> ConfigExample.find_config(:missing_key)
:error

iex> ConfigExample.load_required_config!(:app_name)
"blog_elixir"

iex> ConfigExample.load_required_config!(:missing_key)
** (RuntimeError) Required config key :missing_key is missing

# Direct Map.fetch examples for reference:
iex> Map.fetch(%{app_name: "blog_elixir"}, :app_name)
{:ok, "blog_elixir"}

iex> Map.fetch(%{app_name: "blog_elixir"}, :missing)
:error

Practical Patterns

A Complete Service Layer

defmodule AccountService do
  @min_password_length 8

  def create_account(attrs) do
    with {:ok, username} <- validate_username(attrs[:username]),
         {:ok, email} <- UserValidator.validate_email(attrs[:email]),
         {:ok, password} <- validate_password(attrs[:password]),
         :ok <- check_username_availability(username),
         :ok <- check_email_availability(email),
         {:ok, account} <- persist_account(username, email, password) do
      {:ok, account}
    end
  end

  defp validate_username(username) when is_binary(username) do
    trimmed = String.trim(username)
    cond do
      byte_size(trimmed) < 3 ->
        {:error, {:username_too_short, min: 3}}
      byte_size(trimmed) > 30 ->
        {:error, {:username_too_long, max: 30}}
      not String.match?(trimmed, ~r/^[a-zA-Z0-9_]+$/) ->
        {:error, :username_invalid_characters}
      true ->
        {:ok, String.downcase(trimmed)}
    end
  end

  defp validate_username(_other) do
    {:error, :username_must_be_string}
  end

  defp validate_password(password) when is_binary(password) do
    if byte_size(password) >= @min_password_length do
      {:ok, hash_password(password)}
    else
      {:error, {:password_too_short, min: @min_password_length}}
    end
  end

  defp validate_password(_other) do
    {:error, :password_must_be_string}
  end

  defp check_username_availability(username) do
    # Simulate checking database
    taken_usernames = ["admin", "root", "elixir"]
    if username in taken_usernames do
      {:error, {:username_taken, username}}
    else
      :ok
    end
  end

  defp check_email_availability(_email) do
    # Simulate checking database
    :ok
  end

  defp persist_account(username, email, password_hash) do
    account = %{
      id: :rand.uniform(100_000),
      username: username,
      email: email,
      password_hash: password_hash,
      created_at: DateTime.utc_now()
    }
    {:ok, account}
  end

  defp hash_password(password) do
    # Simulation - in real code use Bcrypt or Argon2
    :crypto.hash(:sha256, password) |> Base.encode64()
  end
end

Testing in IEx:

iex> AccountService.create_account(%{username: "alice_dev", email: "alice@example.com", password: "securepass123"})
{:ok,
 %{
   id: 47291,
   username: "alice_dev",
   email: "alice@example.com",
   password_hash: "...",
   created_at: ~U[2026-03-05 10:00:00.000000Z]
 }}

iex> AccountService.create_account(%{username: "admin", email: "admin@example.com", password: "securepass123"})
{:error, {:username_taken, "admin"}}

iex> AccountService.create_account(%{username: "ab", email: "short@example.com", password: "securepass123"})
{:error, {:username_too_short, [min: 3]}}

iex> AccountService.create_account(%{username: "valid_user", email: "valid@example.com", password: "short"})
{:error, {:password_too_short, [min: 8]}}

Collecting Multiple Errors

Sometimes you want to validate all fields and return all errors at once instead of stopping at the first failure:

defmodule FormValidator do
  def validate_registration_form(params) do
    errors =
      []
      |> validate_field(:name, params[:name], &UserValidator.validate_name/1)
      |> validate_field(:email, params[:email], &UserValidator.validate_email/1)
      |> validate_field(:age, params[:age], &UserValidator.validate_age/1)

    if Enum.empty?(errors) do
      {:ok, sanitize_params(params)}
    else
      {:error, {:validation_failed, errors}}
    end
  end

  defp validate_field(errors, field, value, validator) do
    case validator.(value) do
      {:ok, _valid_value} -> errors
      {:error, reason} -> [{field, reason} | errors]
    end
  end

  defp sanitize_params(params) do
    params
    |> Map.update(:name, nil, &String.trim/1)
    |> Map.update(:email, nil, &String.downcase/1)
  end
end

Testing in IEx:

iex> FormValidator.validate_registration_form(%{name: "Alice", email: "alice@example.com", age: 25})
{:ok, %{name: "Alice", email: "alice@example.com", age: 25}}

iex> FormValidator.validate_registration_form(%{name: "", email: "not-an-email", age: -5})
{:error,
 {:validation_failed,
  [
    age: {:age_out_of_range, -5},
    email: {:invalid_email, "not-an-email"},
    name: :name_must_be_string
  ]}}

Working with Lists of Results

defmodule BatchProcessor do
  def process_all(items) do
    results = Enum.map(items, &process_one/1)

    case Enum.split_with(results, fn
           {:ok, _} -> true
           {:error, _} -> false
           _other -> false
         end) do
      {successes, []} ->
        values = Enum.map(successes, fn {:ok, v} -> v end)
        {:ok, values}

      {successes, failures} ->
        errors =
          Enum.map(failures, fn
            {:error, reason} -> reason
            other -> {:unexpected_result, other}
          end)

        {:partial, Enum.map(successes, fn {:ok, v} -> v end), errors}
    end
  end

  # Fails fast: stops at the first error
  def process_all_strict(items) do
    Enum.reduce_while(items, {:ok, []}, fn item, {:ok, acc} ->
      case process_one(item) do
        {:ok, result} -> {:cont, {:ok, [result | acc]}}
        {:error, reason} -> {:halt, {:error, reason}}
      end
    end)
    |> case do
      {:ok, results} -> {:ok, Enum.reverse(results)}
      error -> error
    end
  end

  defp process_one(item) when is_integer(item) and item > 0 do
    {:ok, item * 2}
  end

  defp process_one(item) do
    {:error, {:invalid_item, item}}
  end
end

Testing in IEx:

iex> BatchProcessor.process_all([1, 2, 3, 4, 5])
{:ok, [2, 4, 6, 8, 10]}

iex> BatchProcessor.process_all([1, -2, 3, -4, 5])
{:partial, [2, 6, 10], [{:invalid_item, -2}, {:invalid_item, -4}]}

iex> BatchProcessor.process_all_strict([1, 2, 3, 4, 5])
{:ok, [2, 4, 6, 8, 10]}

iex> BatchProcessor.process_all_strict([1, -2, 3])
{:error, {:invalid_item, -2}}

Best Practices

I return tagged tuples from functions that can fail — this keeps success and failure visible in the return value instead of hidden behind nil or exceptions.

I try to make error reasons descriptive — specific, actionable reasons are easier to debug:

For example, I find {:error, {:missing_field, :email}} much easier to debug than {:error, :bad_input}.

I use with for sequential operations — it gives me a clean pipeline with a single error handling point.

I avoid silently discarding errors — if I assign _ = Repository.insert(user) and ignore the result, I hide failures from myself. I try to propagate or log them.

I try to stay consistent — tagged tuples as default keep code easier to reason about; mixing nil and {:error, _} can make behavior harder to predict.

Conclusion

The {:ok, value} and {:error, reason} pattern became one of the most useful conventions for me in Elixir. Writing and testing these examples made me more confident with failure paths.

Some things I learned:

Errors are values: I get better results when I treat {:error, reason} like any other return value
Descriptive reasons help a lot: Clear error reasons make debugging faster for me
with keeps pipelines readable: I can chain steps and handle failures in one place
Consistency pays off: Using one style across the codebase makes behavior easier to predict
Bang functions fit programming errors: I use ! variants when failure means my assumptions were wrong
I try not to discard errors: Propagating or logging failures saves debugging time later

Learning this pattern made my Elixir code easier to reason about, test, and maintain. I still keep refining it, but it already makes day-to-day coding much clearer.

Next Steps

After learning the {:ok, value} / {:error, reason} pattern, I felt ready to explore Try, Catch, and Rescue in Elixir. Tagged tuples handle expected failures, while exceptions help with unexpected situations.

In the next article, we'll explore:

When to use try/rescue vs tagged tuples
Defining and raising custom exceptions
Using catch for exits and throws
The after clause for cleanup and resource management
Practical guidelines for combining both error handling approaches

Understanding exceptions rounds out the error handling toolkit. It helped me separate expected validation errors from truly unexpected runtime failures.

Learning Elixir: Ranges

João Paulo Abreu — Sat, 01 Nov 2025 12:16:35 +0000

Ranges are like bookmarks that mark the start and end of a sequence without actually writing down every number in between. I like to think of a range as a smart recipe that knows how to generate numbers on demand - 1..100 doesn't store all 100 numbers in memory, it just remembers "start at 1, end at 100, count by 1s." This lazy approach makes ranges incredibly memory-efficient, whether you're working with small sequences like 1..5 or massive ones like 1..1_000_000. Unlike lists that explicitly store every element, ranges provide a lightweight way to represent sequences, enabling iteration patterns and enumeration operations that scale effortlessly. In this article, we'll explore how ranges work, their enumeration capabilities, and practical applications in Elixir development.

Note: The examples in this article use Elixir 1.19.0-rc.2. While most operations should work across different versions, some functionality might vary.

Introduction
Understanding How Ranges Work
Creating and Working with Range Syntax
Range Enumeration Patterns
Lazy Evaluation and Memory Efficiency
Using Ranges for Slicing and Pattern Matching
Performance Characteristics
Applications in Data Processing
Conclusion
Further Reading
Next Steps

Introduction

Ranges are one of Elixir's elegant solutions for representing sequences of numbers. They're particularly useful when you need to work with consecutive values without the memory overhead of storing each element.

Some characteristics I've noticed about ranges:

Memory efficient: Store only endpoints and step, not every value
Lazy by nature: Generate values only when needed
Always inclusive: Both endpoints are included in the range
Enumerable: Work seamlessly with Enum and Stream functions
Pattern matchable: Can be destructured to extract components
Directional: Support both ascending and descending sequences

Ranges are perfect for:

Iteration: for i <- 1..10, do: process(i)
Slicing: Enum.slice(list, 2..5)
Number generation: Enum.to_list(1..100)
Membership testing: x in 1..10

Here's a simple example that shows the power of ranges:

# Traditional approach with a list - stores all 1 million numbers
million_numbers = Enum.to_list(1..1_000_000)  # Uses significant memory

# Range approach - stores only start, end, step
million_range = 1..1_000_000  # Tiny memory footprint!

# Both can be enumerated the same way
Enum.take(million_range, 5)  # [1, 2, 3, 4, 5]

Let's dive into how ranges work!

Understanding How Ranges Work

The Internal Structure

Unlike lists that store every element, a range stores only three pieces of information:

# A range like 1..10 internally stores:
# - first: 1
# - last: 10
# - step: 1 (default)

# When you enumerate, Elixir generates values on demand:
# Start at 1, add step (1), get 2
# Start at 2, add step (1), get 3
# ... continue until reaching 10

This is why ranges are called "lazy" - they don't do work until you ask them to generate values.

Inclusivity

One thing I learned about ranges is that they're always inclusive in Elixir - both endpoints are included:

range = 1..5

# This includes both 1 and 5
Enum.to_list(range)  # [1, 2, 3, 4, 5]

# Not [1, 2, 3, 4] like in some other languages!

Testing in IEx:

iex> 1..5 |> Enum.to_list()
[1, 2, 3, 4, 5]

iex> first..last = 1..5
1..5

iex> {first, last}
{1, 5}

iex> 5 in 1..10
true

iex> 15 in 1..10
false

Empty Ranges

A range is empty when no values satisfy its conditions. This happens when the step direction doesn't match the endpoint direction:

# Empty ranges - step direction conflicts with endpoints
ascending_empty = 5..1//1    # Positive step, but first > last
descending_empty = 1..5//-1  # Negative step, but first < last

Enum.to_list(ascending_empty)    # []
Enum.to_list(descending_empty)   # []

The rules I've learned:

For ascending ranges (step > 0): needs first <= last
For descending ranges (step < 0): needs first >= last

Note: Writing 5..1 without explicit step generates a deprecation warning in current Elixir versions. The documentation recommends always using explicit step notation like 5..1//-1 for descending ranges.

Testing in IEx:

iex> Enum.to_list(5..1//1)
[]

iex> Enum.to_list(1..5//-1)
[]

iex> Enum.empty?(5..1//1)
true

iex> Enum.empty?(5..1//-1)
false

Creating and Working with Range Syntax

Basic Range Syntax

The most common way to create ranges uses the .. operator:

# Simple ascending range
basic = 1..10
Enum.to_list(basic)  # [1, 2, 3, 4, 5, 6, 7, 8, 9, 10]

# Single element range
single = 5..5
Enum.to_list(single)  # [5]

# Large range (still tiny in memory!)
huge = 1..1_000_000
Enum.take(huge, 3)  # [1, 2, 3]

Ranges with Steps

Use the // operator to specify a step value:

# Count by 2s
evens = 2..10//2
Enum.to_list(evens)  # [2, 4, 6, 8, 10]

# Count by 3s
threes = 0..15//3
Enum.to_list(threes)  # [0, 3, 6, 9, 12, 15]

# Descending ranges require explicit negative step
countdown = 10..1//-1
Enum.to_list(countdown)  # [10, 9, 8, 7, 6, 5, 4, 3, 2, 1]

# Descending by 2s
odd_countdown = 9..1//-2
Enum.to_list(odd_countdown)  # [9, 7, 5, 3, 1]

Important: Implicit decreasing ranges (like 10..1 without specifying step) are deprecated. Always use explicit step notation for descending ranges: 10..1//-1.

Testing in IEx:

iex> 2..10//2 |> Enum.to_list()
[2, 4, 6, 8, 10]

iex> 10..1//-1 |> Enum.to_list()
[10, 9, 8, 7, 6, 5, 4, 3, 2, 1]

iex> 0..20//5 |> Enum.to_list()
[0, 5, 10, 15, 20]

iex> 9..1//-2 |> Enum.to_list()
[9, 7, 5, 3, 1]

Using Range.new/2 and Range.new/3

You can also create ranges programmatically:

# Create range with function
range1 = Range.new(1, 10)
# Equivalent to 1..10

# Create range with step
range2 = Range.new(1, 10, 2)
# Equivalent to 1..10//2

# Dynamic range creation
defmodule RangeBuilder do
  def build_range(start, finish, step \\ 1) do
    Range.new(start, finish, step)
  end

  # Create range based on condition
  def conditional_range(ascending?) do
    if ascending? do
      Range.new(1, 100, 1)
    else
      Range.new(100, 1, -1)
    end
  end
end

Testing in IEx:

iex> Range.new(1, 10)
1..10

iex> Range.new(1, 10, 2)
1..10//2

iex> Range.new(5, 1, -1) |> Enum.to_list()
[5, 4, 3, 2, 1]

The Full-Slice Range

The special .. notation creates the range 0..-1//1, which has special meaning when used with slicing functions:

# Full-slice notation
full_slice = ..

# This range (0..-1//1) would normally be empty
# But Enum.slice/2 and String.slice/2 treat it specially
# to return the entire collection
list = [1, 2, 3, 4, 5]
Enum.slice(list, ..)  # [1, 2, 3, 4, 5] (all elements)

Testing in IEx:

iex> list = [1, 2, 3, 4, 5]
[1, 2, 3, 4, 5]

iex> Enum.slice(list, ..)
[1, 2, 3, 4, 5]

iex> Enum.slice(list, 1..3)
[2, 3, 4]

Range Enumeration Patterns

Working with Enum Functions

Ranges implement the Enumerable protocol, so they work with all Enum functions:

# Map over a range
squares = Enum.map(1..5, fn x -> x * x end)
# [1, 4, 9, 16, 25]

# Filter range values
evens = Enum.filter(1..10, fn x -> rem(x, 2) == 0 end)
# [2, 4, 6, 8, 10]

# Reduce a range
sum = Enum.reduce(1..100, 0, fn x, acc -> x + acc end)
# 5050

# Or use the simpler Enum.sum
sum_simple = Enum.sum(1..100)
# 5050

# Take first N elements
first_five = Enum.take(1..1_000_000, 5)
# [1, 2, 3, 4, 5]

Using Ranges in Comprehensions

Ranges work beautifully with list comprehensions:

# Generate squares
squares = for n <- 1..10, do: n * n
# [1, 4, 9, 16, 25, 36, 49, 64, 81, 100]

# Filter within comprehension
even_squares = for n <- 1..10, rem(n, 2) == 0, do: n * n
# [4, 16, 36, 64, 100]

# Multiple ranges (Cartesian product)
coordinates = for x <- 1..3, y <- 1..3, do: {x, y}
# [{1, 1}, {1, 2}, {1, 3}, {2, 1}, {2, 2}, {2, 3}, {3, 1}, {3, 2}, {3, 3}]

# With pattern matching
results = for x <- 1..5, rem(x, 2) == 1, do: {:odd, x}
# [{:odd, 1}, {:odd, 3}, {:odd, 5}]

Testing in IEx:

iex> for n <- 1..5, do: n * n
[1, 4, 9, 16, 25]

iex> for x <- 1..3, y <- 1..2, do: {x, y}
[{1, 1}, {1, 2}, {2, 1}, {2, 2}, {3, 1}, {3, 2}]

iex> for n <- 1..10, rem(n, 3) == 0, do: n
[3, 6, 9]

iex> Enum.sum(1..100)
5050

Streaming with Ranges

For even more efficiency, combine ranges with Stream:

# Stream allows composing operations without intermediate lists
result = 1..1_000_000
         |> Stream.map(&(&1 * 2))
         |> Stream.filter(&(rem(&1, 3) == 0))
         |> Enum.take(10)
# [6, 12, 18, 24, 30, 36, 42, 48, 54, 60]

# Only computes the first 10 matching values!
# Doesn't process all 1 million numbers

Testing in IEx:

iex> 1..100 |> Stream.map(&(&1 * 2)) |> Stream.filter(&(rem(&1, 5) == 0)) |> Enum.take(5)
[10, 20, 30, 40, 50]

iex> 1..1_000_000 |> Stream.take(3) |> Enum.to_list()
[1, 2, 3]

Lazy Evaluation and Memory Efficiency

Understanding Lazy Evaluation

One of the most powerful features of ranges is their lazy evaluation. This means values are generated only when needed:

# Creating a range doesn't generate any values
big_range = 1..10_000_000  # Instant! No memory used for values

# Values are generated on demand during enumeration
first_ten = Enum.take(big_range, 10)
# Only generates [1, 2, 3, 4, 5, 6, 7, 8, 9, 10]

Memory Comparison

The key difference between ranges and lists in memory:

# Range: stores only 3 values (first, last, step)
range = 1..1_000_000  # Lightweight!

# List: stores every single element
list = Enum.to_list(1..1_000_000)  # Much larger in memory

# Both can be enumerated the same way
Enum.sum(range)  # Works with the range directly
Enum.sum(list)   # Works with the list

This is why ranges are perfect for representing large sequences - they don't need to store every value.

Practical Lazy Evaluation Examples

Lazy evaluation means the range only generates values as needed:

# Take first 5 from a million - only generates 5 values
result = 1..1_000_000 |> Enum.take(5)

# Find first match - stops as soon as found
first_match = 1..100 |> Enum.find(fn x -> rem(x, 13) == 0 end)

# Filter then take - only processes until it has 3 results
filtered = 1..50 |> Enum.filter(&(rem(&1, 7) == 0)) |> Enum.take(3)

Testing in IEx:

iex> 1..1_000_000 |> Enum.take(5)
[1, 2, 3, 4, 5]

iex> 1..100 |> Enum.find(fn x -> rem(x, 13) == 0 end)
13

iex> 1..50 |> Enum.filter(&(rem(&1, 7) == 0)) |> Enum.take(3)
[7, 14, 21]

Using Ranges for Slicing and Pattern Matching

Slicing Collections with Ranges

Ranges provide an elegant syntax for extracting portions of collections:

list = [100, 200, 300, 400, 500, 600, 700, 800, 900, 1000]

# Get elements 2-5 (indices 1-4, remember 0-indexed)
Enum.slice(list, 1..4)
# [200, 300, 400, 500]

# Get last 3 elements using negative indices
Enum.slice(list, -3..-1//1)
# [800, 900, 1000]

# Skip first 2, take next 4
Enum.slice(list, 2..5)
# [300, 400, 500, 600]

# Every other element in a slice
Enum.slice(list, 0..9//2)
# [100, 300, 500, 700, 900]

String Slicing

Ranges work with binary slicing too:

text = "Hello, World!"

# Get characters 0-4
String.slice(text, 0..4)
# "Hello"

# Get last 6 characters
String.slice(text, -6..-1//1)
# "World!"

# Get every 2nd character
String.codepoints(text)
|> Enum.slice(0..12//2)
|> Enum.join()
# "Hlo ol!"

Testing in IEx:

iex> list = [100, 200, 300, 400, 500, 600, 700, 800, 900, 1000]
[100, 200, 300, 400, 500, 600, 700, 800, 900, 1000]

iex> Enum.slice(list, 1..4)
[200, 300, 400, 500]

iex> Enum.slice(list, -3..-1//1)
[800, 900, 1000]

iex> String.slice("Hello, World!", 0..4)
"Hello"

iex> String.slice("Hello, World!", -6..-1//1)
"World!"

Pattern Matching with Ranges

Ranges can be destructured to extract their components:

# Extract range components
first..last//step = 1..10//2
# first = 1, last = 10, step = 2

# Extract without step (default step is 1)
start..finish = 5..15
# start = 5, finish = 15

defmodule RangeAnalyzer do
  # Analyze range properties
  def analyze(range) do
    first..last//step = range

    %{
      start: first,
      end: last,
      step: step,
      size: Enum.count(range),
      direction: if(step > 0, do: :ascending, else: :descending)
    }
  end

  # Check if ranges overlap
  def overlaps?(r1, r2) do
    f1..l1 = r1
    f2..l2 = r2

    # Check if ranges have any common elements
    max(f1, f2) <= min(l1, l2)
  end

  # Merge consecutive ranges
  def merge_consecutive?(r1, r2) do
    _f1..l1//s1 = r1
    f2.._l2//s2 = r2

    # Check if r2 starts right after r1 with same step
    s1 == s2 && l1 + s1 == f2
  end
end

Testing in IEx:

iex> first..last//step = 1..10//2
1..10//2

iex> {first, last, step}
{1, 10, 2}

iex> start..finish = 5..15
5..15

iex> {start, finish}
{5, 15}

iex> RangeAnalyzer.analyze(1..10//2)
%{start: 1, end: 10, step: 2, size: 5, direction: :ascending}

iex> RangeAnalyzer.overlaps?(1..5, 3..7)
true

iex> RangeAnalyzer.overlaps?(1..5, 6..10)
false

Using Ranges in Function Guards

defmodule RangeGuards do
  # Accept values in range
  def categorize_age(age) when age in 0..12, do: :child
  def categorize_age(age) when age in 13..19, do: :teenager
  def categorize_age(age) when age in 20..64, do: :adult
  def categorize_age(age) when age >= 65, do: :senior

  # Validate score range
  def valid_score?(score) when score in 0..100, do: true
  def valid_score?(_), do: false

  # Process based on range membership
  def process_value(x) when x in 1..10, do: {:small, x}
  def process_value(x) when x in 11..100, do: {:medium, x}
  def process_value(x) when x in 101..1000, do: {:large, x}
  def process_value(x), do: {:out_of_range, x}
end

Testing in IEx:

iex> RangeGuards.categorize_age(8)
:child

iex> RangeGuards.categorize_age(17)
:teenager

iex> RangeGuards.valid_score?(85)
true

iex> RangeGuards.valid_score?(150)
false

iex> RangeGuards.process_value(5)
{:small, 5}

iex> RangeGuards.process_value(50)
{:medium, 50}

Performance Characteristics

Understanding Range Efficiency

Ranges are memory-efficient because they store only three values (first, last, step) regardless of the range size:

range = 1..1_000_000

# Creating ranges is fast - only stores endpoints and step
Range.new(1, 1000)
first..last//step = range

# Operations that generate values must enumerate
Enum.to_list(range)          # Generates all 1 million values
Enum.sum(range)              # Enumerates to sum

# Bounded operations only work with needed values
Enum.take(range, 10)         # Only generates first 10 values
Enum.random(range)           # Documented as constant time for ranges

Working Efficiently with Ranges

defmodule RangeExamples do
  # Check if value is in range
  def in_range?(value, range) do
    value in range
  end

  # Use Stream for lazy evaluation
  def first_n_multiples(n, count) do
    Stream.iterate(n, &(&1 + n))
    |> Enum.take(count)
  end

  # Avoid unnecessary conversions
  def sum_direct(range) do
    Enum.sum(range)  # Works directly on range
  end

  # Mathematical formula alternative (for simple ranges)
  def sum_range_formula(first..last) when first <= last do
    n = last - first + 1
    div(n * (first + last), 2)
  end
end

Testing in IEx:

iex> 50 in 1..100
true

iex> RangeExamples.sum_direct(1..100)
5050

iex> RangeExamples.sum_range_formula(1..100)
5050

Memory Considerations

defmodule MemoryExamples do
  # Works with range directly - no intermediate list
  def count_evens_direct(max) do
    1..max |> Enum.count(&(rem(&1, 2) == 0))
  end

  # Creates intermediate list (uses more memory)
  def count_evens_with_list(max) do
    1..max
    |> Enum.to_list()
    |> Enum.filter(&(rem(&1, 2) == 0))
    |> length()
  end

  # Mathematical formula (no enumeration needed)
  def count_evens_formula(max), do: div(max, 2)

  # Lazy streaming for complex operations
  def process_large_range(range) do
    range
    |> Stream.filter(&(rem(&1, 3) == 0))
    |> Stream.map(&(&1 * &1))
    |> Enum.take(100)
  end
end

Testing in IEx:

iex> MemoryExamples.count_evens_direct(100)
50

iex> MemoryExamples.count_evens_formula(100)
50

iex> MemoryExamples.process_large_range(1..10_000) |> length()
100

Applications in Data Processing

Iteration Patterns

Ranges make common iteration patterns simple:

# Generate numbered items
items = for i <- 1..5, do: "Item #{i}"

# Countdown
countdown = for i <- 5..1//-1, do: "T-minus #{i}"

# Simple pagination calculation
page_size = 10
total_items = 45
total_pages = div(total_items + page_size - 1, page_size)
pages = for page <- 1..total_pages, do: page

Testing in IEx:

iex> for i <- 1..5, do: "Item #{i}"
["Item 1", "Item 2", "Item 3", "Item 4", "Item 5"]

iex> for i <- 5..1//-1, do: "T-minus #{i}"
["T-minus 5", "T-minus 4", "T-minus 3", "T-minus 2", "T-minus 1"]

iex> total_pages = div(45 + 10 - 1, 10)
5

iex> for page <- 1..total_pages, do: page
[1, 2, 3, 4, 5]

Common Algorithms

Ranges work well for implementing common algorithms:

# FizzBuzz
fizzbuzz = for i <- 1..15 do
  cond do
    rem(i, 15) == 0 -> "FizzBuzz"
    rem(i, 3) == 0 -> "Fizz"
    rem(i, 5) == 0 -> "Buzz"
    true -> to_string(i)
  end
end

# Multiplication table
table = for i <- 1..3, j <- 1..3, do: {i, j, i * j}

# Sum of squares
sum_of_squares = 1..10 |> Enum.map(&(&1 * &1)) |> Enum.sum()

Testing in IEx:

iex> for i <- 1..15, rem(i, 15) == 0 or rem(i, 3) == 0 or rem(i, 5) == 0, do: i
[3, 5, 6, 9, 10, 12, 15]

iex> for i <- 1..3, j <- 1..3, do: {i, j, i * j}
[{1, 1, 1}, {1, 2, 2}, {1, 3, 3}, {2, 1, 2}, {2, 2, 4}, {2, 3, 6}, {3, 1, 3}, {3, 2, 6}, {3, 3, 9}]

iex> 1..10 |> Enum.map(&(&1 * &1)) |> Enum.sum()
385

Data Generation

Ranges simplify generating test data:

# Generate user IDs
user_ids = 1..5 |> Enum.to_list()

# Generate sequential dates
dates = for day <- 0..4, do: Date.add(~D[2024-01-01], day)

# Sample points at intervals
samples = for x <- 0..100//25, do: {x, x * 2}

Testing in IEx:

iex> 1..5 |> Enum.to_list()
[1, 2, 3, 4, 5]

iex> for day <- 0..4, do: Date.add(~D[2024-01-01], day)
[~D[2024-01-01], ~D[2024-01-02], ~D[2024-01-03], ~D[2024-01-04], ~D[2024-01-05]]

iex> for x <- 0..100//25, do: {x, x * 2}
[{0, 0}, {25, 50}, {50, 100}, {75, 150}, {100, 200}]

Conclusion

Ranges are a fundamental feature of Elixir that I've found incredibly useful for working with sequences. In this article, I explored:

How ranges work internally with their lightweight structure
Creating ranges with various syntax options and step values
Enumeration patterns and how ranges integrate with Enum and Stream
The power of lazy evaluation for memory efficiency
Using ranges for slicing collections and pattern matching
Performance characteristics and when ranges excel
Practical applications in data processing and algorithms

Some things I learned:

Memory efficiency: Ranges store only endpoints and step, making them perfect for large sequences
Lazy by design: Values are generated on demand, not stored in memory
Always inclusive: Both endpoints are included, unlike some other languages
Deprecation note: Implicit decreasing ranges are deprecated; always use explicit steps like 10..1//-1
Enumerable power: Ranges work seamlessly with all Enum and Stream functions
Pattern matching: Ranges can be destructured to extract their components

Ranges complement Elixir's other data structures by providing a memory-efficient way to represent sequences. They work well when combined with lazy evaluation through Stream, allowing you to work with large ranges without storing all values in memory.

Understanding ranges has helped me write cleaner Elixir code. Whether it's simple iteration, batch processing, or algorithms, ranges provide an elegant solution for working with sequences.

Next Steps

With a solid understanding of ranges, the next step is exploring Error Handling in Elixir. Error handling is crucial for building robust applications, and Elixir provides elegant patterns for dealing with failures.

In the next article, we'll explore:

Understanding {:ok, value} and {:error, reason} patterns
The with construct for chaining operations that might fail
Using case and pattern matching for error handling
Best practices for propagating and handling errors
Building resilient functions with proper error handling

Error handling is essential for writing production-ready Elixir code. Let's dive into how Elixir makes error handling both explicit and elegant!

Learning Elixir: Binaries and Bitstrings

João Paulo Abreu — Sun, 28 Sep 2025 12:32:51 +0000

Binaries and bitstrings can be thought of as digital building blocks where each block can hold exactly the amount of information you specify, down to the individual bit. I like to think of a bitstring as a precise digital ruler where you can measure and cut data to exact specifications - <<3::4>> allocates exactly 4 bits for the number 3, while <<42>> uses the standard 8-bit byte. Unlike higher-level data structures that abstract away the underlying representation, binaries give you direct control over how data is stored and manipulated at the byte level, making them useful for file formats and data processing. While this low-level control requires more precision and understanding, it also provides capabilities for data processing and pattern matching on binary streams. In this article, we'll explore how binaries and bitstrings work, their pattern matching capabilities, and techniques that are valuable in Elixir development.

Note: The examples in this article use Elixir 1.18.4. While most operations should work across different versions, some functionality might vary.

Introduction
Understanding Binaries and Bitstrings
Binary Construction and Syntax
Pattern Matching with Binaries
String Operations and UTF8 Handling
Bitwise Operations and Manipulation
Binary Comprehensions and Generators
Conclusion
Further Reading
Next Steps

Introduction

Binaries and bitstrings are Elixir's way of working with raw data at the bit and byte level. They're useful for string processing, file manipulation, and situations where you need precise control over data representation.

Some characteristics I've noticed about binaries and bitstrings:

Precise control: Specify exact bit sizes for optimal memory usage
Pattern matching power: Extract and validate data with elegant syntax
UTF-8 native: Excellent support for international text processing
Memory aware: Good memory representation and operations
Format friendly: Suitable for working with binary formats
Flexible: From single bits to data structures

Binaries and bitstrings are useful for data precision in cases like:

Network packets: <<version::4, type::4, length::16, data::binary>>
File headers: <<magic_number::32, version::8, flags::8>>
Image pixels: <<red::8, green::8, blue::8>>

Binaries are helpful when you need to:

Process binary data with specific byte layouts
Parse binary file formats
Handle international text with proper UTF-8 support
Create domain-specific binary formats
Transform and manipulate data at the byte level

Let's explore how they work!

Understanding Binaries and Bitstrings

Fundamental Concepts

The relationship between bitstrings and binaries can be understood this way:

# A bitstring is a contiguous sequence of bits in memory
bitstring_4_bits = <<3::4>>    # Exactly 4 bits
bitstring_12_bits = <<3::4, 7::8>>  # 12 bits total (4 + 8)

# A binary is a bitstring where the number of bits is divisible by 8
binary_8_bits = <<42>>         # 8 bits (1 byte)
binary_16_bits = <<42, 24>>    # 16 bits (2 bytes)

# Every binary is a bitstring, but not every bitstring is a binary
is_bitstring(<<3::4>>)         # true
is_binary(<<3::4>>)           # false - not divisible by 8

is_bitstring(<<42>>)          # true  
is_binary(<<42>>)             # true - 8 bits, divisible by 8

Understanding Bitstring Syntax

Learning to "read" bitstring syntax helps understand how data is stored and manipulated at the bit level.

Basic Syntax Patterns

# The pattern: <<value::size>>
# "Store [value] using exactly [size] bits"

<<3::4>>        # "Store 3 using 4 bits"
<<42::8>>       # "Store 42 using 8 bits" (default, same as <<42>>)
<<1000::16>>    # "Store 1000 using 16 bits"
<<7::size(12)>> # "Store 7 using 12 bits" (variable size)

Bit Patterns and Storage

# 3::4 means "store the number 3 using exactly 4 bits"
# 3 in binary: 0011 (4 bits)
<<3::4>>  # Stores: 0011

# 7::8 means "store the number 7 using exactly 8 bits"
# 7 in binary: 00000111 (8 bits)
<<7::8>>  # Stores: 00000111

# 15::4 means "store 15 using 4 bits"
# 15 in binary: 1111 (4 bits) - fits perfectly
<<15::4>>  # Stores: 1111

# Visualizing the actual bit patterns (for complete bytes)
<<byte>> = <<15>>
Integer.to_string(byte, 2) |> String.pad_leading(8, "0")
# Result: "00001111" - shows the actual bit representation

Handling Overflow and Truncation

# What happens when a value doesn't fit?
# 16::4 means "store 16 using 4 bits"
# 16 in binary: 10000 (5 bits), but we only have 4 bits!
# Gets truncated to: 0000 (keeps only the lowest 4 bits)
<<16::4>>  # Stores: 0000 (truncation occurs)

# This truncation behavior is predictable and follows bitwise AND with max value:
# 17::4 -> 0001 (17 & 15 = 1, where 15 is max 4-bit value)
# 18::4 -> 0010 (18 & 15 = 2)

Complex Concatenations

# Creating a complex bitstring by concatenating different sized parts
complex_bits = <<3::4, 7::8>>  # 4 bits + 8 bits = 12 bits total

# Understanding what happens step by step:
# 3 in 4 bits:  0011
# 7 in 8 bits:  00000111
# Concatenated: 0011 00000111 (12 bits total)

# Since 12 bits isn't divisible by 8, Elixir groups them:
# First 8 bits:  00110000 → decimal 48
# Last 4 bits:   0111 → decimal 7 (partial byte)
# Result: <<48, 7::size(4)>>

bit_size(complex_bits)   # 12 bits total
byte_size(complex_bits)  # 2 bytes (rounded up)

# Verify the individual components:
part1 = Integer.to_string(3, 2) |> String.pad_leading(4, "0")    # "0011"
part2 = Integer.to_string(7, 2) |> String.pad_leading(8, "0")    # "00000111"

# The concatenation "001100000111" gets split as:
# "00110000" (8 bits) = 48 decimal
# "0111" (4 bits) = 7 decimal
# Hence: <<48, 7::size(4)>>

Reading IEx Output

IEx bitstring results follow predictable patterns:

<<42>>            # Simple binary: all bits divisible by 8
<<3::size(4)>>    # Bitstring: 4 bits, not divisible by 8
<<48, 7::size(4)>> # Mixed: full byte + partial bits

# The pattern: <<full_bytes..., partial_value::size(remaining_bits)>>

This bit-level precision makes bitstrings useful for precise data control.

Key insight: When bits don't align to byte boundaries (8-bit multiples), Elixir shows the result as complete bytes plus remaining bits. So <<3::4, 7::8>> creates 12 bits total, displayed as one complete byte (48) plus 4 remaining bits (7).

Testing in IEx:

iex> bitstring_4_bits = <<3::4>>
<<3::size(4)>>

iex> bitstring_12_bits = <<3::4, 7::8>>  # 4 + 8 = 12 bits total
<<48, 7::size(4)>>

iex> binary_8_bits = <<42>>
"*"

iex> binary_16_bits = <<42, 24>>
<<42, 24>>

iex> is_bitstring(<<3::4>>)
true

iex> is_binary(<<3::4>>)
false

iex> is_bitstring(<<42>>)
true

iex> is_binary(<<42>>)
true

iex> <<byte>> = <<15>>
<<15>>

iex> Integer.to_string(byte, 2) |> String.pad_leading(8, "0")
"00001111"

iex> complex_bits = <<3::4, 7::8>>
<<48, 7::size(4)>>

iex> bit_size(complex_bits)
12

iex> byte_size(complex_bits)
2

iex> part1 = Integer.to_string(3, 2) |> String.pad_leading(4, "0")
"0011"

iex> part2 = Integer.to_string(7, 2) |> String.pad_leading(8, "0")
"00000111"

iex> <<42::16>>
<<0, 42>>

iex> is_binary(<<42::16>>)
true

Size Functions and Inspection

data = <<1, 2, 3, 255>>

# Get size information
bit_size(data)         # 32 (4 bytes × 8 bits/byte)
byte_size(data)        # 4 bytes

# For non-byte-aligned bitstrings
partial = <<1::3, 0::2, 1::3>>  # 8 bits total but constructed from parts
bit_size(partial)      # 8
byte_size(partial)     # 1 (rounds up to nearest byte)

# Size functions work in guards
defmodule BinaryValidator do
  def small_binary?(data) when byte_size(data) <= 10, do: true
  def small_binary?(_), do: false

  def exact_size?(data) when bit_size(data) == 64, do: true
  def exact_size?(_), do: false
end

Testing in IEx:

iex> data = <<1, 2, 3, 255>>
<<1, 2, 3, 255>>

iex> bit_size(data)
32

iex> byte_size(data)
4

iex> partial = <<1::3, 0::2, 1::3>>
"!"

iex> bit_size(partial)
8

iex> byte_size(partial)
1

Memory Representation and Efficiency

# Binaries are stored in memory
large_binary = :crypto.strong_rand_bytes(1024)  # 1KB of random data
byte_size(large_binary)  # 1024

# Binary concatenation creates a new binary
combined = <<1, 2>> <> <<3, 4>>  # <<1, 2, 3, 4>>

# Pattern matching can be used to avoid copying
<<prefix::binary-size(2), suffix::binary>> = large_binary
byte_size(prefix)   # 2
byte_size(suffix)   # 1022 (shares memory with original)

# Check if data is a proper binary vs bitstring
defmodule TypeChecker do
  def analyze(data) do
    %{
      is_bitstring: is_bitstring(data),
      is_binary: is_binary(data),
      bit_size: bit_size(data),
      byte_size: byte_size(data),
      is_proper_binary: is_binary(data)
    }
  end
end

Testing in IEx:

iex> combined = <<1, 2>> <> <<3, 4>>
<<1, 2, 3, 4>>

iex> <<prefix::binary-size(2), suffix::binary>> = <<1, 2, 3, 4, 5>>
<<1, 2, 3, 4, 5>>

iex> prefix
<<1, 2>>

iex> suffix
<<3, 4, 5>>

Binary Construction and Syntax

Basic Construction Patterns

# Default 8-bit integers
basic = <<1, 2, 3>>           # Three bytes
explicit = <<1::8, 2::8, 3::8>>  # Equivalent explicit form

# Different bit sizes
small = <<15::4>>             # 4 bits (fits perfectly)
large = <<1000::16>>          # 16 bits (2 bytes)

# Mixed sizes in one binary
mixed = <<1::4, 2::8, 3::4>>  # 16 bits total = 2 bytes

# Verify equivalence
basic == explicit             # true
bit_size(mixed)              # 16
byte_size(mixed)             # 2

Testing in IEx:

iex> <<1, 2, 3>>
<<1, 2, 3>>

iex> <<1::8, 2::8, 3::8>>
<<1, 2, 3>>

iex> <<15::4>>
<<15::size(4)>>

iex> <<1000::16>>
<<3, 232>>

iex> mixed = <<1::4, 2::8, 3::4>>
<<16, 35>>

iex> bit_size(mixed)
16

Advanced Size Specifications

# Variable sizes using variables
size = 12
variable_size = <<42::size(size)>>   # 12-bit value

# Size expressions (evaluated at compile time when possible)
header_size = 8
data_size = 24
packet = <<1::size(header_size), 12345::size(data_size)>>

# Working with different data types
float_data = <<3.14159::32-float>>   # 32-bit float
double_data = <<3.14159::64-float>>  # 64-bit float

# Signedness specifications (affects how negative numbers are stored)
signed_positive = <<100::8-signed>>    # Positive: stored as 100 (shows as "d")
signed_negative = <<-50::8-signed>>    # Negative: stored as 206 (two's complement of -50)
unsigned_value = <<206::8>>            # Unsigned: stored as 206 (same bytes, different meaning)

# Endianness control
big_endian = <<0x1234::16-big>>       # <<18, 52>>
little_endian = <<0x1234::16-little>> # <<52, 18>>

Testing in IEx:

iex> size = 12
12

iex> <<42::size(size)>>
<<2, 10::size(4)>>

iex> <<3.14159::32-float>>
<<64, 73, 15, 208>>

iex> <<100::8-signed>>
"d"

iex> <<-50::8-signed>>
<<206>>

iex> <<206::8>>
<<206>>

iex> <<0x1234::16-big>>
<<18, 52>>

iex> <<0x1234::16-little>>
<<52, 18>>

Understanding Signed vs Unsigned: IEx displays <<100::8-signed>> as "d" because byte 100 corresponds to the ASCII character 'd'. The signedness modifier affects how negative numbers are encoded (using two's complement) but doesn't change positive number storage. Both <<100::8-signed>> and <<100::8>> store identical byte values for positive numbers.

String and Character Handling

# Strings are UTF-8 encoded binaries
string = "Hello, 世界!"
is_binary(string)      # true
byte_size(string)      # 14 bytes (not 10 characters!)

# Manual UTF-8 construction
utf8_manual = <<72, 101, 108, 108, 111>>  # "Hello" in UTF-8
utf8_manual == "Hello"  # true

# Unicode code points
unicode_point = <<0x4E16::utf8, 0x754C::utf8>>  # 世界
unicode_point == "世界"  # true

# Null-terminated strings (C-style)
c_string = <<"Hello", 0>>    # Hello with null terminator
printable_part = binary_part(c_string, 0, byte_size(c_string) - 1)

Testing in IEx:

iex> string = "Hello, 世界!"
"Hello, 世界!"

iex> byte_size(string)
14

iex> <<72, 101, 108, 108, 111>>
"Hello"

iex> <<0x4E16::utf8, 0x754C::utf8>>
"世界"

iex> c_string = <<"Hello", 0>>
<<72, 101, 108, 108, 111, 0>>

iex> binary_part(c_string, 0, byte_size(c_string) - 1)
"Hello"

Building Complex Structures

defmodule DataBuilder do
  # Binary structure with header and payload
  def build_data(type, payload) when is_binary(payload) do
    version = 1
    length = byte_size(payload)
    checksum = calculate_checksum(payload)

    <<version::4, type::4, length::16, checksum::32, payload::binary>>
  end

  # Message encoding
  def encode_message(id, data) when is_list(data) do
    encoded_data = Enum.map(data, &encode_field/1)
    data_size = Enum.sum_by(encoded_data, &byte_size/1)

    [<<id::16, data_size::32>> | encoded_data]
    |> IO.iodata_to_binary()
  end

  # Binary tree node representation
  def encode_tree_node(value, left_present?, right_present?) do
    flags = 
      case {left_present?, right_present?} do
        {true, true} -> 3    # 11 in binary
        {true, false} -> 2   # 10 in binary  
        {false, true} -> 1   # 01 in binary
        {false, false} -> 0  # 00 in binary
      end

    <<flags::2, 0::6, value::32>>  # Flags + padding + value
  end

  defp calculate_checksum(data) do
    # Simple XOR checksum
    import Bitwise
    data
    |> :binary.bin_to_list()
    |> Enum.reduce(0, fn byte, acc -> bxor(byte, acc) end)
  end

  defp encode_field({:string, str}) do
    size = byte_size(str)
    <<1, size::16, str::binary>>
  end

  defp encode_field({:integer, int}) do
    <<2, int::32>>
  end

  defp encode_field({:float, f}) do
    <<3, f::32-float>>
  end
end

Testing in IEx:

iex> data = DataBuilder.build_data(5, "Hello")
<<21, 0, 5, 0, 0, 0, 66, 72, 101, 108, 108, 111>>

iex> message = DataBuilder.encode_message(100, [{:string, "test"}, {:integer, 42}])
<<0, 100, 0, 0, 0, 11, 1, 0, 4, 116, 101, 115, 116, 2, 0, 0, 0, 42>>

iex> node = DataBuilder.encode_tree_node(1000, true, false)
<<128, 0, 0, 3, 232>>

Pattern Matching with Binaries

Basic Pattern Matching

# Fixed-size pattern matching
<<a, b, c>> = <<1, 2, 3>>   # a=1, b=2, c=3

# Mixed with rest
<<first, rest::binary>> = <<1, 2, 3, 4>>
# first = 1, rest = <<2, 3, 4>>

# Specific sizes
<<header::binary-size(2), payload::binary>> = <<0xFF, 0xFE, 1, 2, 3>>
# header = <<255, 254>>, payload = <<1, 2, 3>>

# Multiple extractions
<<version::4, type::4, length::16, data::binary>> = <<0x12, 0x00, 0x05, 1, 2, 3, 4, 5>>
# version = 1, type = 2, length = 5, data = <<1, 2, 3, 4, 5>>

Common Patterns

defmodule BinaryPatterns do
  # Variable-length data with prefixed size
  def parse_sized_string(<<size::16, string::binary-size(size), rest::binary>>) do
    {:ok, string, rest}
  end

  # Pattern matching with guards
  def validate_packet(<<version, type, _rest::binary>>)
      when version in 1..3 and type in 1..10 do
    {:ok, :valid_packet}
  end

  # Size-based validation
  def process_message(data) when byte_size(data) <= 64 do
    {:ok, "Processing small message"}
  end

  def process_message(_data) do
    {:error, "Message too large"}
  end
end

Testing in IEx:

iex> <<a, b, c>> = <<1, 2, 3>>
<<1, 2, 3>>

iex> {a, b, c}
{1, 2, 3}

iex> <<header::binary-size(2), payload::binary>> = <<255, 254, 1, 2, 3>>
<<255, 254, 1, 2, 3>>

iex> {header, payload}
{<<255, 254>>, <<1, 2, 3>>}

iex> sized_data = <<5::16, "hello", "rest">>
<<0, 5, 104, 101, 108, 108, 111, 114, 101, 115, 116>>

iex> BinaryPatterns.parse_sized_string(sized_data)
{:ok, "hello", "rest"}

iex> packet = <<2, 5, "more data">>
<<2, 5, 109, 111, 114, 101, 32, 100, 97, 116, 97>>

iex> BinaryPatterns.validate_packet(packet)
{:ok, :valid_packet}

iex> BinaryPatterns.process_message("small")
{:ok, "Processing small message"}

String Operations and UTF8 Handling

UTF-8 Pattern Matching

Working with international text requires special consideration for multi-byte characters:

# Incorrect way - treats bytes, not characters
<<first, rest::binary>> = "über"
first == ?ü  # false! (first is 195, first byte of ü in UTF-8)

# Correct way - use utf8 modifier
<<first::utf8, rest::binary>> = "über"
first == ?ü  # true! (first is the Unicode code point)

defmodule UTF8Handler do
  # Extract first character safely
  def first_char(<<char::utf8, _rest::binary>>), do: {:ok, char}
  def first_char(""), do: {:error, :empty_string}
  def first_char(_), do: {:error, :invalid_utf8}

  # Extract last character (more complex due to variable length)
  def last_char(string) when is_binary(string) do
    case String.reverse(string) do
      <<char::utf8, _rest::binary>> -> {:ok, char}
      "" -> {:error, :empty_string}
      _ -> {:error, :invalid_utf8}
    end
  end

  # Count actual characters vs bytes
  def analyze_string(string) do
    %{
      byte_size: byte_size(string),
      char_count: String.length(string),
      first_char: first_char(string),
      is_ascii: is_ascii?(string)
    }
  end

  # Check if string contains only ASCII characters
  defp is_ascii?(string) do
    string
    |> String.to_charlist()
    |> Enum.all?(fn char -> char >= 0 and char <= 127 end)
  end

  # Safe character iteration
  def extract_chars(binary, acc \\ [])

  def extract_chars(<<char::utf8, rest::binary>>, acc) do
    extract_chars(rest, [char | acc])
  end

  def extract_chars("", acc) do
    {:ok, Enum.reverse(acc)}
  end

  def extract_chars(_invalid, _acc) do
    {:error, :invalid_utf8}
  end
end

Testing in IEx:

iex> <<first::utf8, rest::binary>> = "über"
"über"

iex> first == ?ü
true

iex> rest
"ber"

iex> UTF8Handler.analyze_string("Hello")
%{byte_size: 5, char_count: 5, first_char: {:ok, 72}, is_ascii: true}

iex> UTF8Handler.analyze_string("世界")
%{byte_size: 6, char_count: 2, first_char: {:ok, 19990}, is_ascii: false}

iex> UTF8Handler.extract_chars("Héllo")
{:ok, [72, 233, 108, 108, 111]}

String Construction and Manipulation

defmodule StringBuilder do
  # Build strings from Unicode code points
  def from_codepoints(codepoints) when is_list(codepoints) do
    try do
      binary = for cp <- codepoints, into: <<>>, do: <<cp::utf8>>
      {:ok, binary}
    rescue
      _ -> {:error, :invalid_codepoint}
    end
  end

  # Remove specific characters using binary patterns
  def remove_char(string, char_to_remove) do
    for <<char::utf8 <- string>>, char != char_to_remove, into: "", do: <<char::utf8>>
  end

  # Convert binary to hexadecimal representation
  def to_hex_string(binary) do
    for <<byte <- binary>>, into: "" do
      byte |> Integer.to_string(16) |> String.downcase() |> String.pad_leading(2, "0")
    end
  end
end

Testing in IEx:

iex> StringBuilder.from_codepoints([72, 101, 108, 108, 111])
{:ok, "Hello"}

iex> StringBuilder.remove_char("Hello World", ?l)
"Heo Word"

iex> StringBuilder.to_hex_string(<<255, 0, 128>>)
"ff0080"

Bitwise Operations and Manipulation

Basic Bitwise Operations

import Bitwise

# Basic operations
a = 0b1010  # 10 in decimal
b = 0b1100  # 12 in decimal

# Demonstrating bitwise operations
and_result = a &&& b        # 0b1000 = 8
or_result = a ||| b         # 0b1110 = 14
xor_result = bxor(a, b)     # 0b0110 = 6
not_result = bnot(a) &&& 0xFF # Limit to 8 bits = 245
left_shift = a <<< 2        # 0b101000 = 40
right_shift = a >>> 1       # 0b101 = 5

Binary Data Operations

defmodule BitwiseOps do
  import Bitwise

  # Essential bit manipulation functions
  def set_bit(value, position), do: value ||| (1 <<< position)
  def clear_bit(value, position), do: value &&& bnot(1 <<< position)
  def bit_set?(value, position), do: (value &&& (1 <<< position)) != 0

  # XOR two binaries
  def xor_binaries(<<>>, <<>>), do: <<>>
  def xor_binaries(<<a, rest_a::binary>>, <<b, rest_b::binary>>) do
    <<bxor(a, b), xor_binaries(rest_a, rest_b)::binary>>
  end

  # Simple checksum
  def calculate_checksum(data) do
    for <<byte <- data>>, reduce: 0 do
      acc -> (acc + byte) &&& 0xFFFF
    end
  end
end

Testing in IEx:

iex> import Bitwise
Bitwise

iex> a = 0b1010
10

iex> a &&& 0b1100
8

iex> a ||| 0b1100
14

iex> BitwiseOps.calculate_checksum(<<1, 2, 3, 4, 5>>)
15

iex> BitwiseOps.set_bit(0b1010, 0)
11

iex> BitwiseOps.bit_set?(0b1010, 1)
true

Binary Comprehensions and Generators

Basic Binary Comprehensions

# Transform bytes in a binary
data = <<1, 2, 3, 4, 5>>
doubled = for <<byte <- data>>, into: <<>>, do: <<byte * 2>>
# Result: <<2, 4, 6, 8, 10>>

# Filter while processing
filtered = for <<byte <- data>>, byte > 2, into: <<>>, do: <<byte>>
# Result: <<3, 4, 5>>

Common Processing Patterns

defmodule BinaryProcessor do
  # Remove specific bytes
  def remove_bytes(data, bytes_to_remove) do
    for <<byte <- data>>, byte not in bytes_to_remove, into: <<>>, do: <<byte>>
  end

  # Convert to hexadecimal
  def to_hex(data) do
    for <<byte <- data>>, into: "" do
      byte |> Integer.to_string(16) |> String.downcase() |> String.pad_leading(2, "0")
    end
  end
end

Testing in IEx:

iex> data = <<1, 2, 3, 4, 5>>
<<1, 2, 3, 4, 5>>

iex> for <<byte <- data>>, into: <<>>, do: <<byte * 2>>
<<2, 4, 6, 8, 10>>

iex> for <<byte <- data>>, byte > 2, into: <<>>, do: <<byte>>
<<3, 4, 5>>

iex> BinaryProcessor.remove_bytes(data, [2, 4])
<<1, 3, 5>>

iex> BinaryProcessor.to_hex(<<255, 0, 128>>)
"ff0080"

Conclusion

Binaries and bitstrings are a fascinating feature of Elixir for working with data at the bit and byte level. In this article, I explored:

How bitstrings and binaries work internally with precise bit-level control
Binary construction syntax for creating data structures
Pattern matching techniques for elegant data extraction and validation
String operations with proper UTF-8 handling for international text
Bitwise operations for low-level data manipulation
Binary comprehensions for data transformations

Some things I learned:

Precise control: Bitstrings allow exact specification of data representation down to individual bits
Pattern matching power: Binary pattern matching provides elegant solutions for data parsing and validation
UTF-8 support: Excellent support for international text with proper character handling
Memory efficiency: Smart memory sharing and efficient operations
Comprehension support: Powerful transformation capabilities with binary comprehensions

Binaries are one way Elixir handles data processing that I've found particularly interesting. While higher-level data structures like lists and maps provide developer ergonomics, binaries can provide the precision needed for file format processing and data manipulation. Their integration with pattern matching can make parsing tasks more readable and maintainable.

Learning about binaries has changed how I approach data processing in Elixir. They've proven to be a useful feature for building systems that handle specialized data formats and binary processing tasks.

I've found the combination of safety and expressiveness makes Elixir's binary handling a valuable tool for application development that needs precise data control.

Next Steps

With a solid understanding of binaries and bitstrings, the next topic is Ranges in Elixir. Ranges provide an elegant way to represent sequences of numbers, enabling iteration patterns, enumeration operations, and slice operations that complement the precise data control offered by binaries.

The next article will explore:

Creating and working with range syntax and operations
Range enumeration patterns and lazy evaluation benefits
Using ranges for slicing collections and pattern matching
Performance characteristics and memory efficiency of ranges
Applications in data processing and algorithms

Ranges are another useful building block in Elixir, providing ways to work with sequences that scale from small iterations to large data processing tasks!

Learning Elixir: Structs

João Paulo Abreu — Sat, 16 Aug 2025 13:50:34 +0000

Structs are like blueprints for custom-built houses where each room has a specific purpose and fixed location. Unlike a flexible warehouse space where you can put anything anywhere (like maps), a house blueprint defines exactly which rooms exist - kitchen, living room, bedrooms - and ensures every house built from that blueprint follows the same structure. Think of defstruct [:name, :age, :email] as an architectural plan that guarantees every "Person house" will have exactly those three rooms, with compile-time checking to ensure you don't accidentally try to build a bathroom where the kitchen should be. While this structure provides safety and predictability, it also creates powerful opportunities for pattern matching and type-safe data modeling that make large Elixir applications maintainable and robust. In this comprehensive article, we'll explore how structs work, when they're the perfect choice for your data modeling needs, and the patterns that make them indispensable for building reliable, maintainable Elixir systems.

Note: The examples in this article use Elixir 1.18.4. While most operations should work across different versions, some functionality might vary.

Introduction
Understanding Structs
Important Limitations and Warnings
Defining and Creating Custom Structs
Structs vs Maps: When to Use Each
Pattern Matching with Structs for Type Safety
Updating Structs with Immutable Operations
Advanced Struct Patterns
Best Practices
Conclusion
Further Reading
Next Steps

Introduction

Structs in Elixir are specialized maps that provide compile-time guarantees, default values, and type safety for your data structures. They represent the next evolution beyond keyword lists and maps, offering the perfect balance between flexibility and structure for building robust applications.

What makes structs special:

Compile-time guarantees: Field definitions are checked at compile time
Type safety: Clear data contracts with enforced structure
Pattern matching power: Robust matching capabilities for control flow
Default values: Sensible defaults for all fields
Access control: Clear boundaries between internal and external data
Memory efficiency: Optimized internal representation built on maps

Think of structs as data contracts that define exactly what your data should look like:

User profiles: %User{name: "Alice", email: "alice@example.com", role: :admin}
API responses: %Response{status: 200, body: %{}, headers: []}
Configuration objects: %Config{host: "localhost", port: 4000, ssl: false}

Structs excel when you need to:

Define clear data schemas with fixed fields
Ensure type safety across module boundaries
Implement type-safe APIs with clear contracts
Create maintainable APIs with predictable data structures
Build complex applications where data integrity matters
Leverage powerful pattern matching for business logic

Let's explore how they work and why they're essential for serious Elixir development!

Understanding Structs

The Internal Structure

Structs are built on top of maps but with additional compile-time metadata and guarantees:

defmodule User do
  defstruct [:name, :email, age: 0, active: true]
end

# Creating a struct
user = %User{name: "Alice", email: "alice@example.com"}

# Under the hood, it's still a map with a special __struct__ key
IO.inspect(user)
# %User{name: "Alice", email: "alice@example.com", age: 0, active: true}

# You can see the __struct__ field
user.__struct__
# User

# It's still a map at runtime
is_map(user)  # true
Map.keys(user)  # [:__struct__, :active, :age, :email, :name]

Testing in IEx:

iex> defmodule User do
  defstruct [:name, :email, age: 0, active: true]
end
{:module, User, <<...>>, %User{name: nil, email: nil, age: 0, active: true}}

iex> user = %User{name: "Alice", email: "alice@example.com"}
%User{name: "Alice", email: "alice@example.com", age: 0, active: true}

iex> user.__struct__
User

iex> is_map(user)
true

iex> Map.keys(user)
[:active, :name, :__struct__, :email, :age]

Key Characteristics

defmodule Product do
  defstruct [:id, :name, price: 0.0, available: true, tags: []]
end

# Default values are automatically applied
product = %Product{id: 1, name: "Laptop"}
# %Product{available: true, id: 1, name: "Laptop", price: 0.0, tags: []}

# Field access works like maps
product.name  # "Laptop"
product.price  # 0.0

# But you can't access undefined fields (compile-time error)
# product.description  # ** (KeyError) key :description not found

# Pattern matching on struct type
case product do
  %Product{available: true} -> "Product is available"
  %Product{available: false} -> "Product is unavailable"
  _ -> "Not a product"
end

Testing in IEx:

iex> defmodule Product do
  defstruct [:id, :name, price: 0.0, available: true, tags: []]
end
{:module, Product, <<...>>, %Product{id: nil, name: nil, price: 0.0, available: true, tags: []}}

iex> product = %Product{id: 1, name: "Laptop"}
%Product{id: 1, name: "Laptop", price: 0.0, available: true, tags: []}

iex> product.name
"Laptop"

iex> product.price
0.0

iex> case product do
  %Product{available: true} -> "Product is available"
  %Product{available: false} -> "Product is unavailable"
end
"Product is available"

Memory Optimization

defmodule MemoryExample do
  defstruct [:name, :value]
end

# Create multiple structs
struct1 = %MemoryExample{name: "first", value: 1}
struct2 = %MemoryExample{name: "second", value: 2}

# When updating structs, they share key structure in memory
updated = %{struct1 | value: 100}

# The compiler knows the field structure at compile time
# This allows for memory optimizations and better performance

Testing in IEx:

iex> defmodule MemoryExample do
  defstruct [:name, :value]
end
{:module, MemoryExample, <<...>>, %MemoryExample{name: nil, value: nil}}

iex> struct1 = %MemoryExample{name: "first", value: 1}
%MemoryExample{name: "first", value: 1}

iex> updated = %{struct1 | value: 100}
%MemoryExample{name: "first", value: 100}

iex> struct1.name == updated.name
true

Important Limitations and Warnings

Critical Differences from Maps

⚠️ WARNING: While structs are built on maps, they have important limitations that developers must understand:

defmodule LimitationDemo do
  defstruct [:name, :age]
end

demo = %LimitationDemo{name: "Alice", age: 30}

# ✅ These work (struct-specific access)
demo.name  # "Alice"
demo.__struct__  # LimitationDemo

# ❌ These DON'T work (map-specific operations)
# demo[:name]  # ** (UndefinedFunctionError) Access behaviour not implemented for LimitationDemo
# Enum.map(demo, fn {k, v} -> {k, v} end)  # ** (Protocol.UndefinedError)

# ❌ Cannot add undefined fields
# %{demo | undefined_field: "value"}  # ** (KeyError) key :undefined_field not found in struct

# ❌ Cannot use square bracket access
# demo[:name]  # Will raise UndefinedFunctionError

Testing in IEx:

iex> demo = %LimitationDemo{name: "Alice", age: 30}
%LimitationDemo{name: "Alice", age: 30}

iex> demo.name
"Alice"

iex> demo[:name]
** (UndefinedFunctionError) function LimitationDemo.fetch/2 is undefined (LimitationDemo does not implement the Access behaviour)

iex> Enum.map(demo, fn {k, v} -> {k, v} end)
** (Protocol.UndefinedError) protocol Enumerable not implemented for %LimitationDemo{...}

Compile-Time vs Runtime Behavior

Important: @enforce_keys provides compile-time checks, NOT runtime validation:

defmodule EnforceExample do
  @enforce_keys [:id]
  defstruct [:id, :name]
end

# ✅ This works at compile time
valid_struct = %EnforceExample{id: 1, name: "Alice"}

# ❌ This fails at compile time
# invalid_struct = %EnforceExample{name: "Alice"}  # ** (ArgumentError)

# ⚠️ But runtime map conversion can bypass enforcement
map_data = %{name: "Bob"}
converted = struct(EnforceExample, map_data)  # Creates struct with id: nil!

# ⚠️ But runtime conversion can create structs with nil required fields
nil_struct = struct(EnforceExample, %{name: "Test"})  # id becomes nil
case nil_struct do
  %EnforceExample{} -> "This matches even with nil id!"
end

Testing in IEx:

iex> valid = %EnforceExample{id: 1, name: "Alice"}
%EnforceExample{id: 1, name: "Alice"}

iex> struct(EnforceExample, %{name: "Bob"})
%EnforceExample{id: nil, name: "Bob"}

iex> nil_struct = struct(EnforceExample, %{name: "Test"})
%EnforceExample{id: nil, name: "Test"}

iex> case nil_struct do
  %EnforceExample{} -> "This matches!"
end
"This matches!"

Protocol Implementation Implications

Key Point: Structs do NOT implement map protocols by default:

defmodule ProtocolDemo do
  defstruct [:data]
end

demo = %ProtocolDemo{data: [1, 2, 3]}

# ❌ These common map operations don't work
# Map.get(demo, :data)  # Works, but not recommended
# for {key, value} <- demo, do: {key, value}  # ** (Protocol.UndefinedError)

# ✅ Proper access methods
demo.data  # [1, 2, 3]
Map.fetch(demo, :data)  # {:ok, [1, 2, 3]}

# ✅ Convert to map if you need map operations
map_version = Map.from_struct(demo)  # %{data: [1, 2, 3]}
for {key, value} <- map_version, do: {key, value}  # [{:data, [1, 2, 3]}]

Testing in IEx:

iex> demo = %ProtocolDemo{data: [1, 2, 3]}
%ProtocolDemo{data: [1, 2, 3]}

iex> demo.data
[1, 2, 3]

iex> for {key, value} <- demo, do: {key, value}
** (Protocol.UndefinedError) protocol Enumerable not implemented for %ProtocolDemo{...}

iex> map_version = Map.from_struct(demo)
%{data: [1, 2, 3]}

iex> for {key, value} <- map_version, do: {key, value}
[data: [1, 2, 3]]

Memory and Performance Considerations

Performance Tip: Understand how struct updates work:

defmodule PerformanceAware do
  defstruct [:field1, :field2, :field3, :large_data]

  def efficient_update(struct, new_value) do
    # ✅ Efficient: Uses update syntax, shares structure
    %{struct | field1: new_value}
  end

  def inefficient_recreation(struct, new_value) do
    # ❌ Less efficient: Creates entirely new struct
    %__MODULE__{
      field1: new_value,
      field2: struct.field2,
      field3: struct.field3,
      large_data: struct.large_data
    }
  end
end

Safe Conversion Patterns

Best Practice: Always validate when converting between maps and structs:

defmodule SafeConversion do
  defstruct [:required_field, :optional_field]

  def from_map(map) when is_map(map) do
    case Map.fetch(map, :required_field) do
      {:ok, _value} -> 
        {:ok, struct(__MODULE__, map)}
      :error -> 
        {:error, :missing_required_field}
    end
  end

  def from_map(_non_map) do
    {:error, :invalid_input}
  end

  def to_map(%__MODULE__{} = struct) do
    Map.from_struct(struct)
  end
end

Testing in IEx:

iex> SafeConversion.from_map(%{required_field: "present"})
{:ok, %SafeConversion{required_field: "present", optional_field: nil}}

iex> SafeConversion.from_map(%{optional_field: "only"})
{:error, :missing_required_field}

iex> struct = %SafeConversion{required_field: "test"}
%SafeConversion{required_field: "test", optional_field: nil}

iex> SafeConversion.to_map(struct)
%{required_field: "test", optional_field: nil}

Remember: Structs are specialized tools for type-safe data modeling. Use them when you need compile-time guarantees and clear data contracts, but be aware of their limitations compared to regular maps.

Defining and Creating Custom Structs

Basic Struct Definition

defmodule Person do
  # Simple field list - all fields default to nil
  defstruct [:first_name, :last_name, :email]
end

defmodule Account do
  # Mix of required fields and defaults
  defstruct [:username, :email, balance: 0.0, active: true, created_at: nil]
end

defmodule Settings do
  # All fields with defaults
  defstruct theme: "light", language: "en", notifications: true
end

Testing in IEx:

iex> defmodule Person do
  defstruct [:first_name, :last_name, :email]
end
{:module, Person, <<...>>, %Person{first_name: nil, last_name: nil, email: nil}}

iex> %Person{}
%Person{first_name: nil, last_name: nil, email: nil}

iex> %Person{first_name: "Alice", last_name: "Smith"}
%Person{first_name: "Alice", last_name: "Smith", email: nil}

iex> defmodule Settings do
  defstruct theme: "light", language: "en", notifications: true
end
{:module, Settings, <<...>>, %Settings{theme: "light", language: "en", notifications: true}}

iex> %Settings{}
%Settings{theme: "light", language: "en", notifications: true}

Enforcing Required Keys

defmodule User do
  @enforce_keys [:id, :username]
  defstruct [:id, :username, :email, role: :user, active: true]
end

# This works - required keys provided
user = %User{id: 1, username: "alice"}
# %User{id: 1, username: "alice", email: nil, role: :user, active: true}

# This would raise a compile-time error
# %User{username: "alice"}  # ** (ArgumentError) missing required keys [:id]

Testing in IEx:

iex> defmodule User do
  @enforce_keys [:id, :username]
  defstruct [:id, :username, :email, role: :user, active: true]
end
{:module, User, <<...>>, %User{id: nil, username: nil, email: nil, role: :user, active: true}}

iex> %User{id: 1, username: "alice"}
%User{id: 1, username: "alice", email: nil, role: :user, active: true}

iex> %User{username: "alice"}
** (ArgumentError) the following keys must also be given when building struct User: [:id]

Constructor Functions

defmodule Customer do
  defstruct [:id, :name, :email, :phone, created_at: nil, updated_at: nil]

  # Create a new customer with current timestamp
  def new(id, name, email, phone \\ nil) do
    now = DateTime.utc_now()
    %__MODULE__{
      id: id,
      name: name,
      email: email,
      phone: phone,
      created_at: now,
      updated_at: now
    }
  end

  # Alternative constructor with validation
  def create(attrs) do
    with {:ok, id} <- validate_id(attrs[:id]),
         {:ok, name} <- validate_name(attrs[:name]),
         {:ok, email} <- validate_email(attrs[:email]) do
      {:ok, new(id, name, email, attrs[:phone])}
    end
  end

  defp validate_id(id) when is_integer(id) and id > 0, do: {:ok, id}
  defp validate_id(_), do: {:error, :invalid_id}

  defp validate_name(name) when is_binary(name) and byte_size(name) > 0, do: {:ok, name}
  defp validate_name(_), do: {:error, :invalid_name}

  defp validate_email(email) when is_binary(email) do
    if String.contains?(email, "@"), do: {:ok, email}, else: {:error, :invalid_email}
  end
  defp validate_email(_), do: {:error, :invalid_email}
end

Testing in IEx:

iex> customer = Customer.new(1, "Alice Smith", "alice@example.com")
%Customer{
  id: 1,
  name: "Alice Smith",
  email: "alice@example.com",
  phone: nil,
  created_at: ~U[2025-08-16 13:25:32.515579Z],
  updated_at: ~U[2025-08-16 13:25:32.515579Z]
}

iex> Customer.create(%{id: 1, name: "Bob", email: "bob@example.com"})
{:ok, %Customer{...}}

iex> Customer.create(%{id: -1, name: "Invalid", email: "bad-email"})
{:error, :invalid_id}

Nested Structs

defmodule Address do
  defstruct [:street, :city, :state, :zip_code, country: "USA"]
end

defmodule Contact do
  defstruct [:name, :email, :address]

  def new(name, email, address_attrs \\ %{}) do
    address = struct(Address, address_attrs)
    %__MODULE__{name: name, email: email, address: address}
  end
end

defmodule Company do
  defstruct [:name, :contacts, founded_at: nil]

  def new(name) do
    %__MODULE__{name: name, contacts: []}
  end

  def add_contact(%__MODULE__{contacts: contacts} = company, contact) do
    %{company | contacts: [contact | contacts]}
  end
end

Testing in IEx:

iex> address = %Address{street: "123 Main St", city: "Portland", state: "OR", zip_code: "97201"}
%Address{street: "123 Main St", city: "Portland", state: "OR", zip_code: "97201", country: "USA"}

iex> contact = Contact.new("Alice", "alice@example.com", %{street: "123 Main St", city: "Portland"})
%Contact{
  name: "Alice",
  email: "alice@example.com",
  address: %Address{
    street: "123 Main St",
    city: "Portland",
    state: nil,
    zip_code: nil,
    country: "USA"
  }
}

iex> company = Company.new("Tech Corp") |> Company.add_contact(contact)
%Company{
  name: "Tech Corp",
  contacts: [
    %Contact{
      name: "Alice",
      email: "alice@example.com",
      address: %Address{
        street: "123 Main St",
        city: "Portland",
        state: nil,
        zip_code: nil,
        country: "USA"
      }
    }
  ],
  founded_at: nil
}

Structs vs Maps: When to Use Each

Decision Framework

Understanding when to use structs versus maps is crucial for maintainable Elixir code:

Use Structs When

# 1. Defining data schemas with fixed fields
defmodule User do
  defstruct [:id, :name, :email, role: :user, active: true]
end

# 2. Creating APIs that require type guarantees
defmodule APIResponse do
  defstruct [:status, :data, :errors, timestamp: nil]

  def success(data) do
    %__MODULE__{status: :ok, data: data, errors: [], timestamp: DateTime.utc_now()}
  end

  def error(errors) do
    %__MODULE__{status: :error, data: nil, errors: List.wrap(errors), timestamp: DateTime.utc_now()}
  end
end

# 3. Creating type-safe APIs with clear contracts
defmodule UserAPI do
  def to_public_format(%User{id: id, name: name, email: email}) do
    %{id: id, name: name, email: email}
  end

  def is_admin?(%User{role: :admin}), do: true
  def is_admin?(%User{}), do: false
end

# 4. Complex data modeling with business logic
defmodule Order do
  defstruct [:id, :items, :customer_id, :status, total: 0.0, created_at: nil]

  def new(customer_id, items) do
    %__MODULE__{
      id: generate_id(),
      customer_id: customer_id,
      items: items,
      status: :pending,
      total: calculate_total(items),
      created_at: DateTime.utc_now()
    }
  end

  def can_cancel?(%__MODULE__{status: status}) do
    status in [:pending, :confirmed]
  end

  defp generate_id, do: :crypto.strong_rand_bytes(16) |> Base.encode64()
  defp calculate_total(items), do: Enum.sum_by(items, & &1.price)
end

Testing in IEx:

iex> response = APIResponse.success(%{users: [], total: 0})
%APIResponse{
  status: :ok,
  data: %{total: 0, users: []},
  errors: [],
  timestamp: ~U[2025-08-16 13:27:22.659534Z]
}

iex> user = %User{id: 1, name: "Alice", email: "alice@example.com"}
%User{
  id: 1,
  name: "Alice",
  email: "alice@example.com",
  role: :user,
  active: true
}

iex> UserAPI.to_public_format(user)
%{id: 1, name: "Alice", email: "alice@example.com"}

iex> UserAPI.is_admin?(user)
false

Use Maps When

# 1. Dynamic data with unknown keys
defmodule DynamicProcessor do
  def process_json(json_string) do
    # Parse JSON into a map - unknown structure
    Jason.decode!(json_string)
    |> handle_dynamic_data()
  end

  def handle_dynamic_data(data) when is_map(data) do
    # Process arbitrary key-value pairs
    data
    |> Enum.map(fn {key, value} -> {String.upcase(key), value} end)
    |> Enum.into(%{})
  end
end

# 2. Temporary data transformations
defmodule DataTransformer do
  def transform_user_data(users) do
    users
    |> Enum.map(fn user ->
      # Temporary map for transformation
      %{
        "id" => user.id,
        "full_name" => user.name,
        "contact" => user.email,
        "status" => if(user.active, do: "active", else: "inactive")
      }
    end)
  end
end

# 3. Large datasets with frequent key additions/removals
defmodule Cache do
  use GenServer

  def start_link(opts \\ []) do
    GenServer.start_link(__MODULE__, %{}, opts)
  end

  def put(cache, key, value) do
    GenServer.call(cache, {:put, key, value})
  end

  def get(cache, key) do
    GenServer.call(cache, {:get, key})
  end

  # GenServer callbacks
  def handle_call({:put, key, value}, _from, state) do
    new_state = Map.put(state, key, value)
    {:reply, :ok, new_state}
  end

  def handle_call({:get, key}, _from, state) do
    {:reply, Map.get(state, key), state}
  end
end

# 4. Configuration from external sources
defmodule ConfigLoader do
  def load_from_env do
    # Build configuration map from environment variables
    %{
      "DATABASE_URL" => System.get_env("DATABASE_URL"),
      "REDIS_URL" => System.get_env("REDIS_URL"),
      "SECRET_KEY" => System.get_env("SECRET_KEY")
    }
    |> Enum.reject(fn {_key, value} -> is_nil(value) end)
    |> Enum.into(%{})
  end
end

Testing in IEx:

iex> dynamic_data = %{"name" => "alice", "age" => 30, "unknown_field" => "value"}
%{"age" => 30, "name" => "alice", "unknown_field" => "value"}

iex> DynamicProcessor.handle_dynamic_data(dynamic_data)
%{"AGE" => 30, "NAME" => "alice", "UNKNOWN_FIELD" => "value"}

iex> defmodule TempUser, do: defstruct [:id, :name, :email, active: true]
{:module, TempUser, <<...>>, %TempUser{id: nil, name: nil, email: nil, active: true}}

iex> users = [%TempUser{id: 1, name: "Alice", email: "alice@example.com"}]
[%TempUser{id: 1, name: "Alice", email: "alice@example.com", active: true}]

iex> DataTransformer.transform_user_data(users)
[
  %{
    "contact" => "alice@example.com",
    "full_name" => "Alice",
    "id" => 1,
    "status" => "active"
  }
]

Conversion Strategies

defmodule ConversionUtils do
  # Convert struct to map for JSON serialization
  def struct_to_map(%{__struct__: _} = struct) do
    struct
    |> Map.from_struct()
    |> Enum.reject(fn {_key, value} -> is_nil(value) end)
    |> Enum.into(%{})
  end

  # Convert map to struct with validation
  def map_to_struct(map, struct_module) when is_map(map) do
    try do
      struct(struct_module, map)
    rescue
      _ -> {:error, :invalid_struct_data}
    else
      result -> {:ok, result}
    end
  end

  # Safe conversion with defaults
  def safe_struct_conversion(data, struct_module, defaults \\ %{}) do
    clean_data = 
      data
      |> Map.merge(defaults)
      |> Enum.filter(fn {key, _value} -> 
        key in struct_module.__struct__() |> Map.keys()
      end)
      |> Enum.into(%{})

    struct(struct_module, clean_data)
  end
end

Testing in IEx:

iex> defmodule TestUser, do: defstruct [:id, :name, :email, role: :user, active: true]
{:module, TestUser, <<...>>, %TestUser{id: nil, name: nil, email: nil, role: :user, active: true}}

iex> user = %TestUser{id: 1, name: "Alice", email: "alice@example.com"}
%TestUser{
  id: 1,
  name: "Alice",
  email: "alice@example.com",
  role: :user,
  active: true
}

iex> ConversionUtils.struct_to_map(user)
%{active: true, id: 1, name: "Alice", email: "alice@example.com", role: :user}

iex> map_data = %{id: 2, name: "Bob", email: "bob@example.com", invalid_field: "ignored"}
%{id: 2, name: "Bob", email: "bob@example.com", invalid_field: "ignored"}

iex> ConversionUtils.map_to_struct(map_data, TestUser)
{:ok,
 %TestUser{
   id: 2,
   name: "Bob",
   email: "bob@example.com",
   role: :user,
   active: true
 }}

Pattern Matching with Structs for Type Safety

Basic Pattern Matching

defmodule UserProcessor do
  def process_user(%User{active: true, role: :admin} = user) do
    "Processing admin user: #{user.name}"
  end

  def process_user(%User{active: true, role: :user} = user) do
    "Processing regular user: #{user.name}"
  end

  def process_user(%User{active: false} = user) do
    "User #{user.name} is inactive"
  end

  # Catch non-User structs
  def process_user(_other) do
    {:error, :invalid_user_type}
  end
end

defmodule ResponseHandler do
  def handle(%APIResponse{status: :ok, data: data}) do
    {:success, data}
  end

  def handle(%APIResponse{status: :error, errors: errors}) when length(errors) > 0 do
    {:error, errors}
  end

  def handle(%APIResponse{status: status}) do
    {:unknown_status, status}
  end

  # Handle non-APIResponse structs
  def handle(_other) do
    {:error, :invalid_response_type}
  end
end

Testing in IEx:

iex> admin = %User{id: 1, name: "Alice", role: :admin, active: true}
%User{id: 1, name: "Alice", email: nil, role: :admin, active: true}

iex> UserProcessor.process_user(admin)
"Processing admin user: Alice"

iex> inactive_user = %User{id: 2, name: "Bob", active: false}
%User{id: 2, name: "Bob", email: nil, role: :user, active: false}

iex> UserProcessor.process_user(inactive_user)
"User Bob is inactive"

iex> UserProcessor.process_user(%{name: "Not a user struct"})
{:error, :invalid_user_type}

Advanced Pattern Matching with Guards

defmodule OrderProcessor do
  def can_process?(%Order{status: :pending, total: total}) when total > 0 do
    true
  end

  def can_process?(%Order{status: :confirmed, total: total}) when total > 0 do
    true
  end

  def can_process?(_order), do: false

  def apply_discount(%Order{total: total} = order, percentage) 
      when percentage > 0 and percentage <= 100 do
    discount = total * (percentage / 100)
    new_total = total - discount

    %{order | total: new_total}
  end

  def categorize_order(%Order{total: total}) when total >= 1000 do
    :premium
  end

  def categorize_order(%Order{total: total}) when total >= 100 do
    :standard
  end

  def categorize_order(%Order{}) do
    :basic
  end
end

defmodule PaymentHandler do
  def process_payment(%Order{status: :confirmed, total: total} = order, %{type: :credit_card} = payment)
      when total > 0 do
    # Process credit card payment
    case charge_card(payment, total) do
      {:ok, transaction_id} ->
        {:ok, %{order | status: :paid}, transaction_id}
      {:error, reason} ->
        {:error, reason}
    end
  end

  def process_payment(%Order{status: :confirmed, total: total} = order, %{type: :bank_transfer})
      when total > 0 do
    # Process bank transfer
    {:ok, %{order | status: :payment_pending}}
  end

  def process_payment(%Order{status: status}, _payment) when status != :confirmed do
    {:error, :order_not_confirmed}
  end

  def process_payment(%Order{total: total}, _payment) when total <= 0 do
    {:error, :invalid_total}
  end

  defp charge_card(_payment, _amount) do
    # Simulate payment processing
    if :rand.uniform() > 0.1 do
      {:ok, "txn_" <> (:crypto.strong_rand_bytes(8) |> Base.encode64())}
    else
      {:error, :payment_failed}
    end
  end
end

Testing in IEx:

iex> order = %Order{id: "order_1", status: :pending, total: 150.0}
%Order{
  id: "order_1",
  items: nil,
  customer_id: nil,
  status: :pending,
  total: 150.0,
  created_at: nil
}

iex> OrderProcessor.can_process?(order)
true

iex> OrderProcessor.categorize_order(order)
:standard

iex> discounted = OrderProcessor.apply_discount(order, 10)
%Order{
  id: "order_1",
  items: nil,
  customer_id: nil,
  status: :pending,
  total: 135.0,
  created_at: nil
}

iex> confirmed_order = %{order | status: :confirmed}
%Order{
  id: "order_1",
  items: nil,
  customer_id: nil,
  status: :confirmed,
  total: 150.0,
  created_at: nil
}

iex> payment = %{type: :credit_card, number: "****-****-****-1234"}
%{type: :credit_card, number: "****-****-****-1234"}

iex> PaymentHandler.process_payment(confirmed_order, payment)
{:ok,
 %Order{
   id: "order_1",
   items: nil,
   customer_id: nil,
   status: :paid,
   total: 150.0,
   created_at: nil
 }, "txn_hjIdJ6UP6To="}

Struct Validation with Pattern Matching

defmodule UserValidator do
  def validate_registration(%User{} = user) do
    user
    |> validate_required_fields()
    |> validate_email_format()
    |> validate_role()
    |> case do
      {:ok, validated_user} -> {:ok, validated_user}
      {:error, _} = error -> error
    end
  end

  def validate_registration(_non_user) do
    {:error, :invalid_user_struct}
  end

  defp validate_required_fields(%User{id: nil}), do: {:error, :missing_id}
  defp validate_required_fields(%User{name: nil}), do: {:error, :missing_name}
  defp validate_required_fields(%User{name: name}) when byte_size(name) == 0, do: {:error, :empty_name}
  defp validate_required_fields(user), do: {:ok, user}

  defp validate_email_format({:error, _} = error), do: error
  defp validate_email_format({:ok, %User{email: nil} = user}), do: {:ok, user}
  defp validate_email_format({:ok, %User{email: email} = user}) do
    if String.contains?(email, "@") do
      {:ok, user}
    else
      {:error, :invalid_email_format}
    end
  end

  defp validate_role({:error, _} = error), do: error
  defp validate_role({:ok, %User{role: role} = user}) when role in [:user, :admin, :moderator] do
    {:ok, user}
  end
  defp validate_role({:ok, %User{role: _invalid_role}}) do
    {:error, :invalid_role}
  end
end

defmodule StructMatcher do
  # Match on multiple struct types
  def identify_data(%User{name: name}) do
    {:user, name}
  end

  def identify_data(%Order{id: id}) do
    {:order, id}
  end

  def identify_data(%APIResponse{status: status}) do
    {:response, status}
  end

  def identify_data(other) when is_map(other) do
    {:map, Map.keys(other)}
  end

  def identify_data(_other) do
    :unknown
  end

  # Pattern match with extraction
  def extract_identifiers([%User{id: user_id} | rest]) do
    [user_id | extract_identifiers(rest)]
  end

  def extract_identifiers([%Order{id: order_id} | rest]) do
    [order_id | extract_identifiers(rest)]
  end

  def extract_identifiers([_other | rest]) do
    extract_identifiers(rest)
  end

  def extract_identifiers([]) do
    []
  end
end

Testing in IEx:

iex> valid_user = %User{id: 1, name: "Alice", email: "alice@example.com"}
%User{
  id: 1,
  name: "Alice",
  email: "alice@example.com",
  role: :user,
  active: true
}

iex> UserValidator.validate_registration(valid_user)
{:ok,
 %User{
   id: 1,
   name: "Alice",
   email: "alice@example.com",
   role: :user,
   active: true
 }}

iex> invalid_user = %User{id: nil, name: "Bob"}
%User{id: nil, name: "Bob", email: nil, role: :user, active: true}

iex> UserValidator.validate_registration(invalid_user)
{:error, :missing_id}

iex> StructMatcher.identify_data(%User{name: "Alice"})
{:user, "Alice"}

iex> StructMatcher.identify_data(%{random: "data"})
{:map, [:random]}

Updating Structs with Immutable Operations

Basic Update Syntax

defmodule ImmutableUpdates do
  def demo_basic_updates do
    # Create initial struct
    user = %User{id: 1, name: "Alice", email: "alice@example.com"}

    # Update single field
    updated_user = %{user | name: "Alice Smith"}

    # Update multiple fields
    activated_user = %{user | active: true, role: :admin}

    # Original struct is unchanged
    IO.inspect({user.name, updated_user.name})
    # {"Alice", "Alice Smith"}

    {user, updated_user, activated_user}
  end

  def safe_update(struct, field, value) do
    if Map.has_key?(struct, field) do
      {:ok, %{struct | field => value}}
    else
      {:error, :field_not_found}
    end
  end

  def conditional_update(%User{active: true} = user, updates) do
    # Only update if user is active
    {:ok, Map.merge(user, updates)}
  end

  def conditional_update(%User{active: false}, _updates) do
    {:error, :user_inactive}
  end
end

Testing in IEx:

iex> user = %User{id: 1, name: "Alice", email: "alice@example.com"}
%User{
  id: 1,
  name: "Alice",
  email: "alice@example.com",
  role: :user,
  active: true
}

iex> updated = %{user | name: "Alice Smith", role: :admin}
%User{
  id: 1,
  name: "Alice Smith",
  email: "alice@example.com",
  role: :admin,
  active: true
}

iex> user.name
"Alice"

iex> updated.name
"Alice Smith"

iex> ImmutableUpdates.safe_update(user, :email, "new@example.com")
{:ok,
 %User{
   id: 1,
   name: "Alice",
   email: "new@example.com",
   role: :user,
   active: true
 }}

Functional Update Patterns

defmodule UserService do
  def update_profile(%User{} = user, changes) do
    user
    |> apply_name_change(changes[:name])
    |> apply_email_change(changes[:email])
    |> apply_role_change(changes[:role])
    |> touch_updated_at()
  end

  defp apply_name_change(user, nil), do: user
  defp apply_name_change(user, new_name) when is_binary(new_name) do
    %{user | name: String.trim(new_name)}
  end

  defp apply_email_change(user, nil), do: user
  defp apply_email_change(user, new_email) when is_binary(new_email) do
    if String.contains?(new_email, "@") do
      %{user | email: String.downcase(new_email)}
    else
      user  # Invalid email, don't update
    end
  end

  defp apply_role_change(user, nil), do: user
  defp apply_role_change(user, new_role) when new_role in [:user, :admin, :moderator] do
    %{user | role: new_role}
  end
  defp apply_role_change(user, _invalid_role), do: user

  defp touch_updated_at(user) do
    Map.put(user, :updated_at, DateTime.utc_now())
  end

  # Batch update with validation
  def batch_update(users, update_fn) when is_list(users) and is_function(update_fn, 1) do
    users
    |> Enum.map(update_fn)
    |> Enum.filter(&valid_user?/1)
  end

  defp valid_user?(%User{id: id, name: name}) when not is_nil(id) and is_binary(name) do
    byte_size(name) > 0
  end
  defp valid_user?(_), do: false
end

defmodule OrderUpdater do
  def add_item(%Order{items: items} = order, new_item) do
    updated_items = [new_item | items || []]
    new_total = calculate_total(updated_items)

    %{order | items: updated_items, total: new_total}
  end

  def remove_item(%Order{items: items} = order, item_id) do
    updated_items = Enum.reject(items || [], &(&1.id == item_id))
    new_total = calculate_total(updated_items)

    %{order | items: updated_items, total: new_total}
  end

  def apply_discount(%Order{total: total} = order, %{type: :percentage, value: percent}) 
      when percent > 0 and percent <= 100 do
    discount_amount = total * (percent / 100)
    new_total = max(total - discount_amount, 0)

    %{order | total: new_total}
  end

  def apply_discount(%Order{total: total} = order, %{type: :fixed, value: amount}) 
      when amount > 0 do
    new_total = max(total - amount, 0)

    %{order | total: new_total}
  end

  defp calculate_total(items) do
    items
    |> Enum.sum_by(fn item -> item.price * item.quantity end)
  end
end

Testing in IEx:

iex> user = %User{id: 1, name: "alice", email: "ALICE@EXAMPLE.COM"}
%User{
  id: 1,
  name: "alice",
  email: "ALICE@EXAMPLE.COM",
  role: :user,
  active: true
}

iex> changes = %{name: "Alice Smith  ", email: "ALICE.SMITH@EXAMPLE.COM", role: :admin}
%{name: "Alice Smith  ", email: "ALICE.SMITH@EXAMPLE.COM", role: :admin}

iex> updated = UserService.update_profile(user, changes)
%{
  active: true,
  id: 1,
  name: "Alice Smith",
  __struct__: User,
  email: "alice.smith@example.com",
  role: :admin,
  updated_at: ~U[2025-08-16 13:38:30.171564Z]
}

Complex Update Workflows

defmodule WorkflowUpdater do
  # Pipeline-based updates
  def process_user_activation(user_id, activation_data) do
    with {:ok, user} <- fetch_user(user_id),
         {:ok, validated_user} <- validate_activation(user, activation_data),
         {:ok, activated_user} <- activate_user(validated_user),
         {:ok, enriched_user} <- enrich_user_data(activated_user),
         :ok <- notify_activation(enriched_user) do
      {:ok, enriched_user}
    end
  end

  defp fetch_user(_user_id) do
    # Simulate database fetch
    {:ok, %User{id: 1, name: "Alice", active: false}}
  end

  defp validate_activation(%User{active: true}, _data) do
    {:error, :already_active}
  end

  defp validate_activation(user, %{email_verified: true, phone_verified: true}) do
    {:ok, user}
  end

  defp validate_activation(_user, _data) do
    {:error, :incomplete_verification}
  end

  defp activate_user(user) do
    activated = %{user | active: true, role: :user}
    {:ok, activated}
  end

  defp enrich_user_data(user) do
    enriched = Map.put(user, :activated_at, DateTime.utc_now())
    {:ok, enriched}
  end

  defp notify_activation(_user) do
    # Simulate notification
    :ok
  end

  # Conditional updates with state machine
  def transition_order_status(%Order{status: :pending} = order, :confirm) do
    {:ok, %{order | status: :confirmed}}
  end

  def transition_order_status(%Order{status: :confirmed} = order, :ship) do
    {:ok, %{order | status: :shipped}}
  end

  def transition_order_status(%Order{status: :shipped} = order, :deliver) do
    {:ok, %{order | status: :delivered}}
  end

  def transition_order_status(%Order{status: current}, desired) do
    {:error, {:invalid_transition, current, desired}}
  end

  # Nested struct updates
  def update_user_address(%Contact{address: address} = contact, address_changes) do
    updated_address = Map.merge(address, address_changes)
    %{contact | address: updated_address}
  end
end

Testing in IEx:

iex> activation_data = %{email_verified: true, phone_verified: true}
%{email_verified: true, phone_verified: true}

iex> WorkflowUpdater.process_user_activation(1, activation_data)
{:ok,
 %{
   active: true,
   id: 1,
   name: "Alice",
   __struct__: User,
   email: nil,
   role: :user,
   activated_at: ~U[2025-08-16 13:39:28.476339Z]
 }}

iex> order = %Order{id: "order_1", status: :pending}
%Order{
  id: "order_1",
  items: nil,
  customer_id: nil,
  status: :pending,
  total: 0.0,
  created_at: nil
}

iex> WorkflowUpdater.transition_order_status(order, :confirm)
{:ok,
 %Order{
   id: "order_1",
   items: nil,
   customer_id: nil,
   status: :confirmed,
   total: 0.0,
   created_at: nil
 }}

iex> WorkflowUpdater.transition_order_status(order, :ship)
{:error, {:invalid_transition, :pending, :ship}}

Advanced Struct Patterns

Using @derive for Protocol Implementation

# Custom derivation for Inspect protocol - show only public fields
defmodule APIUser do
  @derive {Inspect, only: [:id, :name, :email]}
  defstruct [:id, :name, :email, :password_hash, :internal_notes]
end

# Hide sensitive fields from inspection
defmodule SecureUser do
  @derive {Inspect, except: [:password_hash, :secret_key]}
  defstruct [:id, :name, :email, :password_hash, :secret_key]
end

# For libraries that support derivation, you can specify multiple
defmodule Product do
  @derive {Inspect, except: [:internal_cost]}
  defstruct [:id, :name, :price, :internal_cost, :supplier_id]
end

Testing in IEx:

iex> user = %APIUser{id: 1, name: "Alice", email: "alice@example.com", password_hash: "secret", internal_notes: "VIP"}
#APIUser<id: 1, name: "Alice", email: "alice@example.com", ...>

iex> inspect(user)
"#APIUser<id: 1, name: \"Alice\", email: \"alice@example.com\", ...>"

iex> secure = %SecureUser{id: 1, name: "Alice", password_hash: "secret"}
#SecureUser<id: 1, name: "Alice", email: nil, ...>

Module Alias Pattern

defmodule UserAccount do
  alias __MODULE__

  defstruct [:id, :username, :email, :profile, created_at: nil]

  def new(username, email) do
    %UserAccount{
      id: generate_id(),
      username: username,
      email: email,
      created_at: DateTime.utc_now()
    }
  end

  def with_profile(%UserAccount{} = account, profile_data) do
    %{account | profile: profile_data}
  end

  defp generate_id do
    :crypto.strong_rand_bytes(8) |> Base.encode64()
  end
end

defmodule TeamMember do
  alias __MODULE__

  @enforce_keys [:user_id, :team_id]
  defstruct [:user_id, :team_id, :role, :permissions, joined_at: nil]

  def new(user_id, team_id, role \\ :member) do
    %TeamMember{
      user_id: user_id,
      team_id: team_id,
      role: role,
      permissions: default_permissions(role),
      joined_at: DateTime.utc_now()
    }
  end

  def promote(%TeamMember{} = member, new_role) do
    %{member | role: new_role, permissions: default_permissions(new_role)}
  end

  defp default_permissions(:admin), do: [:read, :write, :delete, :manage]
  defp default_permissions(:moderator), do: [:read, :write, :delete]
  defp default_permissions(:member), do: [:read, :write]
  defp default_permissions(_), do: [:read]
end

Testing in IEx:

iex> account = UserAccount.new("alice", "alice@example.com")
%UserAccount{
  id: "nvL4rQrEyBo=",
  username: "alice",
  email: "alice@example.com",
  profile: nil,
  created_at: ~U[2025-08-16 13:42:46.313086Z]
}

iex> member = TeamMember.new(1, 5, :moderator)
%TeamMember{
  user_id: 1,
  team_id: 5,
  role: :moderator,
  permissions: [:read, :write, :delete],
  joined_at: ~U[2025-08-16 13:43:03.302761Z]
}

iex> promoted = TeamMember.promote(member, :admin)
%TeamMember{
  user_id: 1,
  team_id: 5,
  role: :admin,
  permissions: [:read, :write, :delete, :manage],
  joined_at: ~U[2025-08-16 13:43:03.302761Z]
}

Best Practices

Do's and Don'ts

✅ DO: Use @enforce_keys for required fields

# Good - enforces critical fields at compile time
defmodule User do
  @enforce_keys [:id, :email]
  defstruct [:id, :email, :name, role: :user, active: true]
end

✅ DO: Provide constructor functions

# Good - encapsulates creation logic
defmodule User do
  defstruct [:id, :name, :email, created_at: nil]

  def new(name, email) do
    %__MODULE__{
      id: generate_id(),
      name: name,
      email: email,
      created_at: DateTime.utc_now()
    }
  end

  defp generate_id, do: :crypto.strong_rand_bytes(8) |> Base.encode64()
end

✅ DO: Use pattern matching for type safety

# Good - clear, type-safe function definitions
def process_user(%User{active: true} = user) do
  # Process active user
end

def process_user(%User{active: false}) do
  {:error, :user_inactive}
end

✅ DO: Use struct-specific access methods

# Good - clear, safe field access
def get_user_display_name(%User{name: name}) when is_binary(name) do
  String.trim(name)
end

def get_user_display_name(%User{name: nil}) do
  "Unknown User"
end

❌ DON'T: Access undefined fields

# Bad - will raise KeyError
defmodule BadExample do
  defstruct [:name]
end

user = %BadExample{name: "Alice"}
# user.undefined_field  # ** (KeyError)

❌ DON'T: Use structs for dynamic data

# Bad - structs are for fixed schemas
defmodule BadDynamic do
  defstruct []  # Empty struct defeats the purpose
end

# Good - use maps for dynamic data
dynamic_data = %{"user_123" => %{name: "Alice"}, "user_456" => %{name: "Bob"}}

❌ DON'T: Ignore compile-time guarantees

# Bad - creating structs manually without validation
user = %{__struct__: User, id: nil, name: "Alice"}  # Bypasses @enforce_keys

# Good - use proper struct syntax
user = %User{id: 1, name: "Alice"}

Performance Considerations

defmodule PerformanceExample do
  defstruct [:id, :data, :metadata]

  # Efficient: Update syntax shares memory structure
  def efficient_update(%__MODULE__{} = struct, new_data) do
    %{struct | data: new_data}
  end

  # Less efficient: Creating new struct from scratch
  def inefficient_update(%__MODULE__{id: id, metadata: meta}, new_data) do
    %__MODULE__{id: id, data: new_data, metadata: meta}
  end

  # Batch operations for multiple updates
  def batch_update(structs, update_fn) when is_function(update_fn, 1) do
    Enum.map(structs, update_fn)
  end

  # Stream for large datasets
  def stream_process(structs, process_fn) do
    structs
    |> Stream.map(process_fn)
    |> Stream.filter(&valid?/1)
    |> Enum.to_list()
  end

  defp valid?(%__MODULE__{id: id}) when not is_nil(id), do: true
  defp valid?(_), do: false
end

Conclusion

Structs in Elixir represent a powerful evolution in data modeling that bridges the gap between the flexibility of maps and the safety of strongly-typed systems. In this comprehensive article, we've explored the full spectrum of struct capabilities:

How structs work internally as enhanced maps with compile-time guarantees
Defining custom structs with required fields, defaults, and constructors
Strategic decision-making between structs and maps based on use cases
Leveraging pattern matching for robust type safety and business logic
Mastering immutable update operations that maintain data integrity
Advanced patterns including @derive attributes and constructor functions
Performance considerations and memory optimization techniques

Key takeaways:

Type safety first: Structs provide compile-time guarantees that prevent entire classes of runtime errors
Clear data contracts: Well-defined structs serve as documentation and API contracts
Pattern matching power: Structs enable robust, readable control flow through pattern matching
Access control: Clear boundaries between internal and external data
Memory efficient: Update syntax allows memory structure sharing for performance
Immutable by design: Struct updates create new instances, maintaining data integrity
Constructor patterns: Custom creation functions encapsulate validation and business logic

Structs demonstrate Elixir's philosophy of making the right choice the easy choice. While maps excel at dynamic data and large datasets, structs shine when you need predictable, well-defined data structures that evolve safely over time. Their integration with pattern matching and the type system makes them indispensable for building maintainable, robust applications.

Understanding structs deeply will transform how you approach data modeling in Elixir. They're not just enhanced maps—they're foundational building blocks for creating systems that are both flexible and reliable, enabling you to build applications that scale gracefully from small scripts to complex distributed systems.

The combination of compile-time safety, runtime performance, and developer ergonomics makes structs one of Elixir's most valuable features for serious application development.

Next Steps

With a solid understanding of structs, you're ready to explore Binaries and Bitstrings in Elixir. This fundamental data structure is essential for working with raw data, I/O operations, network protocols, and efficient string manipulation at the byte level.

In the next article, we'll explore:

Understanding binary data representation and bitstrings
Pattern matching with binaries for data parsing
Binary operations and manipulation functions
Real-world applications in file processing and network communication
Performance considerations when working with binary data

Binaries represent one of Elixir's most powerful features for systems programming and data processing, complementing the high-level data structures we've covered with low-level control when you need it!

Learning Elixir: Keyword Lists

João Paulo Abreu — Sat, 09 Aug 2025 12:35:16 +0000

Keyword lists are like restaurant order forms where each field has a clear label and you can repeat certain items when it makes sense. Unlike a table setting where each position holds one specific item, an order form lets you write "drink: water, appetizer: salad, drink: soda" - keeping everything in order and allowing duplicates when needed. Think of [timeout: 5000, retry: 3, retry: 5] as a configuration form where some options can be specified multiple times, each with its own meaning and context. While this flexibility makes keyword lists perfect for function options and small configurations, it also makes them quite different from maps in both behavior and use cases. In this comprehensive article, we'll explore how keyword lists work, when they're the perfect choice for your data, and the patterns that make them indispensable in Elixir's ecosystem.

Note: The examples in this article use Elixir 1.18.4. While most operations should work across different versions, some functionality might vary.

Introduction
Understanding Keyword Lists
Creating and Manipulating Keyword Lists
Function Options and Configuration Patterns
Working with Duplicate Keys
Pattern Matching with Keyword Lists
Keyword Lists vs Maps
Best Practices
Conclusion
Further Reading
Next Steps

Introduction

Keyword lists are Elixir's specialized data structure for handling small collections of key-value pairs where order matters and duplicate keys provide semantic value. They serve as the backbone for function options, configuration systems, and DSL parameters throughout the Elixir ecosystem.

What makes keyword lists special:

Ordered collection: Keys maintain their insertion order
Duplicate keys allowed: Same key can appear multiple times
Atom keys only: Keys must be atoms (not strings or other types)
Concise syntax: Clean [key: value] notation
Function-friendly: Perfect for optional parameters
DSL integration: Essential for domain-specific languages

Think of keyword lists as configuration forms where each setting has a name:

Function options: [timeout: 5000, retries: 3, async: true]
Query parameters: [where: "active = true", limit: 10, order: "name"]
Route options: [as: :user_profile, only: [:show, :edit]]

Keyword lists excel when you need to:

Pass options to functions with readable names
Maintain the order of configuration items
Allow certain options to be specified multiple times
Create clean, readable APIs for your modules
Build domain-specific languages and configuration systems

Let's explore how they work and why they're indispensable!

Understanding Keyword Lists

The Internal Structure

Keyword lists are actually lists of two-element tuples where the first element is always an atom:

# These are equivalent:
options_short = [timeout: 5000, retry: 3]
options_verbose = [{:timeout, 5000}, {:retry, 3}]

# Verify they're the same
options_short == options_verbose  # true

# Under the hood, it's just a list
[timeout: 5000, retry: 3] |> is_list()  # true

Testing in IEx:

iex> [timeout: 5000, retry: 3]
[timeout: 5000, retry: 3]

iex> [{:timeout, 5000}, {:retry, 3}]
[timeout: 5000, retry: 3]

iex> [timeout: 5000, retry: 3] == [{:timeout, 5000}, {:retry, 3}]
true

iex> is_list([timeout: 5000, retry: 3])
true

Key Characteristics

config = [host: "localhost", port: 4000, host: "remote", ssl: true]

# Order is preserved
Keyword.keys(config)  # [:host, :port, :host, :ssl]

# Duplicate keys are allowed
Keyword.get_values(config, :host)  # ["localhost", "remote"]

# First occurrence is returned by default
Keyword.get(config, :host)  # "localhost"

# Only atoms can be keys in keyword lists
# [{1, "value"}]  # Valid syntax but not a keyword list (integer key)
# [{"key", "value"}]  # Valid syntax but not a keyword list (string key)

Testing in IEx:

iex> config = [host: "localhost", port: 4000, host: "remote", ssl: true]
[host: "localhost", port: 4000, host: "remote", ssl: true]

iex> Keyword.keys(config)
[:host, :port, :host, :ssl]

iex> Keyword.get_values(config, :host)
["localhost", "remote"]

iex> Keyword.get(config, :host)
"localhost"

Syntax Variations

# Standard syntax (recommended)
options = [timeout: 5000, async: true]

# Verbose tuple syntax
options_verbose = [{:timeout, 5000}, {:async, true}]

# Mixed syntax (keyword lists must come last)
mixed = [{:timeout, 5000}, async: true]

# With variables as keys
key = :retry
options_with_var = [{key, 3}, timeout: 5000]  # [retry: 3, timeout: 5000]

# Multi-line for readability
long_config = [
  host: "api.example.com",
  port: 443,
  timeout: 10_000,
  retries: 5,
  ssl: true
]

Testing in IEx:

iex> key = :retry
:retry

iex> options = [{key, 3}, timeout: 5000]
[retry: 3, timeout: 5000]

iex> Keyword.keyword?(options)
true

iex> Keyword.keyword?(%{retry: 3, timeout: 5000})
false

Creating and Manipulating Keyword Lists

Creation Methods

# Literal syntax (most common)
config = [host: "localhost", port: 4000, ssl: true]

# From tuples
from_tuples = Keyword.new([{:timeout, 5000}, {:retries, 3}])

# From maps (loses duplicate key capability)
from_map = Keyword.new(%{timeout: 5000, retries: 3})

# From other enumerables
from_list = Keyword.new([timeout: 5000, retries: 3])

# Empty keyword list
empty = Keyword.new()  # []

# Building incrementally
incremental = []
  |> Keyword.put(:host, "localhost")
  |> Keyword.put(:port, 4000)
  |> Keyword.put(:ssl, true)

Testing in IEx:

iex> Keyword.new([{:timeout, 5000}, {:retries, 3}])
[timeout: 5000, retries: 3]

iex> Keyword.new(%{timeout: 5000, retries: 3})
[timeout: 5000, retries: 3]

iex> [] |> Keyword.put(:host, "localhost") |> Keyword.put(:port, 4000)
[port: 4000, host: "localhost"]

Basic Operations

options = [timeout: 5000, retries: 3, host: "localhost"]

# Get values
timeout = Keyword.get(options, :timeout)        # 5000
missing = Keyword.get(options, :missing, "N/A") # "N/A"
port = Keyword.get(options, :port, 4000)        # 4000 (default)

# Check for keys
has_timeout = Keyword.has_key?(options, :timeout)  # true
has_port = Keyword.has_key?(options, :port)        # false

# Get all keys and values
keys = Keyword.keys(options)      # [:timeout, :retries, :host]
values = Keyword.values(options)  # [5000, 3, "localhost"]

# Check if it's a keyword list and get length
is_keyword = Keyword.keyword?(options)  # true
length = length(options)                # 3

Testing in IEx:

iex> options = [timeout: 5000, retries: 3, host: "localhost"]
[timeout: 5000, retries: 3, host: "localhost"]

iex> Keyword.get(options, :timeout)
5000

iex> Keyword.get(options, :port, 4000)
4000

iex> Keyword.has_key?(options, :timeout)
true

iex> Keyword.keys(options)
[:timeout, :retries, :host]

Updating and Modifying

original = [timeout: 5000, retries: 3]

# Add new key-value pair
with_ssl = Keyword.put(original, :ssl, true)
# [ssl: true, timeout: 5000, retries: 3]

# Update existing key (replaces first occurrence)
updated_timeout = Keyword.put(original, :timeout, 8000)
# [timeout: 8000, retries: 3]

# Add only if key doesn't exist
maybe_added = Keyword.put_new(original, :host, "localhost")
# [host: "localhost", timeout: 5000, retries: 3]

wont_change = Keyword.put_new(original, :timeout, 8000)
# [timeout: 5000, retries: 3] (timeout already exists)

# Delete keys
without_retries = Keyword.delete(original, :retries)
# [timeout: 5000]

# Merge keyword lists
defaults = [timeout: 1000, retries: 1, ssl: false]
user_config = [timeout: 5000, host: "remote"]
merged = Keyword.merge(defaults, user_config)
# [timeout: 5000, retries: 1, ssl: false, host: "remote"]

Testing in IEx:

iex> original = [timeout: 5000, retries: 3]
[timeout: 5000, retries: 3]

iex> Keyword.put(original, :ssl, true)
[ssl: true, timeout: 5000, retries: 3]

iex> Keyword.put_new(original, :timeout, 8000)
[timeout: 5000, retries: 3]

iex> Keyword.put_new(original, :host, "localhost")
[host: "localhost", timeout: 5000, retries: 3]

iex> defaults = [timeout: 1000, retries: 1, ssl: false]
[timeout: 1000, retries: 1, ssl: false]

iex> user_config = [timeout: 5000, host: "remote"]
[timeout: 5000, host: "remote"]

iex> Keyword.merge(defaults, user_config)
[retries: 1, ssl: false, timeout: 5000, host: "remote"]

Conversion Operations

# Keyword list to map
kw_list = [name: "Alice", age: 30, role: :admin]
as_map = Enum.into(kw_list, %{})
# %{age: 30, name: "Alice", role: :admin}

# Map to keyword list
map = %{timeout: 5000, retries: 3}
as_keyword = Enum.into(map, [])
# [timeout: 5000, retries: 3] (order may vary)

# Filter keyword list
config = [timeout: 5000, retries: 3, debug: true, verbose: false]
only_booleans = Keyword.take(config, [:debug, :verbose])
# [debug: true, verbose: false]

without_debug = Keyword.drop(config, [:debug, :verbose])
# [timeout: 5000, retries: 3]

Testing in IEx:

iex> kw_list = [name: "Alice", age: 30, role: :admin]
[name: "Alice", age: 30, role: :admin]

iex> Enum.into(kw_list, %{})
%{age: 30, name: "Alice", role: :admin}

iex> map = %{timeout: 5000, retries: 3}
%{retries: 3, timeout: 5000}

iex> Enum.into(map, [])
[timeout: 5000, retries: 3]

iex> config = [timeout: 5000, retries: 3, debug: true, verbose: false]
[timeout: 5000, retries: 3, debug: true, verbose: false]

iex> Keyword.take(config, [:debug, :verbose])
[debug: true, verbose: false]

Function Options and Configuration Patterns

The Idiomatic Elixir Pattern

Functions that accept options typically use keyword lists as the last parameter:

defmodule HTTPClient do
  # Function with default options
  def get(url, opts \\ []) do
    timeout = Keyword.get(opts, :timeout, 5000)
    retries = Keyword.get(opts, :retries, 3)
    _headers = Keyword.get(opts, :headers, [])

    "Requesting #{url} with timeout: #{timeout}ms, retries: #{retries}"
  end

  # More complex option processing
  def post(url, _body, opts \\ []) do
    config = build_config(opts)
    "POST to #{url} with config: #{inspect(config)}"
  end

  defp build_config(opts) do
    %{
      timeout: Keyword.get(opts, :timeout, 5000),
      retries: Keyword.get(opts, :retries, 3),
      headers: Keyword.get(opts, :headers, []),
      follow_redirects: Keyword.get(opts, :follow_redirects, true),
      ssl_verify: Keyword.get(opts, :ssl_verify, true)
    }
  end
end

Testing in IEx:

iex> HTTPClient.get("https://api.example.com")
"Requesting https://api.example.com with timeout: 5000ms, retries: 3"

iex> HTTPClient.get("https://api.example.com", timeout: 1000, retries: 5)
"Requesting https://api.example.com with timeout: 1000ms, retries: 5"

iex> HTTPClient.post("https://api.example.com", "data", ssl_verify: false)
"POST to https://api.example.com with config: %{follow_redirects: true, headers: [], retries: 3, ssl_verify: false, timeout: 5000}"

Option Validation Patterns

defmodule SafeProcessor do
  @valid_options [:timeout, :retries, :async, :callback]
  @required_options [:timeout]

  def process(_data, opts \\ []) do
    with :ok <- validate_options(opts),
         config <- build_config(opts) do
      {:ok, "Processing with config: #{inspect(config)}"}
    else
      {:error, reason} -> {:error, reason}
    end
  end

  defp validate_options(opts) do
    case validate_required(opts) do
      :ok -> validate_allowed(opts)
      error -> error
    end
  end

  defp validate_required(opts) do
    missing = @required_options -- Keyword.keys(opts)
    if missing == [], do: :ok, else: {:error, {:missing_options, missing}}
  end

  defp validate_allowed(opts) do
    invalid = Keyword.keys(opts) -- @valid_options
    if invalid == [], do: :ok, else: {:error, {:invalid_options, invalid}}
  end

  defp build_config(opts) do
    %{
      timeout: Keyword.get(opts, :timeout),
      retries: Keyword.get(opts, :retries, 3),
      async: Keyword.get(opts, :async, false),
      callback: Keyword.get(opts, :callback)
    }
  end
end

Testing in IEx:

iex> SafeProcessor.process("data", timeout: 5000, retries: 2)
{:ok, "Processing with config: %{async: false, callback: nil, retries: 2, timeout: 5000}"}

iex> SafeProcessor.process("data", [])
{:error, {:missing_options, [:timeout]}}

iex> SafeProcessor.process("data", timeout: 5000, invalid_option: true)
{:error, {:invalid_options, [:invalid_option]}}

Configuration Management

defmodule AppConfig do
  @default_config [
    host: "localhost",
    port: 4000,
    pool_size: 10,
    timeout: 15_000,
    ssl: false,
    retries: 3
  ]

  def load(env_config \\ []) do
    @default_config
    |> Keyword.merge(env_config)
    |> validate_config()
  end

  def get_database_config(config) do
    config
    |> Keyword.take([:host, :port, :pool_size, :ssl])
    |> add_database_specific_options()
  end

  def get_http_config(config) do
    config
    |> Keyword.take([:host, :port, :timeout, :retries, :ssl])
  end

  defp add_database_specific_options(config) do
    config
    |> Keyword.put_new(:username, "postgres")
    |> Keyword.put_new(:password, "")
    |> Keyword.put_new(:database, "myapp_dev")
  end

  defp validate_config(config) do
    cond do
      config[:port] < 1 or config[:port] > 65535 ->
        {:error, "Invalid port number"}
      config[:pool_size] < 1 ->
        {:error, "Pool size must be positive"}
      true ->
        {:ok, config}
    end
  end
end

Testing in IEx:

iex> AppConfig.load()
{:ok, [host: "localhost", port: 4000, pool_size: 10, timeout: 15000, ssl: false, retries: 3]}

iex> AppConfig.load(port: 8080, ssl: true)
{:ok, [host: "localhost", port: 8080, pool_size: 10, timeout: 15000, ssl: true, retries: 3]}

iex> {:ok, config} = AppConfig.load()
{:ok, [host: "localhost", port: 4000, pool_size: 10, timeout: 15000, ssl: false, retries: 3]}

iex> AppConfig.get_database_config(config)
[host: "localhost", port: 4000, pool_size: 10, ssl: false, username: "postgres", password: "", database: "myapp_dev"]

Documentation Patterns

defmodule DocumentedModule do
  @doc """
  Processes data with configurable options.

  ## Options

    * `:timeout` - Request timeout in milliseconds (default: 5000)
    * `:retries` - Number of retry attempts (default: 3)
    * `:async` - Process asynchronously (default: false)
    * `:callback` - Function called on completion (default: nil)
    * `:format` - Output format, either `:json` or `:text` (default: `:json`)

  ## Examples

      iex> DocumentedModule.process("data")
      {:ok, "Processing data with default options"}

      iex> DocumentedModule.process("data", timeout: 1000, async: true)
      {:ok, "Processing data asynchronously with 1000ms timeout"}

  """
  def process(data, opts \\ []) do
    timeout = Keyword.get(opts, :timeout, 5000)
    async = Keyword.get(opts, :async, false)

    async_text = if async, do: "asynchronously ", else: ""
    {:ok, "Processing #{data} #{async_text}with #{timeout}ms timeout"}
  end
end

Testing in IEx:

iex> DocumentedModule.process("data")
{:ok, "Processing data with 5000ms timeout"}

iex> DocumentedModule.process("data", timeout: 1000, async: true)
{:ok, "Processing data asynchronously with 1000ms timeout"}

Working with Duplicate Keys

Understanding Duplicate Key Behavior

config = [env: :dev, timeout: 5000, env: :prod, retry: 3, env: :test]

# get/2 returns the FIRST occurrence
primary_env = Keyword.get(config, :env)  # :dev

# get_values/2 returns ALL occurrences
all_envs = Keyword.get_values(config, :env)  # [:dev, :prod, :test]

# has_key?/2 returns true if ANY occurrence exists
has_env = Keyword.has_key?(config, :env)  # true

# delete/2 removes ALL occurrences
no_envs = Keyword.delete(config, :env)
# [timeout: 5000, retry: 3]

Testing in IEx:

iex> config = [env: :dev, timeout: 5000, env: :prod, retry: 3, env: :test]
[env: :dev, timeout: 5000, env: :prod, retry: 3, env: :test]

iex> Keyword.get(config, :env)
:dev

iex> Keyword.get_values(config, :env)
[:dev, :prod, :test]

iex> Keyword.delete(config, :env)
[timeout: 5000, retry: 3]

Practical Use Cases for Duplicates

defmodule PlugPipeline do
  # Multiple middleware configurations
  def build_pipeline(opts) do
    middleware_configs = Keyword.get_values(opts, :middleware)
    auth_configs = Keyword.get_values(opts, :auth)

    %{
      middleware: middleware_configs,
      auth: auth_configs,
      timeout: Keyword.get(opts, :timeout, 30_000)
    }
  end

  def example_usage do
    options = [
      middleware: {:cors, origins: ["localhost"]},
      middleware: {:rate_limit, max: 100},
      middleware: {:logging, level: :info},
      auth: {:token, header: "Authorization"},
      auth: {:session, store: :cookie},
      timeout: 5000
    ]

    build_pipeline(options)
  end
end

Testing in IEx:

iex> PlugPipeline.example_usage()
%{
  auth: [token: [header: "Authorization"], session: [store: :cookie]],
  middleware: [
    cors: [origins: ["localhost"]],
    rate_limit: [max: 100],
    logging: [level: :info]
  ],
  timeout: 5000
}

Advanced Duplicate Key Patterns

defmodule QueryBuilder do
  def build_query(clauses) do
    %{
      select: build_select_clause(clauses),
      where: build_where_clauses(clauses),
      join: build_join_clauses(clauses),
      order: build_order_clauses(clauses)
    }
  end

  defp build_select_clause(clauses) do
    case Keyword.get_values(clauses, :select) do
      [] -> "*"
      fields -> Enum.join(fields, ", ")
    end
  end

  defp build_where_clauses(clauses) do
    clauses
    |> Keyword.get_values(:where)
    |> Enum.join(" AND ")
  end

  defp build_join_clauses(clauses) do
    Keyword.get_values(clauses, :join)
  end

  defp build_order_clauses(clauses) do
    clauses
    |> Keyword.get_values(:order)
    |> Enum.join(", ")
  end

  def example_query do
    clauses = [
      select: "name",
      select: "email",
      select: "age",
      where: "active = true",
      where: "age >= 18",
      join: "LEFT JOIN profiles ON users.id = profiles.user_id",
      order: "name ASC",
      order: "created_at DESC"
    ]

    build_query(clauses)
  end
end

Testing in IEx:

iex> QueryBuilder.example_query()
%{
  join: ["LEFT JOIN profiles ON users.id = profiles.user_id"],
  order: "name ASC, created_at DESC",
  select: "name, email, age",
  where: "active = true AND age >= 18"
}

Handling Duplicates Safely

defmodule DuplicateHandler do
  # Get first occurrence with fallback
  def get_first_or_default(keyword_list, key, default) do
    case Keyword.get_values(keyword_list, key) do
      [] -> default
      [first | _] -> first
    end
  end

  # Get last occurrence
  def get_last(keyword_list, key) do
    keyword_list
    |> Keyword.get_values(key)
    |> List.last()
  end

  # Remove specific occurrence by value
  def delete_value(keyword_list, key, value) do
    Enum.reject(keyword_list, fn {k, v} -> k == key and v == value end)
  end

  # Replace all occurrences with single value
  def replace_all(keyword_list, key, new_value) do
    keyword_list
    |> Keyword.delete(key)
    |> Keyword.put(key, new_value)
  end
end

Testing in IEx:

iex> config = [env: :dev, timeout: 5000, env: :prod, env: :test]
[env: :dev, timeout: 5000, env: :prod, env: :test]

iex> DuplicateHandler.get_last(config, :env)
:test

iex> DuplicateHandler.delete_value(config, :env, :prod)
[env: :dev, timeout: 5000, env: :test]

iex> DuplicateHandler.replace_all(config, :env, :staging)
[env: :staging, timeout: 5000]

Pattern Matching with Keyword Lists

The Official Warning

Important: The Elixir documentation explicitly advises against pattern matching directly on keyword lists. Here's why and what to do instead:

Why Avoid Direct Pattern Matching

defmodule AntiPatterns do
  # DON'T DO THIS - Fragile and order-dependent
  def bad_pattern_match([timeout: t, retries: r]) do
    "Timeout: #{t}, Retries: #{r}"
  end

  # This function will fail if:
  # - Keys are in different order: [retries: 3, timeout: 5000]
  # - Extra keys are present: [timeout: 5000, retries: 3, ssl: true]
  # - Keys are missing: [timeout: 5000]

  # DON'T DO THIS EITHER - Still fragile
  def bad_partial_match([timeout: t | _rest]) do
    "Timeout: #{t}"
  end
  # Fails if timeout is not the first key
end

Safe Alternatives Using Keyword Module

defmodule SafePatterns do
  # GOOD - Use Keyword.get/3 for extraction
  def safe_extraction(options) do
    timeout = Keyword.get(options, :timeout, 5000)
    retries = Keyword.get(options, :retries, 3)

    "Timeout: #{timeout}, Retries: #{retries}"
  end

  # GOOD - Validate structure first
  def process_with_validation(options) do
    with {:ok, timeout} <- fetch_timeout(options),
         {:ok, retries} <- fetch_retries(options) do
      {:ok, "Processing with timeout: #{timeout}, retries: #{retries}"}
    end
  end

  defp fetch_timeout(options) do
    case Keyword.fetch(options, :timeout) do
      {:ok, timeout} when is_integer(timeout) and timeout > 0 -> {:ok, timeout}
      {:ok, _} -> {:error, :invalid_timeout}
      :error -> {:error, :missing_timeout}
    end
  end

  defp fetch_retries(options) do
    case Keyword.fetch(options, :retries) do
      {:ok, retries} when is_integer(retries) and retries >= 0 -> {:ok, retries}
      {:ok, _} -> {:error, :invalid_retries}
      :error -> {:ok, 3}  # Default value
    end
  end

  # GOOD - Pattern match on known structure after validation
  def safe_pattern_match(options) when is_list(options) do
    case Keyword.keyword?(options) do
      true -> extract_safely(options)
      false -> {:error, :not_keyword_list}
    end
  end

  defp extract_safely(options) do
    host = Keyword.get(options, :host, "localhost")
    port = Keyword.get(options, :port, 4000)
    {:ok, "Connecting to #{host}:#{port}"}
  end
end

Testing in IEx:

iex> good_options = [retries: 3, timeout: 5000, ssl: true]
[retries: 3, timeout: 5000, ssl: true]

iex> SafePatterns.safe_extraction(good_options)
"Timeout: 5000, Retries: 3"

iex> SafePatterns.process_with_validation(good_options)
{:ok, "Processing with timeout: 5000, retries: 3"}

iex> bad_options = [timeout: -1000, retries: 3]
[timeout: -1000, retries: 3]

iex> SafePatterns.process_with_validation(bad_options)
{:error, :invalid_timeout}

When Pattern Matching Can Work

There are limited scenarios where pattern matching on keyword lists is acceptable:

defmodule LimitedPatternMatching do
  # ACCEPTABLE - Matching on empty list
  def handle_options([]), do: "No options provided"

  # ACCEPTABLE - Matching specific known structures in controlled contexts
  def handle_simple_config([debug: true]), do: "Debug mode enabled"
  def handle_simple_config([debug: false]), do: "Debug mode disabled"
  def handle_simple_config(other), do: handle_complex_config(other)

  # PREFERRED - Always have a catch-all that uses Keyword functions
  defp handle_complex_config(options) do
    debug = Keyword.get(options, :debug, false)
    "Debug mode: #{debug}, other options: #{inspect(Keyword.delete(options, :debug))}"
  end
end

Testing in IEx:

iex> LimitedPatternMatching.handle_options([])
"No options provided"

iex> LimitedPatternMatching.handle_simple_config([debug: true])
"Debug mode enabled"

iex> LimitedPatternMatching.handle_simple_config([debug: true, timeout: 5000])
"Debug mode: true, other options: [timeout: 5000]"

Safe Extraction Patterns

defmodule ExtractionPatterns do
  # Extract with defaults and validation
  def extract_database_config(options) do
    %{
      host: Keyword.get(options, :host, "localhost"),
      port: validate_port(Keyword.get(options, :port, 5432)),
      database: Keyword.fetch!(options, :database),
      username: Keyword.get(options, :username, "postgres"),
      password: Keyword.get(options, :password, ""),
      ssl: Keyword.get(options, :ssl, false)
    }
  rescue
    KeyError -> {:error, :missing_database_name}
  end

  # Multiple option sets handling
  def extract_environments(options) do
    options
    |> Keyword.get_values(:env)
    |> case do
      [] -> [:dev]  # Default environment
      envs -> envs
    end
  end

  # Conditional extraction
  def extract_auth_config(options) do
    case {Keyword.has_key?(options, :username), Keyword.has_key?(options, :token)} do
      {true, false} ->
        {:basic_auth, Keyword.get(options, :username), Keyword.get(options, :password, "")}
      {false, true} ->
        {:token_auth, Keyword.get(options, :token)}
      {false, false} ->
        :no_auth
      {true, true} ->
        {:error, :conflicting_auth_methods}
    end
  end

  defp validate_port(port) when is_integer(port) and port > 0 and port <= 65535, do: port
  defp validate_port(_), do: raise(ArgumentError, "Invalid port number")
end

Testing in IEx:

iex> db_options = [host: "db.example.com", database: "myapp", port: 5432]
[host: "db.example.com", database: "myapp", port: 5432]

iex> ExtractionPatterns.extract_database_config(db_options)
%{database: "myapp", host: "db.example.com", password: "", port: 5432, ssl: false, username: "postgres"}

iex> auth_options = [username: "admin", password: "secret"]
[username: "admin", password: "secret"]

iex> ExtractionPatterns.extract_auth_config(auth_options)
{:basic_auth, "admin", "secret"}

iex> token_options = [token: "abc123"]
[token: "abc123"]

iex> ExtractionPatterns.extract_auth_config(token_options)
{:token_auth, "abc123"}

Keyword Lists vs Maps

Decision Guide

Understanding when to use keyword lists versus maps is crucial for writing idiomatic Elixir:

Use Keyword Lists When:

# 1. Function options (the primary use case)
def api_call(endpoint, opts \\ []) do
  timeout = Keyword.get(opts, :timeout, 5000)
  headers = Keyword.get(opts, :headers, [])
  # Process with options...
end

# 2. Small configuration (typically < 50 keys)
config = [
  host: "localhost",
  port: 4000,
  ssl: false,
  retries: 3
]

# 3. DSL parameters where order matters
route_options = [as: :user_profile, only: [:show, :edit], except: [:delete]]

# 4. Duplicate keys provide semantic meaning
middleware_stack = [
  middleware: {:cors, origins: ["*"]},
  middleware: {:auth, required: true},
  middleware: {:logging, level: :info}
]

# 5. Interfacing with libraries that expect keyword lists
# Many Elixir libraries use keyword lists for options

Use Maps When:

# 1. Large datasets (50+ key-value pairs)
large_config = %{
  database_url: "...",
  redis_url: "...",
  # ... 50+ more configuration items
}

# 2. Large datasets and complex data structures
cache = %{
  "user:123" => %{name: "Alice"},
  "user:456" => %{name: "Bob"},
  # ... potentially thousands of entries
}

# 3. Data modeling and structured records
user = %{
  id: 123,
  name: "Alice",
  email: "alice@example.com",
  created_at: ~U[2024-01-15 10:00:00Z]
}

# 4. Pattern matching requirements
def handle_response(%{status: 200, body: body}), do: {:ok, body}
def handle_response(%{status: 404}), do: {:error, :not_found}

# 5. Unique keys required
settings = %{theme: "dark", language: "en"}  # No duplicate keys allowed

Conversion Strategies

defmodule ConversionStrategies do
  # Convert keyword list to map when it becomes large
  def optimize_for_lookups(options) when length(options) > 50 do
    Enum.into(options, %{})
  end
  def optimize_for_lookups(options), do: options

  # Maintain keyword list for small, option-like data
  def ensure_keyword_list(data) when is_map(data) and map_size(data) <= 20 do
    Enum.into(data, [])
  end
  def ensure_keyword_list(data) when is_list(data), do: data
  def ensure_keyword_list(data), do: data  # Keep as-is for other types

  # Smart conversion based on usage pattern
  def convert_for_usage(data, :large_dataset) when is_list(data) do
    Enum.into(data, %{})
  end
  def convert_for_usage(data, :function_options) when is_map(data) do
    Enum.into(data, [])
  end
  def convert_for_usage(data, _usage), do: data

  # Preserve duplicates when converting back to keyword list
  def map_to_keyword_preserving_order(map, key_order) do
    Enum.map(key_order, fn key -> {key, Map.get(map, key)} end)
  end
end

Testing in IEx:

iex> small_options = [timeout: 5000, retries: 3, ssl: true]
[timeout: 5000, retries: 3, ssl: true]

iex> ConversionStrategies.optimize_for_lookups(small_options)
[timeout: 5000, retries: 3, ssl: true]

iex> large_options = Enum.map(1..60, &{:"key#{&1}", &1})
[key1: 1, key2: 2, key3: 3, key4: 4, key5: 5, ...]

iex> optimized = ConversionStrategies.optimize_for_lookups(large_options)
%{key1: 1, key2: 2, key3: 3, key4: 4, key5: 5, ...}

iex> is_map(optimized)
true

Hybrid Approaches

defmodule HybridPatterns do
  # Use both structures for different purposes
  defstruct options: [], cache: %{}

  def new(options \\ []) do
    %__MODULE__{options: options, cache: build_cache(options)}
  end

  # Keep options as keyword list for API compatibility
  def get_option(%__MODULE__{options: options}, key, default) do
    Keyword.get(options, key, default)
  end

  # Use map for internal lookups
  defp build_cache(options) do
    options
    |> Enum.take(20)  # Cache only first 20 options
    |> Enum.into(%{})
  end

  # Extract frequently accessed options to map, keep others as keyword list
  def partition_options(options, frequent_keys) do
    {frequent, others} = Enum.split_with(options, fn {key, _} ->
      key in frequent_keys
    end)

    {Enum.into(frequent, %{}), others}
  end
end

Testing in IEx:

iex> config = HybridPatterns.new([timeout: 5000, retries: 3, ssl: true])
%HybridPatterns{cache: %{retries: 3, ssl: true, timeout: 5000}, options: [timeout: 5000, retries: 3, ssl: true]}

iex> HybridPatterns.get_option(config, :timeout, 1000)
5000

iex> options = [timeout: 5000, retries: 3, host: "localhost", ssl: true, debug: false]
[timeout: 5000, retries: 3, host: "localhost", ssl: true, debug: false]

iex> HybridPatterns.partition_options(options, [:timeout, :retries])
{%{retries: 3, timeout: 5000}, [host: "localhost", ssl: true, debug: false]}

Best Practices

Do's and Don'ts

✅ DO: Use keyword lists for function options

# Good - idiomatic Elixir pattern
def api_call(endpoint, opts \\ []) do
  timeout = Keyword.get(opts, :timeout, 5000)
  retries = Keyword.get(opts, :retries, 3)
  # Process with options
end

# Usage
api_call("/users", timeout: 1000, retries: 5)

✅ DO: Keep keyword lists small (< 50 keys)

# Good - small configuration
config = [
  host: "localhost",
  port: 4000,
  ssl: true,
  pool_size: 10
]

✅ DO: Use Keyword module functions for access

# Good - safe and flexible
def process_config(config) do
  host = Keyword.get(config, :host, "localhost")
  port = Keyword.get(config, :port, 4000)
  ssl = Keyword.get(config, :ssl, false)

  %{host: host, port: port, ssl: ssl}
end

✅ DO: Document your options clearly

@doc """
## Options

  * `:timeout` - Request timeout in milliseconds (default: 5000)
  * `:retries` - Number of retry attempts (default: 3)
  * `:ssl` - Enable SSL connection (default: false)
"""
def connect(url, opts \\ []) do
  # Implementation
end

❌ DON'T: Use pattern matching directly on keyword lists

# Bad - fragile and order-dependent
def bad_pattern([timeout: t, retries: r]), do: {t, r}

# Good - safe extraction
def good_extraction(opts) do
  timeout = Keyword.get(opts, :timeout, 5000)
  retries = Keyword.get(opts, :retries, 3)
  {timeout, retries}
end

❌ DON'T: Use keyword lists for large datasets

# Bad - not suitable for large datasets
large_config = Enum.map(1..200, &{:"setting#{&1}", &1})

# Good - use maps for large collections
large_config = 1..200 |> Enum.map(&{:"setting#{&1}", &1}) |> Enum.into(%{})

Conclusion

Keyword lists are a specialized but essential data structure in Elixir that serve as the foundation for clean, readable APIs and configuration systems. In this comprehensive article, we've explored:

How keyword lists work internally as lists of two-element tuples
Creating and manipulating keyword lists with the Keyword module
The idiomatic pattern of using keyword lists for function options
Working safely with duplicate keys and understanding their semantic value
Why pattern matching should be avoided and what to use instead
When to choose each data structure for optimal results
Best practices for maintainable and performant code

Key takeaways:

Perfect for function options: Keyword lists are the idiomatic choice for optional parameters
Keep them small: Most suitable for fewer than 50 key-value pairs
Order matters: Unlike maps, keyword lists preserve insertion order
Duplicates allowed: Same keys can appear multiple times with semantic meaning
Use Keyword module: Always prefer Keyword.get/3 over pattern matching
Consider conversion: Convert to maps for large datasets or complex data modeling
Document thoroughly: Clear option documentation improves API usability

Keyword lists demonstrate Elixir's philosophy of having specialized tools for specific jobs. While maps excel at general key-value storage and data modeling, keyword lists shine in their specific niche of function options, small configurations, and DSL parameters. Their unique characteristics—ordered keys, duplicate support, and clean syntax—make them irreplaceable for creating readable, maintainable Elixir code.

Understanding when and how to use keyword lists effectively will help you write more idiomatic Elixir code that integrates seamlessly with the broader ecosystem, from Phoenix web applications to configuration management systems.

Next Steps

With a solid understanding of keyword lists, you're ready to explore Structs in Elixir. Structs provide a way to define custom data types with fixed fields, compile-time guarantees, and pattern matching capabilities that complement the flexible nature of maps and keyword lists.

In the next article, we'll explore:

Defining and creating custom structs
Struct vs map - when to use each approach
Pattern matching with structs for type safety
Updating structs with immutable operations

Structs represent the next level of data modeling in Elixir, providing the structure and type safety that make large applications maintainable and robust!

Learning Elixir: Maps

João Paulo Abreu — Sun, 27 Jul 2025 13:30:32 +0000

Maps are like your smartphone's contacts app where each person has a clear name and you can instantly find their information. Instead of scrolling through contact #1, #2, #3 hoping to find the right person, you simply search for "Sofia" or "Marcus" and get exactly what you need. Think of %{name: "Sofia", role: "Engineer", phone: "+1-555-0123"} as a contact entry where each piece of information has a meaningful label—you know exactly where to find someone's phone number, email, or work details. You can easily add new contacts, update existing information, or organize details however makes sense. In this article, we'll explore how maps work, when they're the perfect choice for your data, and the patterns that make them indispensable for building robust Elixir applications.

Note: The examples in this article use Elixir 1.18.4. While most operations should work across different versions, some functionality might vary.

Introduction
Understanding Maps
Creating and Updating Maps
Accessing Map Values
Pattern Matching with Maps
Essential Map Functions
Working with Nested Maps
Maps vs Other Data Structures
Real World Applications
Best Practices
Conclusion
Further Reading
Next Steps

Introduction

Maps are Elixir's key-value data structure, perfect for storing and organizing data where each piece has a meaningful name or identifier. They're one of the most versatile and commonly used data structures in Elixir applications.

What makes maps special:

Key-value pairs: Each value is associated with a unique key
Fast lookups: Direct access to values by their keys
Flexible keys: Keys can be atoms, strings, or any Elixir term
Dynamic size: Maps can grow and shrink as needed
Immutable: Like all Elixir data, maps cannot be modified in place
Pattern matching friendly: Excellent support for destructuring

Think of maps as contact entries where each piece of information has a clear purpose:

Employee contact: %{name: "Sofia", role: "developer", department: "engineering"}
Server details: %{hostname: "api.server.com", port: 4000, ssl: true}
API response: %{"status" => "success", "data" => [...], "message" => "OK"}

Maps excel when you need to:

Store related information with meaningful labels
Look up values by name rather than position
Represent JSON-like data structures
Build flexible, evolving data schemas

Understanding Maps

The Basics

Maps are collections of key-value pairs enclosed in %{} syntax:

# Empty map
empty = %{}

# Map with atom keys (most common)
product = %{name: "Gaming Laptop", price: 1299.99, category: "electronics"}

# Map with string keys (common for external data)
api_config = %{"endpoint" => "api.service.com", "timeout" => 5000, "retries" => 3}

# Mixed key types (possible but not recommended)
mixed = %{:status => "active", "count" => 42, 1 => "priority"}

# Maps can contain any data types as values
complex = %{
  task_id: 42,
  title: "Deploy to production",
  tags: [:urgent, :backend],
  metadata: %{created_at: ~D[2024-01-15], assigned: true},
  transformer: fn x -> String.upcase(x) end
}

Testing in IEx:

iex> employee = %{name: "Sofia", department: "Engineering", level: "Senior"}
%{department: "Engineering", level: "Senior", name: "Sofia"}

iex> api_config = %{"endpoint" => "api.service.com", "timeout" => 5000}
%{"endpoint" => "api.service.com", "timeout" => 5000}

iex> %{}
%{}

Key Types and Conventions

# Atom keys - preferred for internal data
internal = %{user_id: 123, status: :active, type: :premium}

# String keys - common for external data (JSON, APIs)
external = %{"user_id" => 123, "status" => "active", "type" => "premium"}

# Shorthand syntax for atom keys
shorthand = %{title: "DevOps Lead", experience: 5}
# Equivalent to: %{:title => "DevOps Lead", :experience => 5}

# When keys are dynamic variables
key = :dynamic_key
dynamic = %{key => "value"}  # Results in %{:dynamic_key => "value"}
computed = %{key => "value", department: "Engineering"}

Testing in IEx:

iex> %{title: "DevOps Lead", experience: 5}
%{experience: 5, title: "DevOps Lead"}

iex> key = :status
:status

iex> %{key => "value", brand: "Toyota"}
%{brand: "Toyota", status: "value"}

Map Properties

product = %{sku: "LAP-001", category: "electronics", price: 1299.99}

# Get map size
size = map_size(product)  # 3

# Check if key exists
has_sku = Map.has_key?(product, :sku)           # true
has_description = Map.has_key?(product, :description)  # false

# Get all keys
keys = Map.keys(product)       # [:category, :price, :sku] (order may vary)

# Get all values
values = Map.values(product)   # ["electronics", 1299.99, "LAP-001"] (order may vary)

Testing in IEx:

iex> product = %{sku: "LAP-001", category: "electronics", price: 1299.99}
%{category: "electronics", price: 1299.99, sku: "LAP-001"}

iex> map_size(product)
3

iex> Map.has_key?(product, :sku)
true

iex> Map.keys(product)
[:category, :price, :sku]

Creating and Updating Maps

Creating Maps

# Literal syntax
task = %{title: "Deploy API", priority: :urgent}

# From keyword lists
from_keywords = Map.new([brand: "Tesla", model: "Model 3"])

# From lists of tuples
from_tuples = Map.new([{"sensor_id", "TEMP-001"}, {"location", "Server Room"}])

# With Enum.into
from_enum = ["a", "b", "c"] |> Enum.with_index() |> Enum.into(%{})
# Results in %{"a" => 0, "b" => 1, "c" => 2}

# Using Map.put to build gradually
empty = %{}
step1 = Map.put(empty, :event, "Tech Conference 2024")
step2 = Map.put(step1, :capacity, 500)
# Results in %{capacity: 500, event: "Tech Conference 2024"}

Testing in IEx:

iex> Map.new([brand: "Tesla", model: "Model 3"])
%{brand: "Tesla", model: "Model 3"}

iex> ["a", "b", "c"] |> Enum.with_index() |> Enum.into(%{})
%{"a" => 0, "b" => 1, "c" => 2}

iex> %{} |> Map.put(:event, "Tech Conference 2024") |> Map.put(:capacity, 500)
%{capacity: 500, event: "Tech Conference 2024"}

Updating Maps

Maps are immutable, so "updating" creates new maps:

original = %{sensor_id: "TEMP-001", reading: 23.5, location: "Server Room"}

# Update existing key
with_new_reading = %{original | reading: 24.1}
# Results in %{location: "Server Room", reading: 24.1, sensor_id: "TEMP-001"}

# Add new key (use Map.put for new keys)
with_timestamp = Map.put(original, :timestamp, ~U[2024-01-15 14:30:00Z])

# Update multiple keys
updated = %{original | reading: 24.1, location: "Data Center"}

# Conditional update with Map.put_new (only if key doesn't exist)
maybe_added = Map.put_new(original, :unit, "celsius")
already_exists = Map.put_new(original, :sensor_id, "TEMP-002")  # Won't change sensor_id

Testing in IEx:

iex> original = %{sensor_id: "TEMP-001", reading: 23.5, location: "Server Room"}
%{location: "Server Room", reading: 23.5, sensor_id: "TEMP-001"}

iex> %{original | reading: 24.1}
%{location: "Server Room", reading: 24.1, sensor_id: "TEMP-001"}

iex> Map.put(original, :timestamp, ~U[2024-01-15 14:30:00Z])
%{location: "Server Room", reading: 23.5, sensor_id: "TEMP-001", timestamp: ~U[2024-01-15 14:30:00Z]}

iex> Map.put_new(original, :unit, "celsius")
%{location: "Server Room", reading: 23.5, sensor_id: "TEMP-001", unit: "celsius"}

iex> original
%{location: "Server Room", reading: 23.5, sensor_id: "TEMP-001"}

Advanced Update Patterns

defmodule InventoryUpdater do
  # Update with function
  def increment_stock(product) do
    Map.update(product, :stock_count, 0, fn current_stock -> current_stock + 1 end)
  end

  # Update existing key, or use default if key doesn't exist
  def add_view_count(product) do
    Map.update(product, :view_count, 1, fn count -> count + 1 end)
  end

  # Merge maps (right side wins conflicts)
  def merge_product_data(product, updates) do
    Map.merge(product, updates)
  end

  # Merge with custom conflict resolution
  def smart_merge(product, updates) do
    Map.merge(product, updates, fn _key, old_val, new_val ->
      if new_val != nil, do: new_val, else: old_val
    end)
  end

  # Delete keys
  def remove_internal_data(product) do
    Map.drop(product, [:cost_price, :supplier_id])
  end
end

Testing in IEx:

iex> product = %{sku: "LAP-001", stock_count: 10}
%{sku: "LAP-001", stock_count: 10}

iex> InventoryUpdater.increment_stock(product)
%{sku: "LAP-001", stock_count: 11}

iex> InventoryUpdater.add_view_count(product)
%{sku: "LAP-001", stock_count: 10, view_count: 1}

iex> updates = %{stock_count: 15, location: "Warehouse A"}
%{location: "Warehouse A", stock_count: 15}

iex> InventoryUpdater.merge_product_data(product, updates)
%{location: "Warehouse A", sku: "LAP-001", stock_count: 15}

Accessing Map Values

Basic Access Methods

order = %{id: "ORD-2024-001", total: 299.99, status: :shipped}

# Bracket access (returns nil if key doesn't exist)
order_id = order[:id]          # "ORD-2024-001"
missing = order[:tracking]      # nil

# Map.get with default
total = Map.get(order, :total)                    # 299.99
tracking = Map.get(order, :tracking, "N/A")       # "N/A"

# Dot access (only for atom keys, raises if key doesn't exist)
status_dot = order.status        # :shipped
# order.tracking               # ** (KeyError) key :tracking not found

# Map.fetch (returns {:ok, value} or :error)
{:ok, total} = Map.fetch(order, :total)       # {:ok, 299.99}
:error = Map.fetch(order, :tracking)          # :error

# Map.fetch! (raises if key doesn't exist)
status_bang = Map.fetch!(order, :status)     # :shipped
# Map.fetch!(order, :tracking)              # ** (KeyError)

Testing in IEx:

iex> order = %{id: "ORD-2024-001", total: 299.99, status: :shipped}
%{id: "ORD-2024-001", status: :shipped, total: 299.99}

iex> order[:id]
"ORD-2024-001"

iex> order[:tracking]
nil

iex> Map.get(order, :tracking, "N/A")
"N/A"

iex> order.status
:shipped

iex> Map.fetch(order, :total)
{:ok, 299.99}

iex> Map.fetch(order, :tracking)
:error

Safe Access Patterns

defmodule SafeAccess do
  # Safe tracking extraction
  def get_tracking(order) do
    case Map.fetch(order, :tracking_number) do
      {:ok, tracking} -> {:ok, tracking}
      :error -> {:error, :tracking_not_found}
    end
  end

  # With default transformation
  def get_display_status(order) do
    order
    |> Map.get(:custom_status)
    |> case do
      nil -> Map.get(order, :status, :unknown)
      custom_status -> custom_status
    end
  end

  # Multiple key access with validation
  def get_order_summary(order) do
    with {:ok, id} <- Map.fetch(order, :id),
         {:ok, total} <- Map.fetch(order, :total) do
      {:ok, "Order #{id}: $#{total}"}
    else
      :error -> {:error, :incomplete_order_info}
    end
  end
end

Testing in IEx:

iex> order = %{id: "ORD-001", total: 299.99, tracking_number: "TRK-123"}
%{id: "ORD-001", total: 299.99, tracking_number: "TRK-123"}

iex> SafeAccess.get_tracking(order)
{:ok, "TRK-123"}

iex> SafeAccess.get_display_status(order)
:unknown

iex> incomplete = %{id: "ORD-002"}
%{id: "ORD-002"}

iex> SafeAccess.get_order_summary(incomplete)
{:error, :incomplete_order_info}

iex> SafeAccess.get_order_summary(order)
{:ok, "Order ORD-001: $299.99"}

Pattern Matching with Maps

Pattern matching with maps is one of the most powerful features for destructuring and validating data:

Basic Pattern Matching

defmodule MapPatterns do
  # Match specific keys
  def format_event(%{title: title}) do
    "Event: #{title}"
  end

  # Match multiple keys
  def event_summary(%{title: title, capacity: capacity}) do
    "#{title} - Max capacity: #{capacity} attendees"
  end

  # Match with guards
  def check_large_event(%{capacity: capacity} = event) when capacity >= 1000 do
    {:large_event, event}
  end
  def check_large_event(event) do
    {:small_event, event}
  end

  # Partial matching (map can have more keys)
  def get_event_id(%{id: id}) do
    id
  end

  # Match nested maps
  def get_venue_city(%{venue: %{city: city}}) do
    city
  end
  def get_venue_city(_), do: "Unknown"
end

Testing in IEx:

iex> event = %{title: "Tech Conference 2024", capacity: 500, location: "Convention Center"}
%{capacity: 500, location: "Convention Center", title: "Tech Conference 2024"}

iex> MapPatterns.format_event(event)
"Event: Tech Conference 2024"

iex> MapPatterns.event_summary(event)
"Tech Conference 2024 - Max capacity: 500 attendees"

iex> MapPatterns.check_large_event(event)
{:small_event, %{capacity: 500, location: "Convention Center", title: "Tech Conference 2024"}}

iex> event_with_id = %{id: 789, title: "DevOps Summit", category: :technical}
%{category: :technical, id: 789, title: "DevOps Summit"}

iex> MapPatterns.get_event_id(event_with_id)
789

Advanced Pattern Matching

defmodule AdvancedPatterns do
  # Match and extract with variable capture
  def process_task(%{title: title, tags: tags} = task) do
    if :urgent in tags do
      {:priority_task, title, task}
    else
      {:regular_task, title, task}
    end
  end

  # Pattern match in function heads for different cases
  def handle_api_response(%{"status" => "success", "data" => data}) do
    {:ok, data}
  end

  def handle_api_response(%{"status" => "error", "message" => message}) do
    {:error, message}
  end

  def handle_api_response(response) do
    {:unknown, response}
  end

  # Match with pin operator (match against existing variable)
  def find_task_by_priority(tasks, target_priority) do
    Enum.find(tasks, fn %{priority: ^target_priority} -> true; _ -> false end)
  end

  # Complex nested pattern matching
  def extract_sensor_coordinates(%{device: %{location: {lat, lon}}}) do
    {:ok, lat, lon}
  end
  def extract_sensor_coordinates(_), do: {:error, :no_coordinates}
end

Testing in IEx:

iex> urgent_task = %{title: "Fix production bug", tags: [:urgent, :backend]}
%{tags: [:urgent, :backend], title: "Fix production bug"}

iex> AdvancedPatterns.process_task(urgent_task)
{:priority_task, "Fix production bug", %{tags: [:urgent, :backend], title: "Fix production bug"}}

iex> api_success = %{"status" => "success", "data" => ["sensor1", "sensor2"]}
%{"data" => ["sensor1", "sensor2"], "status" => "success"}

iex> AdvancedPatterns.handle_api_response(api_success)
{:ok, ["sensor1", "sensor2"]}

iex> tasks = [%{title: "Deploy API", priority: :high}, %{title: "Update docs", priority: :low}]
[%{priority: :high, title: "Deploy API"}, %{priority: :low, title: "Update docs"}]

iex> AdvancedPatterns.find_task_by_priority(tasks, :high)
%{priority: :high, title: "Deploy API"}

Pattern Matching in case Expressions

defmodule ResponseProcessor do
  def process_api_response(response) do
    case response do
      %{status: 200, body: %{"data" => data}} ->
        {:success, data}

      %{status: 404} ->
        {:error, :not_found}

      %{status: status} when status >= 500 ->
        {:error, :server_error}

      %{status: status, body: %{"error" => message}} ->
        {:error, "HTTP #{status}: #{message}"}

      %{error: reason} ->
        {:error, reason}

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

  def categorize_user(user) do
    case user do
      %{age: age, role: :admin} when age >= 21 ->
        :senior_admin

      %{age: age, role: :admin} when age < 21 ->
        :junior_admin

      %{age: age, subscription: :premium} when age >= 18 ->
        :premium_adult

      %{age: age} when age >= 18 ->
        :regular_adult

      %{age: age} when age < 18 ->
        :minor

      _ ->
        :unknown
    end
  end
end

Testing in IEx:

iex> good_response = %{status: 200, body: %{"data" => ["item1", "item2"]}}
%{body: %{"data" => ["item1", "item2"]}, status: 200}

iex> ResponseProcessor.process_api_response(good_response)
{:success, ["item1", "item2"]}

iex> not_found = %{status: 404, body: %{"error" => "Not found"}}
%{body: %{"error" => "Not found"}, status: 404}

iex> ResponseProcessor.process_api_response(not_found)
{:error, :not_found}

iex> junior_admin = %{name: "Sofia", age: 19, role: :admin}
%{age: 19, name: "Sofia", role: :admin}

iex> ResponseProcessor.categorize_user(junior_admin)
:junior_admin

iex> regular_dev = %{name: "Marcus", age: 25, role: :developer}
%{age: 25, name: "Marcus", role: :developer}

iex> ResponseProcessor.categorize_user(regular_dev)
:regular_adult

Essential Map Functions

Basic Map Operations

base_config = %{host: "localhost", port: 4000, ssl: true}

# Adding and updating
updated = Map.put(base_config, :timeout, 5000)
port_updated = Map.put(base_config, :port, 8080)

# Conditional operations
maybe_added = Map.put_new(base_config, :retries, 3)
wont_change = Map.put_new(base_config, :host, "remote.server.com")  # host already exists

# Removing keys
without_ssl = Map.delete(base_config, :ssl)
clean_config = Map.drop(base_config, [:ssl, :port])

# Taking specific keys
subset = Map.take(base_config, [:host, :port])

Testing in IEx:

iex> base_config = %{host: "localhost", port: 4000, ssl: true}
%{host: "localhost", port: 4000, ssl: true}

iex> Map.put(base_config, :timeout, 5000)
%{host: "localhost", port: 4000, ssl: true, timeout: 5000}

iex> Map.delete(base_config, :ssl)
%{host: "localhost", port: 4000}

iex> Map.take(base_config, [:host, :port])
%{host: "localhost", port: 4000}

Transformation Functions

defmodule MapTransformations do
  # Transform all values
  def increment_numbers(map) do
    Map.new(map, fn {key, value} ->
      new_value = if is_number(value), do: value + 1, else: value
      {key, new_value}
    end)
  end

  # Filter by condition
  def filter_adults(users) do
    users
    |> Enum.filter(fn {_id, %{age: age}} -> age >= 18 end)
    |> Map.new()
  end

  # Transform keys
  def stringify_keys(map) do
    Map.new(map, fn {key, value} -> {to_string(key), value} end)
  end

  def atomize_keys(map) do
    Map.new(map, fn {key, value} -> {String.to_atom(key), value} end)
  end

  # Combine multiple maps
  def merge_user_data(base_data, profile_data, preferences) do
    base_data
    |> Map.merge(profile_data)
    |> Map.merge(preferences)
  end
end

Testing in IEx:

iex> test_map = %{temperature: 23, status: "active", score: 85}
%{score: 85, status: "active", temperature: 23}

iex> MapTransformations.increment_numbers(test_map)
%{score: 86, status: "active", temperature: 24}

iex> string_map = %{"sensor_type" => "temperature", "reading" => "23.5"}
%{"reading" => "23.5", "sensor_type" => "temperature"}

iex> MapTransformations.atomize_keys(string_map)
%{reading: "23.5", sensor_type: "temperature"}

iex> MapTransformations.stringify_keys(%{sensor_type: :temperature, reading: 23.5})
%{"reading" => 23.5, "sensor_type" => "temperature"}

Working with Collections of Maps

defmodule MapCollections do
  # Process list of product maps
  def get_names(products) do
    Enum.map(products, &Map.get(&1, :name))
  end

  # Filter and transform
  def get_expensive_skus(products) do
    products
    |> Enum.filter(fn %{price: price} -> price >= 1000 end)
    |> Enum.map(fn %{sku: sku} -> sku end)
  end

  # Group by attribute
  def group_by_price_range(products) do
    products
    |> Enum.group_by(fn %{price: price} ->
      cond do
        price < 100 -> :budget
        price < 1000 -> :mid_range
        true -> :premium
      end
    end)
  end

  # Calculate statistics
  def calculate_average_price(products) do
    prices = Enum.map(products, &Map.get(&1, :price))
    Enum.sum(prices) / length(prices)
  end

  # Find by criteria
  def find_premium_product(products) do
    Enum.find(products, fn product ->
      Map.get(product, :category) == :premium
    end)
  end
end

Testing in IEx:

iex> products = [%{name: "Laptop", price: 1299.99, sku: "LAP-001", category: :electronics}, %{name: "Mouse", price: 29.99, sku: "MOU-001", category: :accessories}, %{name: "Monitor", price: 899.99, sku: "MON-001", category: :premium}]
[%{category: :electronics, name: "Laptop", price: 1299.99, sku: "LAP-001"}, %{category: :accessories, name: "Mouse", price: 29.99, sku: "MOU-001"}, %{category: :premium, name: "Monitor", price: 899.99, sku: "MON-001"}]

iex> MapCollections.get_names(products)
["Laptop", "Mouse", "Monitor"]

iex> MapCollections.get_expensive_skus(products)
["LAP-001"]

iex> MapCollections.find_premium_product(products)
%{category: :premium, name: "Monitor", price: 899.99, sku: "MON-001"}

Working with Nested Maps

Nested maps are common when dealing with complex data structures, APIs, and configurations:

Creating Nested Maps

# Server configuration with nested monitoring and security
server_config = %{
  id: "SRV-001",
  hostname: "api.service.com",
  region: "us-east-1",
  networking: %{
    port: 443,
    protocol: "https",
    load_balancer: "ALB-001",
    coordinates: %{datacenter: "DC-1", rack: "R-15"}
  },
  monitoring: %{
    alerts: "enabled",
    metrics: %{
      cpu: true,
      memory: true,
      disk: false
    },
    retention: "30d"
  }
}

# API response with nested data
api_response = %{
  status: "success",
  data: %{
    sensors: [
      %{id: "TEMP-001", type: "temperature"},
      %{id: "HUMID-002", type: "humidity"}
    ],
    metadata: %{
      total: 2,
      page: 1,
      per_page: 10
    }
  }
}

Accessing Nested Values

defmodule NestedAccess do
  # Safe nested access
  def get_user_city(user) do
    user
    |> Map.get(:address, %{})
    |> Map.get(:city)
  end

  # Deep access with get_in
  def get_notification_preference(user, type) do
    get_in(user, [:preferences, :notifications, type])
  end

  # Pattern matching for nested extraction
  def extract_coordinates(%{address: %{coordinates: coords}}) do
    {:ok, coords}
  end
  def extract_coordinates(_), do: {:error, :no_coordinates}

  # Multiple level extraction
  def get_contact_info(user) do
    with {:ok, name} <- Map.fetch(user, :name),
         {:ok, email} <- Map.fetch(user, :email),
         city <- get_user_city(user) do
      %{name: name, email: email, city: city}
    end
  end
end

Testing in IEx:

iex> user_profile = %{name: "Sofia", address: %{city: "Barcelona", state: "Catalonia"}, preferences: %{notifications: %{email: true, sms: false}}}
%{address: %{city: "Barcelona", state: "Catalonia"}, name: "Sofia", preferences: %{notifications: %{email: true, sms: false}}}

iex> NestedAccess.get_user_city(user_profile)
"Barcelona"

iex> NestedAccess.get_notification_preference(user_profile, :email)
true

iex> get_in(user_profile, [:preferences, :notifications, :sms])
false

iex> get_in(user_profile, [:preferences, :notifications, :push])
nil

Updating Nested Maps

defmodule NestedUpdates do
  # Update nested value with put_in
  def update_city(user, new_city) do
    put_in(user, [:address, :city], new_city)
  end

  # Update with function using update_in
  def increment_login_count(user) do
    update_in(user, [:stats, :login_count], fn
      nil -> 1
      count -> count + 1
    end)
  end

  # Safe nested update (create path if doesn't exist)
  def enable_notification(user, type) do
    user
    |> put_in([:preferences], Map.get(user, :preferences, %{}))
    |> put_in([:preferences, :notifications],
              get_in(user, [:preferences, :notifications]) || %{})
    |> put_in([:preferences, :notifications, type], true)
  end

  # Complex nested transformation
  def normalize_address(user) do
    update_in(user, [:address], fn address ->
      address
      |> Map.update(:city, "", &String.upcase/1)
      |> Map.update(:state, "", &String.upcase/1)
    end)
  end
end

Testing in IEx:

iex> user_data = %{name: "Marcus", address: %{city: "madrid", state: "madrid"}}
%{address: %{city: "madrid", state: "madrid"}, name: "Marcus"}

iex> NestedUpdates.update_city(user_data, "Barcelona")
%{address: %{city: "Barcelona", state: "madrid"}, name: "Marcus"}

iex> NestedUpdates.normalize_address(user_data)
%{address: %{city: "MADRID", state: "MADRID"}, name: "Marcus"}

iex> simple_user = %{name: "Elena"}
%{name: "Elena"}

iex> NestedUpdates.enable_notification(simple_user, :email)
%{name: "Elena", preferences: %{notifications: %{email: true}}}

Complex Nested Operations

defmodule ComplexNested do
  # Merge nested maps intelligently
  def deep_merge(map1, map2) do
    Map.merge(map1, map2, fn _key, val1, val2 ->
      if is_map(val1) and is_map(val2) do
        deep_merge(val1, val2)
      else
        val2
      end
    end)
  end

  # Flatten nested structure
  def flatten_user(user) do
    base = Map.take(user, [:id, :name, :email])
    address = Map.get(user, :address, %{})

    base
    |> Map.put(:city, Map.get(address, :city))
    |> Map.put(:state, Map.get(address, :state))
    |> Map.put(:zip, Map.get(address, :zip))
  end

  # Transform nested collections
  def transform_nested_users(response) do
    update_in(response, [:data, :users], fn users ->
      Enum.map(users, fn user ->
        Map.update(user, :name, "", &String.upcase/1)
      end)
    end)
  end
end

Testing in IEx:

iex> map1 = %{a: 1, b: %{c: 2, d: 3}}
%{a: 1, b: %{c: 2, d: 3}}

iex> map2 = %{a: 10, b: %{d: 30, e: 40}}
%{a: 10, b: %{d: 30, e: 40}}

iex> ComplexNested.deep_merge(map1, map2)
%{a: 10, b: %{c: 2, d: 30, e: 40}}

iex> user_with_address = %{id: "USR-001", name: "Viktor", email: "viktor@company.com", address: %{city: "Stockholm", state: "Stockholm", zip: "11122"}}
%{address: %{city: "Stockholm", state: "Stockholm", zip: "11122"}, email: "viktor@company.com", id: "USR-001", name: "Viktor"}

iex> ComplexNested.flatten_user(user_with_address)
%{city: "Stockholm", email: "viktor@company.com", id: "USR-001", name: "Viktor", state: "Stockholm", zip: "11122"}

Maps vs Other Data Structures

Understanding when to choose maps over other data structures is crucial for writing idiomatic Elixir:

Maps vs Keyword Lists

# Use keyword lists for:
options = [host: "localhost", port: 4000, ssl: true]  # Function options
config = [debug: true, log_level: :info]              # Small configs
ecto_query = from(u in User, where: u.age > 18)       # DSL parameters

# Use maps for:
employee_data = %{id: 1001, role: "developer", department: "engineering"}  # Structured data
cache = %{"session:1" => %{status: "active"}, "session:2" => %{status: "expired"}} # Fast lookups
response = %{status: :ok, data: [...], message: "Success"}          # Complex data

# Conversion between them
keyword_to_map = Enum.into(options, %{})    # %{host: "localhost", port: 4000, ssl: true}
map_to_keyword = Enum.into(user_data, [])   # Not recommended - loses map benefits

Maps vs Tuples

# Use tuples for:
coordinate = {10, 20}                    # Fixed position data
result = {:ok, "success"}                # Tagged return values
version = {1, 2, 3}                      # Fixed number of elements

# Use maps for:
point = %{x: 10, y: 20}                  # Named fields
api_result = %{status: :ok, data: "success", meta: %{}}  # Flexible structure
task = %{id: 42, title: "Deploy API", priority: :urgent}  # Record-like data

# When you need to add/remove fields, maps are better:
extended_point = Map.put(point, :z, 30)  # Easy to extend
# Can't easily extend a tuple: {10, 20} → {10, 20, 30} requires full reconstruction

Maps vs Structs

# Maps: Flexible, dynamic structure
product_map = %{sku: "LAP-001", price: 1299.99, category: "electronics"}
extended_product = Map.put(product_map, :warranty, "2 years")  # Easy to extend

# Structs: Fixed structure, type safety
defmodule Product do
  defstruct [:sku, :price, :category]
end

product_struct = %Product{sku: "LAP-001", price: 1299.99, category: "electronics"}
# product_struct.warranty  # This would raise an error - warranty not defined

# Choose maps when:
# - Working with external data (JSON, APIs)
# - Structure might change
# - Need flexible key-value storage

# Choose structs when:
# - Modeling domain entities
# - Want compile-time guarantees
# - Need pattern matching on type

Testing in IEx:

iex> options = [host: "localhost", port: 4000]
[host: "localhost", port: 4000]

iex> Enum.into(options, %{})
%{host: "localhost", port: 4000}

iex> point_tuple = {10, 20}
{10, 20}

iex> point_map = %{x: 10, y: 20}
%{x: 10, y: 20}

iex> Map.put(point_map, :z, 30)
%{x: 10, y: 20, z: 30}

Real World Applications

API Response Handling

defmodule APIHandler do
  # Process weather API response
  def process_weather_data(response) do
    case response do
      %{"temperature" => temp, "humidity" => humidity, "city" => city} ->
        {:ok, %{
          temperature: temp,
          humidity: humidity,
          location: city,
          wind_speed: Map.get(response, "wind_speed", 0),
          pressure: Map.get(response, "pressure", 0)
        }}

      %{"error" => "City not found"} ->
        {:error, :location_not_found}

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

  # Handle paginated API responses
  def extract_paginated_data(%{"data" => items, "pagination" => pagination}) do
    %{
      items: items,
      current_page: Map.get(pagination, "page", 1),
      total_pages: Map.get(pagination, "pages", 1),
      total_items: Map.get(pagination, "total", 0),
      has_next: Map.get(pagination, "has_next", false)
    }
  end
end

Configuration Management

defmodule AppConfig do
  # Application configuration with defaults
  def load_config(env \\ :dev) do
    base_config = %{
      app_name: "MyApp",
      port: 4000,
      database: %{
        adapter: "postgres",
        pool_size: 10
      },
      features: %{
        analytics: false,
        caching: true
      }
    }

    env_config = load_env_config(env)
    deep_merge_config(base_config, env_config)
  end

  # Environment-specific overrides
  defp load_env_config(:prod) do
    %{
      port: 80,
      database: %{
        pool_size: 20,
        timeout: 30_000
      },
      features: %{
        analytics: true,
        caching: true
      }
    }
  end

  defp load_env_config(:test) do
    %{
      database: %{
        adapter: "sqlite",
        database: ":memory:"
      },
      features: %{
        analytics: false,
        caching: false
      }
    }
  end

  defp load_env_config(_), do: %{}

  defp deep_merge_config(base, override) do
    Map.merge(base, override, fn _key, base_val, override_val ->
      if is_map(base_val) and is_map(override_val) do
        deep_merge_config(base_val, override_val)
      else
        override_val
      end
    end)
  end
end

Data Transformation Pipeline

defmodule DataPipeline do
  # Transform raw CSV data into structured format
  def process_user_csv(csv_rows) do
    csv_rows
    |> Enum.map(&parse_csv_row/1)
    |> Enum.filter(&valid_user?/1)
    |> Enum.map(&normalize_user/1)
    |> Enum.group_by(& &1.department)
  end

  defp parse_csv_row([name, email, age, department, salary]) do
    %{
      name: String.trim(name),
      email: String.downcase(String.trim(email)),
      age: String.to_integer(age),
      department: String.trim(department),
      salary: String.to_float(salary)
    }
  end

  defp valid_user?(%{email: email, age: age}) do
    String.contains?(email, "@") and age >= 18
  end

  defp normalize_user(%{name: name, department: dept} = user) do
    %{user |
      name: String.split(name) |> Enum.map(&String.capitalize/1) |> Enum.join(" "),
      department: String.downcase(dept)
    }
  end

  # Build user analytics
  def calculate_department_stats(users_by_dept) do
    Map.new(users_by_dept, fn {dept, users} ->
      stats = %{
        count: length(users),
        avg_age: average_age(users),
        avg_salary: average_salary(users),
        age_range: age_range(users)
      }
      {dept, stats}
    end)
  end

  defp average_age(users) do
    (users |> Enum.map(& &1.age) |> Enum.sum()) / length(users)
  end

  defp average_salary(users) do
    (users |> Enum.map(& &1.salary) |> Enum.sum()) / length(users)
  end

  defp age_range(users) do
    ages = Enum.map(users, & &1.age)
    %{min: Enum.min(ages), max: Enum.max(ages)}
  end
end

Testing in IEx:

iex> weather_response = %{"temperature" => 23.5, "humidity" => 65, "city" => "Barcelona", "wind_speed" => 12.3}
%{"city" => "Barcelona", "humidity" => 65, "temperature" => 23.5, "wind_speed" => 12.3}

iex> APIHandler.process_weather_data(weather_response)
{:ok, %{humidity: 65, location: "Barcelona", pressure: 0, temperature: 23.5, wind_speed: 12.3}}

iex> AppConfig.load_config(:prod)
%{app_name: "MyApp", database: %{adapter: "postgres", pool_size: 20, timeout: 30000}, features: %{analytics: true, caching: true}, port: 80}

Best Practices

Do's and Don'ts

✅ DO: Use atom keys for internal data

# Good - fast access, clear intent
employee = %{name: "Sofia", experience: 5, role: :lead}

✅ DO: Use string keys for external data

# Good - matches JSON APIs, external sources
api_data = %{"user_id" => 123, "status" => "active"}

✅ DO: Pattern match to extract needed data

# Good - clear and safe
def get_user_email(%{email: email}), do: {:ok, email}
def get_user_email(_), do: {:error, :no_email}

✅ DO: Use Map.get with defaults for optional values

# Good - safe with sensible defaults
display_name = Map.get(user, :display_name, user.name)

❌ DON'T: Mix atom and string keys unnecessarily

# Confusing - pick one style
mixed = %{status: :active, "priority" => "high"}

❌ DON'T: Use maps for ordered data

# Bad - maps don't guarantee order
sequence = %{1 => "first", 2 => "second", 3 => "third"}

# Good - use lists for ordered data
sequence = ["first", "second", "third"]

Performance Considerations

defmodule PerformanceTips do
  # Fast: Direct key access
  def get_name_fast(%{name: name}), do: name

  # Slower: Function call
  def get_name_slow(user), do: Map.get(user, :name)

  # Fast: Update existing key
  def update_age_fast(user, new_age), do: %{user | age: new_age}

  # Slower: Map.put (but works for new keys too)
  def update_age_slower(user, new_age), do: Map.put(user, :age, new_age)

  # Good: Batch updates
  def update_user_info(user, updates) do
    Map.merge(user, updates)
  end

  # Less efficient: Individual updates
  def update_user_info_slow(user, name, age, email) do
    user
    |> Map.put(:name, name)
    |> Map.put(:age, age)
    |> Map.put(:email, email)
  end
end

Error Handling Patterns

defmodule SafeMapOperations do
  # Safe extraction with defaults
  def safe_get(map, key, default \\ nil) do
    Map.get(map, key, default)
  end

  # Validation before processing
  def process_user(user_data) do
    with {:ok, user} <- validate_required_fields(user_data),
         {:ok, normalized} <- normalize_user_data(user) do
      {:ok, normalized}
    end
  end

  defp validate_required_fields(data) do
    required = [:name, :email, :age]

    case Enum.find(required, &(!Map.has_key?(data, &1))) do
      nil -> {:ok, data}
      missing_key -> {:error, {:missing_field, missing_key}}
    end
  end

  defp normalize_user_data(user) do
    try do
      normalized = %{
        name: String.trim(user.name),
        email: String.downcase(user.email),
        age: ensure_integer(user.age)
      }
      {:ok, normalized}
    rescue
      _ -> {:error, :normalization_failed}
    end
  end

  defp ensure_integer(value) when is_integer(value), do: value
  defp ensure_integer(value) when is_binary(value), do: String.to_integer(value)
  defp ensure_integer(_), do: raise("Invalid integer value")
end

Testing in IEx:

iex> good_data = %{name: " Elena Martinez ", email: "ELENA@COMPANY.COM", age: "28"}
%{age: "28", email: "ELENA@COMPANY.COM", name: " Elena Martinez "}

iex> SafeMapOperations.process_user(good_data)
{:ok, %{age: 28, email: "elena@company.com", name: "Elena Martinez"}}

iex> bad_data = %{name: "Viktor", email: "viktor@company.com"}
%{email: "viktor@company.com", name: "Viktor"}

iex> SafeMapOperations.process_user(bad_data)
{:error, {:missing_field, :age}}

Conclusion

Maps are one of the most versatile and powerful data structures in Elixir, providing the foundation for modeling complex data in functional applications. In this article, we've explored:

How maps work internally with key-value pairs
Creating and updating maps with various techniques
Accessing values safely with different approaches
Pattern matching for powerful data extraction
Essential map functions for transformation and manipulation
Working with nested maps for complex data structures
Choosing between maps and other data structures
Real-world applications in APIs, configuration, and data processing
Best practices for performance and error handling

Key takeaways:

Maps excel at key-value storage with fast lookups
Use atom keys for internal data, string keys for external data
Pattern matching makes map code elegant and safe
Nested maps handle complex hierarchical data well
Choose maps for flexible, dynamic data structures
Combine maps with other data structures for optimal solutions
Always consider immutability when updating maps

Maps form the backbone of many Elixir applications, from web servers handling JSON to configuration systems managing complex settings. Master maps, and you'll have the tools to model almost any kind of data your applications need.

Next Steps

With a solid understanding of maps, you're ready to explore Keyword Lists in Elixir. Keyword lists provide an ordered collection of key-value pairs that's perfect for function options, small configurations, and DSL parameters.

In the next article, we'll explore:

Creating and manipulating keyword lists
When to choose keyword lists over maps
Pattern matching with keyword lists
Function options and configuration patterns
Working with duplicate keys
Performance characteristics and trade-offs

Keyword lists complete our journey through Elixir's core data structures, giving you all the tools needed to choose the right structure for any situation!

Learning Elixir: Tuples

João Paulo Abreu — Sat, 19 Jul 2025 12:52:36 +0000

Tuples are like standardized forms where each field has a fixed position and specific meaning. In a user registration form, the first field is always the type (:user), the second is the ID, the third is the name, and the fourth is the email. You can't add extra fields or change the order - the structure is fixed and each position has its well-defined purpose. Think of {:user, 123, "Alice", "alice@example.com"} as a structured record where each position tells a specific part of the story. Once created, tuples keep their size and elements in their exact positions, making them perfect for structured data where order and position matter. In this article, we'll explore how tuples work, when to use them, and the patterns that make them indispensable in Elixir programming.

Note: The examples in this article use Elixir 1.18.3. While most operations should work across different versions, some functionality might vary.

Introduction
Understanding Tuples
Creating and Accessing Tuples
Pattern Matching with Tuples
Common Tuple Patterns
Tuples vs Lists
Working with Nested Tuples
Best Practices
Conclusion
Further Reading
Next Steps

Introduction

Tuples are one of the most fundamental and elegant data structures in Elixir. They serve as the building blocks for many common patterns you'll see throughout Elixir code, from simple coordinate pairs to complex return values that carry both data and status information.

What makes tuples special:

Fixed size: Once created, tuples cannot grow or shrink
Random access: You can access any element by its position
Ordered collection: Elements have specific positions with distinct meanings
Heterogeneous: Each element can be a different data type
Immutable: Like all Elixir data structures, tuples cannot be modified

Think of tuples as structured forms where each position matters:

An address form: {"123 Main St", "Springfield", "IL", "62701"} (street, city, state, zip)
A user registration: {:user, 123, "Alice", "alice@example.com"} (type, ID, name, email)
Function results: {:ok, "Success message"} or {:error, "Something went wrong"} (status, data)

Let's explore how tuples work and why they're so useful in Elixir!

Understanding Tuples

The Basics

A tuple is a collection of elements wrapped in curly braces {}, where each position has a specific meaning:

# Empty tuple
empty = {}

# Single element tuple
single = {42}

# Two elements (pair)
coordinate = {3, 4}

# Three elements (triple)
person = {"Alice", 25, :active}

# Mixed data types
mixed = {:ok, %{id: 1, name: "Bob"}, ["tag1", "tag2"]}

Basic Operations

tuple = {:user, 123, "Alice", "alice@example.com"}

# Access by index (0-based)
first = elem(tuple, 0)    # :user
second = elem(tuple, 1)   # 123
third = elem(tuple, 2)    # "Alice"

# Get tuple size
size = tuple_size(tuple)  # 4

Testing in IEx:

iex> tuple = {:user, 123, "Alice", "alice@example.com"}
{:user, 123, "Alice", "alice@example.com"}

iex> elem(tuple, 0)
:user

iex> elem(tuple, 2)
"Alice"

iex> tuple_size(tuple)
4

Immutability and Updates

Since tuples are immutable, "updating" a tuple creates a new one:

original = {:user, 123, "Alice"}

# Update the name (position 2) - creates a new tuple
updated = put_elem(original, 2, "Alice Smith")
# Result: {:user, 123, "Alice Smith"}

# Original tuple is unchanged
IO.inspect(original)  # {:user, 123, "Alice"}
IO.inspect(updated)   # {:user, 123, "Alice Smith"}

Testing in IEx:

iex> original = {:user, 123, "Alice"}
{:user, 123, "Alice"}

iex> updated = put_elem(original, 2, "Alice Smith")
{:user, 123, "Alice Smith"}

iex> original
{:user, 123, "Alice"}

Creating and Accessing Tuples

Creation Patterns

# Coordinate pairs
point = {10, 20}
point3d = {10, 20, 30}

# Status with data
success = {:ok, "File saved successfully"}
error = {:error, "File not found"}

# Database-style records
user = {:user, 1, "john", "john@example.com", :active}
product = {:product, 101, "Laptop", 999.99, 10}

# Time and date information
time_point = {:datetime, 2024, 1, 15, 14, 30, 0}

# Complex nested data
response = {:ok, %{users: [1, 2, 3], total: 3}}

Accessing Elements

user_record = {:user, 42, "Alice", "alice@example.com"}

# Using elem/2 function
user_id = elem(user_record, 1)      # 42
username = elem(user_record, 2)     # "Alice"
email = elem(user_record, 3)        # "alice@example.com"

# Check tuple size
size = tuple_size(user_record)      # 4

# Pattern matching (more idiomatic)
{:user, id, name, email} = user_record
# Now you have: id = 42, name = "Alice", email = "alice@example.com"

Testing in IEx:

iex> user_record = {:user, 42, "Alice", "alice@example.com"}
{:user, 42, "Alice", "alice@example.com"}

iex> elem(user_record, 1)
42

iex> {type, id, name, email} = user_record
{:user, 42, "Alice", "alice@example.com"}

iex> name
"Alice"

iex> id
42

Pattern Matching with Tuples

Pattern matching is where tuples really shine. They allow you to destructure data elegantly:

Basic Pattern Matching

defmodule TuplePatterns do
  # Match specific tuple structures
  def handle_result({:ok, data}) do
    "Success! Got: #{inspect(data)}"
  end

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

  def handle_result(_) do
    "Unknown result format"
  end

  # Extract coordinates
  def distance_from_origin({x, y}) do
    :math.sqrt(x * x + y * y)
  end

  # Match and extract user info
  def greet_user({:user, _id, name, _email}) do
    "Hello, #{name}!"
  end

  def greet_user(_), do: "Hello, stranger!"
end

Pattern Matching in Function Clauses

defmodule ResponseHandler do
  # Handle different HTTP response patterns
  def process({:ok, %{status: 200, body: body}}) do
    {:success, body}
  end

  def process({:ok, %{status: 404}}) do
    {:error, :not_found}
  end

  def process({:ok, %{status: status}}) when status >= 500 do
    {:error, :server_error}
  end

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

  # Coordinate processing
  def quadrant({x, y}) when x > 0 and y > 0, do: :first
  def quadrant({x, y}) when x < 0 and y > 0, do: :second
  def quadrant({x, y}) when x < 0 and y < 0, do: :third
  def quadrant({x, y}) when x > 0 and y < 0, do: :fourth
  def quadrant({0, _}), do: :on_x_axis
  def quadrant({_, 0}), do: :on_y_axis
end

Testing in IEx:

iex> TuplePatterns.handle_result({:ok, "data"})
"Success! Got: \"data\""

iex> TuplePatterns.handle_result({:error, "timeout"})
"Failed: timeout"

iex> TuplePatterns.distance_from_origin({3, 4})
5.0

iex> ResponseHandler.quadrant({5, 3})
:first

iex> ResponseHandler.quadrant({-2, 4})
:second

Ignoring Elements with Underscore

defmodule SelectiveMatching do
  # Extract only what you need
  def get_user_id({:user, id, _, _}), do: id

  def get_username({:user, _, name, _}), do: name

  def get_user_email({:user, _, _, email}), do: email

  # Extract nested data
  def extract_value({:ok, {_, value, _}}), do: value
  def extract_value(_), do: nil

  # Match specific positions
  def is_admin_user({:user, _, _, _, :admin}), do: true
  def is_admin_user(_), do: false
end

Testing in IEx:

iex> user = {:user, 123, "Alice", "alice@example.com"}
{:user, 123, "Alice", "alice@example.com"}

iex> SelectiveMatching.get_user_id(user)
123

iex> SelectiveMatching.get_username(user)
"Alice"

iex> admin_user = {:user, 456, "Bob", "bob@example.com", :admin}
{:user, 456, "Bob", "bob@example.com", :admin}

iex> SelectiveMatching.is_admin_user(admin_user)
true

Common Tuple Patterns

Result Tuples (Ok/Error Pattern)

This is one of the most common patterns in Elixir:

defmodule FileProcessor do
  def read_file(filename) do
    case File.read(filename) do
      {:ok, content} ->
        {:ok, String.upcase(content)}
      {:error, reason} ->
        {:error, "Failed to read #{filename}: #{reason}"}
    end
  end

  def process_multiple_files(filenames) do
    results = Enum.map(filenames, &read_file/1)

    # Separate successful and failed operations
    {successes, errors} =
      Enum.split_with(results, fn
        {:ok, _} -> true
        {:error, _} -> false
      end)

    success_count = length(successes)
    error_count = length(errors)

    {:summary, success_count, error_count}
  end
end

Testing in IEx:

iex> FileProcessor.read_file("nonexistent.txt")
{:error, "Failed to read nonexistent.txt: enoent"}

iex> FileProcessor.process_multiple_files(["file1.txt", "file2.txt"])
{:summary, 0, 2}

Tagged Tuples for Type Safety

defmodule DatabaseRecord do
  # Different record types with tags
  def create_user(id, name, email) do
    {:user, id, name, email, :active}
  end

  def create_product(id, name, price) do
    {:product, id, name, price, :available}
  end

  def create_order(id, user_id, product_ids) do
    {:order, id, user_id, product_ids, :pending}
  end

  # Pattern match on record type
  def get_id({:user, id, _, _, _}), do: {:user_id, id}
  def get_id({:product, id, _, _, _}), do: {:product_id, id}
  def get_id({:order, id, _, _, _}), do: {:order_id, id}
  def get_id(_), do: {:error, :unknown_record_type}
end

Testing in IEx:

iex> user = DatabaseRecord.create_user(1, "Alice", "alice@example.com")
{:user, 1, "Alice", "alice@example.com", :active}

iex> product = DatabaseRecord.create_product(101, "Laptop", 999.99)
{:product, 101, "Laptop", 999.99, :available}

iex> DatabaseRecord.get_id(user)
{:user_id, 1}

iex> DatabaseRecord.get_id(product)
{:product_id, 101}

State Machines with Tuples

defmodule LightSwitch do
  # Represent state as tuples
  def new(), do: {:off, 0}  # {state, usage_count}

  def toggle({:off, count}), do: {:on, count + 1}
  def toggle({:on, count}), do: {:off, count}

  def status({:off, count}), do: "Light is OFF (used #{count} times)"
  def status({:on, count}), do: "Light is ON (used #{count} times)"

  def is_on?({:on, _}), do: true
  def is_on?({:off, _}), do: false
end

Testing in IEx:

iex> light = LightSwitch.new()
{:off, 0}

iex> light = LightSwitch.toggle(light)
{:on, 1}

iex> LightSwitch.status(light)
"Light is ON (used 1 time)"

iex> LightSwitch.is_on?(light)
true

Tuples vs Lists

Understanding when to use tuples vs lists is crucial for writing idiomatic Elixir:

Use Tuples When

# 1. Fixed number of elements with specific meanings
coordinate = {x, y}
rgb_color = {255, 128, 64}
user_info = {:user, id, name, email}

# 2. Function return values (especially ok/error)
def divide(a, b) when b != 0, do: {:ok, a / b}
def divide(_, 0), do: {:error, :division_by_zero}

# 3. Small collections where order matters
version = {1, 2, 3}  # major.minor.patch
date = {2024, 1, 15}  # year, month, day

# 4. When you need direct element access
def get_rgb_red({r, _g, _b}), do: r
def get_rgb_green({_r, g, _b}), do: g
def get_rgb_blue({_r, _g, b}), do: b

Use Lists When

# 1. Variable number of elements
shopping_list = ["apples", "bananas", "bread"]
user_ids = [1, 5, 12, 33, 101]

# 2. Elements of the same type/purpose
temperatures = [20.5, 21.0, 19.8, 22.1]
error_messages = ["Invalid email", "Password too short"]

# 3. When you'll process elements sequentially
numbers = [1, 2, 3, 4, 5]
doubled = Enum.map(numbers, &(&1 * 2))

# 4. When you need to add/remove elements frequently
def add_item(list, item), do: [item | list]
def remove_item(list, item), do: List.delete(list, item)

Decision Guide

# Choose tuples for:
{:response, status_code, headers, body}     # Structured data
{:coordinate, x, y, z}                      # Fixed dimensions
{:ok, result} | {:error, reason}            # Tagged unions

# Choose lists for:
[1, 2, 3, 4, 5, 6, 7, 8, 9, 10]          # Collections to iterate
["red", "green", "blue", "yellow"]         # Variable-length data
[user1, user2, user3]                      # Homogeneous collections

Working with Nested Tuples

Tuples can contain other tuples, creating more complex data structures:

Nested Structure Examples

# Geographic coordinates with metadata
location = {{40.7128, -74.0060}, "New York City", :usa}

# Complex response with nested data
api_response = {
  :ok,
  {200, "OK"},
  %{"content-type" => "application/json"},
  "{\"users\": [1, 2, 3]}"
}

# Nested coordinates (rectangle defined by two points)
rectangle = {{0, 0}, {10, 5}}  # top-left and bottom-right

# Hierarchical data
organization = {
  :company,
  "Tech Corp",
  {:address, "123 Main St", "Tech City", "12345"},
  {:contact, "info@techcorp.com", "+1-555-0123"}
}

Pattern Matching Nested Tuples

defmodule NestedTupleProcessor do
  # Extract nested coordinate data
  def get_city_coordinates({{lat, lon}, city, _country}) do
    "#{city} is at latitude #{lat}, longitude #{lon}"
  end

  # Match nested API response
  def handle_api_response({:ok, {status, _message}, _headers, body})
      when status in 200..299 do
    {:success, body}
  end

  def handle_api_response({:ok, {status, message}, _, _}) do
    {:error, "HTTP #{status}: #{message}"}
  end

  def handle_api_response({:error, reason}) do
    {:error, "Request failed: #{reason}"}
  end

  # Calculate rectangle area
  def rectangle_area({{x1, y1}, {x2, y2}}) do
    width = abs(x2 - x1)
    height = abs(y2 - y1)
    width * height
  end

  # Extract contact info
  def get_company_email({:company, _name, _address, {:contact, email, _phone}}) do
    email
  end
end

Testing in IEx:

iex> location = {{40.7128, -74.0060}, "New York City", :usa}
{{40.7128, -74.006}, "New York City", :usa}

iex> NestedTupleProcessor.get_city_coordinates(location)
"New York City is at latitude 40.7128, longitude -74.006"

iex> rectangle = {{0, 0}, {10, 5}}
{{0, 0}, {10, 5}}

iex> NestedTupleProcessor.rectangle_area(rectangle)
50

Working with Complex Nested Patterns

defmodule DataExtractor do
  # Extract from deeply nested structures
  def extract_user_from_response({:ok, {:data, {:users, users}}, _meta}) do
    {:ok, users}
  end

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

  # Transform nested coordinates
  def translate_point({{x, y}, metadata}, {dx, dy}) do
    {{x + dx, y + dy}, metadata}
  end

  # Validate nested structure
  def validate_config({:config, {:database, _url}, {:redis, _host}, {:log_level, level}})
      when level in [:debug, :info, :warn, :error] do
    :valid
  end

  def validate_config(_), do: :invalid
end

Testing in IEx:

iex> response = {:ok, {:data, {:users, ["Alice", "Bob"]}}, %{timestamp: "2024-01-15"}}
{:ok, {:data, {:users, ["Alice", "Bob"]}}, %{timestamp: "2024-01-15"}}

iex> DataExtractor.extract_user_from_response(response)
{:ok, ["Alice", "Bob"]}

iex> point = {{10, 20}, "New York"}
{{10, 20}, "New York"}

iex> DataExtractor.translate_point(point, {5, -3})
{{15, 17}, "New York"}

iex> config = {:config, {:database, "localhost:5432"}, {:redis, "localhost:6379"}, {:log_level, :info}}
{:config, {:database, "localhost:5432"}, {:redis, "localhost:6379"}, {:log_level, :info}}

iex> DataExtractor.validate_config(config)
:valid

iex> bad_config = {:config, {:database, "localhost"}, {:redis, "localhost"}, {:log_level, :invalid}}
{:config, {:database, "localhost"}, {:redis, "localhost"}, {:log_level, :invalid}}

iex> DataExtractor.validate_config(bad_config)
:invalid

Best Practices

Do's and Don'ts

✅ DO: Use tuples for fixed-size structured data

# Good - clear structure with specific meanings
point = {x, y}
color = {red, green, blue}
result = {:ok, data}

✅ DO: Use tagged tuples for type safety

# Good - the tag makes the data type clear
{:user, id, name, email}
{:error, reason}
{:coordinate, x, y}

✅ DO: Pattern match in function definitions

# Good - clear, readable pattern matching
def handle_result({:ok, data}), do: process_data(data)
def handle_result({:error, reason}), do: log_error(reason)

❌ DON'T: Use tuples for collections of similar items

# Bad - use a list instead
colors = {"red", "green", "blue", "yellow", "orange"}

# Good - variable-length collection
colors = ["red", "green", "blue", "yellow", "orange"]

❌ DON'T: Create very large tuples

# Bad - hard to work with, consider a map or struct
huge_tuple = {1, 2, 3, 4, 5, 6, 7, 8, 9, 10, 11, 12}

# Good - more readable and flexible
user_data = %{
  id: 1, name: "Alice", email: "alice@example.com",
  age: 30, city: "New York", country: "USA"
}

Size Guidelines

Keep tuples small (2-6 elements ideally). For larger structures, consider maps or structs instead.

Error Handling Patterns

defmodule ErrorHandling do
  # Consistent error tuple patterns
  def safe_divide(a, b) when b != 0 do
    {:ok, a / b}
  end

  def safe_divide(_, 0) do
    {:error, :division_by_zero}
  end

  # Chain operations with tuple results
  def calculate_average(numbers) do
    with {:ok, sum} <- safe_sum(numbers),
         {:ok, count} <- safe_count(numbers),
         {:ok, result} <- safe_divide(sum, count) do
      {:ok, result}
    else
      {:error, reason} -> {:error, reason}
    end
  end

  # Helper functions that maintain tuple pattern
  defp safe_sum([]), do: {:error, :empty_list}
  defp safe_sum(numbers), do: {:ok, Enum.sum(numbers)}

  defp safe_count([]), do: {:error, :empty_list}
  defp safe_count(numbers), do: {:ok, length(numbers)}
end

Testing in IEx:

iex> ErrorHandling.safe_divide(10, 2)
{:ok, 5.0}

iex> ErrorHandling.safe_divide(10, 0)
{:error, :division_by_zero}

iex> ErrorHandling.calculate_average([1, 2, 3, 4, 5])
{:ok, 3.0}

iex> ErrorHandling.calculate_average([])
{:error, :empty_list}

Conclusion

Tuples are a fundamental building block in Elixir that enable elegant, type-safe programming patterns. In this article, we've explored:

How tuples work internally
Creating and accessing tuple elements
Pattern matching techniques for destructuring tuples
Common patterns like ok/error tuples and tagged data
When to choose tuples over lists and other data structures
Working with nested tuple structures
Best practices for tuple usage

Key takeaways:

Tuples are perfect for fixed-size, structured data
Pattern matching makes tuple code readable and reliable
The ok/error pattern is essential for error handling
Use tagged tuples for type safety
Keep tuples small and meaningful
Choose tuples for structure, lists for collections

Master tuples, and you'll write more expressive and robust Elixir code. They're the foundation for many advanced patterns you'll encounter as you dive deeper into the Elixir ecosystem.

Next Steps

Now that we understand both lists and tuples, we're ready to explore Maps in Elixir. Maps provide key-value storage and are perfect for representing structured data where you need to access values by name rather than position.

In the next article, we'll explore:

Creating and updating maps
Pattern matching with maps
Map vs struct - when to use each
Working with nested maps
Essential map functions and operations

Maps complete the trio of essential Elixir data structures, giving you the tools to model any kind of data in your applications!

Learning Elixir: Lists

João Paulo Abreu — Sat, 12 Jul 2025 13:35:38 +0000

Lists are like a chain of boxes where each box holds a value and points to the next box in line. Unlike arrays in other languages that let you jump directly to any position, Elixir lists work more like a treasure hunt - you start at the first box and follow the chain until you find what you're looking for. This might sound limiting, but it makes lists incredibly powerful for the functional programming style that Elixir embraces. In this article, we'll explore how lists work, why they're designed this way, and how to use them effectively in your Elixir programs.

Note: The examples in this article use Elixir 1.18.3. While most operations should work across different versions, some functionality might vary.

Introduction
Understanding How Lists Work
Creating Lists
Basic List Operations
Head and Tail Decomposition
List Comprehensions
Essential List Functions
Working with Nested Lists
Best Practices and Common Patterns
Conclusion
Further Reading
Next Steps

Introduction

Lists are one of the most fundamental data structures in Elixir, and understanding them well is essential for effective functional programming.

Think of a list as a train where each car is connected to the next one. You can easily:

Add a new car to the front (very fast)
Look at what's in the first car (very fast)
Get a view of the train starting from the second car (very fast)

But if you want to reach the last car, you'd need to walk through every car in front of it. This is exactly how lists work in Elixir, and understanding this concept will help you write better code.

Lists are perfect for:

Building collections of data piece by piece
Processing data in order from start to finish
Representing sequences where you often work with the first element

Let's dive in and see how they work!

Understanding How Lists Work

Before we jump into using lists, let's understand what makes them special. This will help you understand why some operations are super fast while others take more time.

The Chain Structure

Imagine a list as a chain of connected boxes. Each box contains:

A value (like the number 1, 2, or 3)
A pointer to the next box in the chain

# When you write [1, 2, 3], Elixir creates this structure:
# Box1(1) → Box2(2) → Box3(3) → End

This is different from arrays in other languages where all values are stored side by side in memory. With lists, each box can be anywhere in memory, but they're connected by these pointers.

Head and Tail

Every list has two important parts:

Head: The first value in the list
Tail: Everything else (which is also a list!)

Important: Lists in Elixir are immutable. Operations like [1 | list] or list ++ [5] create new lists - the original remains unchanged.

list1 = [1, 2, 3, 4]
list2 = [2, 3, 4] 
list3 = [4]

# For [1, 2, 3, 4]: head = 1, tail = [2, 3, 4]
head1 = hd(list1)  # Result: 1
tail1 = tl(list1)  # Result: [2, 3, 4]

# For [2, 3, 4]: head = 2, tail = [3, 4]
head2 = hd(list2)  # Result: 2
tail2 = tl(list2)  # Result: [3, 4]

# For [4]: head = 4, tail = [] (empty list)
head3 = hd(list3)  # Result: 4
tail3 = tl(list3)  # Result: []

Let's see this in action:

my_list = [1, 2, 3, 4]

# Get the first element (head) - this will be 1
first = hd(my_list)

# Get everything except the first element (tail) - this will be [2, 3, 4]
rest = tl(my_list)

Testing in IEx:

iex> my_list = [1, 2, 3, 4]
[1, 2, 3, 4]

iex> hd(my_list)
1

iex> tl(my_list)
[2, 3, 4]

Why This Structure Matters

This chain structure explains why certain operations are super fast:

# These are FAST (instant):
list = [1, 2, 3, 4, 5]
first_element = hd(list)      # Just look at the first box
rest_of_list = tl(list)       # Just follow the pointer
new_list = [0 | list]         # Just create one new box

# These are SLOWER (have to walk the chain):
last_element = List.last(list)     # Walk to the end
list_length = length(list)         # Count all boxes
third_element = Enum.at(list, 2)   # Walk to position 2

Testing in IEx

iex> fruits = ["apple", "banana", "cherry"]
["apple", "banana", "cherry"]
iex> hd(fruits)
"apple"
iex> tl(fruits)
["banana", "cherry"]
iex> [1 | [2, 3]]
[1, 2, 3]

Creating Lists

There are several ways to create lists in Elixir, each useful in different situations.

Literal Syntax

The most common way to create lists is using the literal syntax:

# Empty list
empty = []

# List of integers
numbers = [1, 2, 3, 4, 5]

# List of atoms
statuses = [:ok, :error, :pending]

# Mixed types (though not always recommended)
mixed = [1, :atom, "string", [1, 2]]

# Lists can contain any Elixir data type
complex = [
  %{name: "Alice", age: 30},
  {:tuple, "data"},
  fn x -> x * 2 end
]

Testing in IEx:

iex> empty = []
[]

iex> numbers = [1, 2, 3, 4, 5]
[1, 2, 3, 4, 5]

iex> statuses = [:ok, :error, :pending]
[:ok, :error, :pending]

iex> mixed = [1, :atom, "string", [1, 2]]
[1, :atom, "string", [1, 2]]

Using the Cons Operator

The cons operator | allows you to prepend elements:

original = [2, 3, 4]
# Add 1 to the front - result will be [1, 2, 3, 4]
with_prepended = [1 | original]

Testing in IEx:

iex> original = [2, 3, 4]
[2, 3, 4]

iex> [1 | original]
[1, 2, 3, 4]

iex> [0, 1 | original]
[0, 1, 2, 3, 4]

Range to List Conversion

You can convert ranges to lists using Enum.to_list/1:

# Simple range - creates [1, 2, 3, 4, 5]
numbers = Enum.to_list(1..5)

# Range with steps (every 2nd number) - creates [2, 4, 6, 8, 10]
evens = Enum.to_list(2..10//2)

# Descending range (step of -1) - creates [5, 4, 3, 2, 1]
countdown = Enum.to_list(5..1//-1)

Testing in IEx:

iex> Enum.to_list(1..5)
[1, 2, 3, 4, 5]

iex> Enum.to_list(2..10//2)
[2, 4, 6, 8, 10]

iex> Enum.to_list(5..1//-1)
[5, 4, 3, 2, 1]

Using List Module Functions

The List module provides functions for creating specialized lists:

# Duplicate elements - creates [0, 0, 0, 0, 0]
zeros = List.duplicate(0, 5)
# Creates ["hello", "hello", "hello"]
greetings = List.duplicate("hello", 3)

Testing in IEx:

iex> List.duplicate(0, 5)
[0, 0, 0, 0, 0]

iex> List.duplicate("hello", 3)
["hello", "hello", "hello"]

A Quick Note About Display in IEx

Sometimes you might see something unexpected in IEx when working with lists of numbers:

# This might surprise you!
numbers = [72, 101, 108, 108, 111]
# IEx might display this as ~c"Hello" instead of [72, 101, 108, 108, 111]

This happens because these numbers correspond to ASCII character codes, and IEx tries to be helpful by showing them as a charlist (character list). The list is still a list of numbers - it's just how IEx chooses to display it. You can force IEx to show the actual numbers:

# Force IEx to show numbers
inspect([72, 101, 108, 108, 111], charlists: :as_lists)
# Shows: [72, 101, 108, 108, 111]

Testing in IEx:

iex> [72, 101, 108, 108, 111]
~c"Hello"

iex> inspect([72, 101, 108, 108, 111], charlists: :as_lists)
"[72, 101, 108, 108, 111]"

iex> # These don't form valid ASCII, so shown as numbers
nil
iex> [1, 2, 3, 200, 255]
[1, 2, 3, 200, 255]

Don't worry - this is just a display quirk in IEx. Your list is still a list of integers!

Basic List Operations

Now that we understand how to create lists, let's explore the fundamental operations you'll use daily.

Accessing Elements

list = [1, 2, 3, 4, 5]

# Getting the first element (head) - result is 1
first = hd(list)

# Getting all but the first element (tail) - result is [2, 3, 4, 5]
rest = tl(list)

# Safe access (returns nil for empty lists) - result is 1
first_safe = List.first(list)
# This returns nil instead of crashing
first_empty = List.first([])

# Getting the last element (expensive - O(n)) - result is 5
last = List.last(list)

# Accessing by index (expensive - O(n), zero-indexed) - result is 3
third = Enum.at(list, 2)  # Index 2 means third element

# ⚠️ Important: hd/1 and tl/1 crash on empty lists!
hd([])  # ** (ArgumentError) argument error
tl([])  # ** (ArgumentError) argument error

# Use List.first/1 for safe access:
List.first([])  # nil (doesn't crash)

Adding Elements

original = [2, 3, 4]

# Prepending (fast - O(1)) - result is [1, 2, 3, 4]
prepended = [1 | original]

# Appending (slow - O(n)) - result is [2, 3, 4, 5]
appended = original ++ [5]

# Multiple prepends (add multiple elements at once) - result is [0, 1, 2, 3, 4]
multiple_prepend = [0, 1 | original]

Concatenating Lists

list1 = [1, 2, 3]
list2 = [4, 5, 6]

# Concatenation
combined = list1 ++ list2

# Flatten nested lists
nested = [[1, 2], [3, 4], [5]]
flattened = List.flatten(nested)

Basic Information

list = [1, 2, 3, 4, 5]

# Length (O(n) operation)
len = length(list)  # 5

# Check if empty (pattern matching against [] is idiomatic)
is_empty = list == []  # false
is_empty_alt = length(list) == 0  # false (requires traversal, less efficient)

# Check if element exists
has_three = 3 in list  # true
has_ten = 10 in list   # false

Testing in IEx - Basic Operations

iex> list = [1, 2, 3, 4, 5]
[1, 2, 3, 4, 5]
iex> hd(list)
1
iex> tl(list)
[2, 3, 4, 5]
iex> List.first([])
nil
iex> [0 | list]
[0, 1, 2, 3, 4, 5]
iex> [1, 2] ++ [3, 4]
[1, 2, 3, 4]
iex> 3 in [1, 2, 3, 4]
true

Head and Tail Decomposition

Head and tail decomposition is one of the most powerful techniques for working with lists in functional programming. It allows you to process lists recursively by dealing with one element at a time.

Understanding Head and Tail

# Any non-empty list can be decomposed into head and tail
list = [1, 2, 3, 4, 5]

# Head: the first element - result is 1
head = hd(list)

# Tail: everything except the first element - result is [2, 3, 4, 5]
tail = tl(list)

# The tail is itself a list (possibly empty)
single_element = [42]
head_single = hd(single_element)  # Result: 42
tail_single = tl(single_element)  # Result: [] (empty list)

Recursive Processing

Head and tail decomposition enables elegant recursive solutions:

defmodule ListProcessor do
  # Calculate sum recursively
  def sum([]), do: 0
  def sum([head | tail]), do: head + sum(tail)

  # Count elements recursively
  def count([]), do: 0
  def count([_head | tail]), do: 1 + count(tail)

  # Find maximum element
  def max([single]), do: single
  def max([head | tail]) do
    tail_max = max(tail)
    if head > tail_max, do: head, else: tail_max
  end

  # Reverse a list (using accumulator for efficiency)
  def reverse(list), do: reverse(list, [])

  # Base case: empty list, return accumulator
  defp reverse([], acc), do: acc
  # Recursive case: move head to accumulator, process tail
  defp reverse([head | tail], acc), do: reverse(tail, [head | acc])
end

Building Lists with Head and Tail

defmodule ListBuilder do
  # Double all elements
  def double([]), do: []
  def double([head | tail]), do: [head * 2 | double(tail)]

  # Filter elements (keep only those that pass the test)
  def filter([], _fun), do: []
  def filter([head | tail], fun) do
    if fun.(head) do
      [head | filter(tail, fun)]  # Keep this element
    else
      filter(tail, fun)  # Skip this element
    end
  end

  # Map transformation
  def map([], _fun), do: []
  def map([head | tail], fun), do: [fun.(head) | map(tail, fun)]
end

Testing in IEx - Recursive Functions

iex> [head | tail] = [1, 2, 3, 4, 5]
[1, 2, 3, 4, 5]
iex> head
1
iex> tail
[2, 3, 4, 5]
iex> ListProcessor.sum([1, 2, 3])
6
iex> ListProcessor.count([1, 2, 3, 4])
4
iex> ListProcessor.max([3, 1, 4, 1, 5])
5
iex> ListProcessor.reverse([1, 2, 3])
[3, 2, 1]
iex> ListBuilder.double([1, 2, 3])
[2, 4, 6]
iex> ListBuilder.filter([1, 2, 3, 4, 5], &(rem(&1, 2) == 0))
[2, 4]

List Comprehensions

List comprehensions let you create new lists in a clean, readable way:

# Square numbers from 1 to 5 - creates [1, 4, 9, 16, 25]
squares = for n <- 1..5, do: n * n

# Only even numbers - creates [2, 4, 6, 8, 10]
evens = for n <- 1..10, rem(n, 2) == 0, do: n

# Extract successful results (pattern match only :ok tuples)
results = [{:ok, 1}, {:error, "bad"}, {:ok, 2}]
successes = for {:ok, value} <- results, do: value  # Creates [1, 2]

Testing in IEx - Comprehensions

iex> for n <- 1..5, do: n * n
[1, 4, 9, 16, 25]
iex> for n <- 1..10, rem(n, 2) == 0, do: n
[2, 4, 6, 8, 10]
iex> for {:ok, value} <- [{:ok, 1}, {:ok, 2}], do: value * 2
[2, 4]

Working with Nested Lists

Sometimes you'll work with lists containing other lists. List comprehensions make this easy:

# Cartesian product - all combinations
coordinates = for x <- 1..2, y <- 1..2, do: {x, y}
# Result: [{1, 1}, {1, 2}, {2, 1}, {2, 2}]

# Nested list processing
matrix = [[1, 2], [3, 4], [5, 6]]
all_elements = for row <- matrix, element <- row, do: element
# Result: [1, 2, 3, 4, 5, 6]

# With filtering
greater_than_three = for row <- matrix, element <- row, element > 3, do: element
# Result: [4, 5, 6]

Pattern Matching in Comprehensions

# Extract from tuples - gets only names, result is ["Alice", "Bob"]
people = [{"Alice", 25}, {"Bob", 30}]
names = for {name, _age} <- people, do: name

# Filter by pattern - only extracts :ok values, result is [1, 2]
results = [{:ok, 1}, {:error, "bad"}, {:ok, 2}]
successes = for {:ok, value} <- results, do: value

Testing in IEx - Nested Lists

iex> people = [{"Alice", 25}, {"Bob", 30}]
[{"Alice", 25}, {"Bob", 30}]
iex> for {name, _age} <- people, do: name
["Alice", "Bob"]
iex> results = [{:ok, 1}, {:error, "bad"}, {:ok, 2}]
[{:ok, 1}, {:error, "bad"}, {:ok, 2}]
iex> for {:ok, value} <- results, do: value
[1, 2]
iex> for x <- 1..2, y <- 1..2, do: {x, y}
[{1, 1}, {1, 2}, {2, 1}, {2, 2}]
iex> for n <- 1..3, into: %{}, do: {n, n * n}
%{1 => 1, 2 => 4, 3 => 9}

Essential List Functions

The List module and Enum module provide a rich set of functions for working with lists. Let's explore the most essential ones you'll use in everyday Elixir programming.

List Module Functions

The List module contains functions specific to lists:

# Basic list information
list = [1, 2, 3, 4, 5]

# First and last elements (safe)
first = List.first(list)        # 1
last = List.last(list)          # 5
first_empty = List.first([])    # nil

# Insert and delete
inserted = List.insert_at(list, 2, 99)
# [1, 2, 99, 3, 4, 5]
deleted = List.delete_at(list, 2)
# [1, 2, 4, 5]
delete_value = List.delete(list, 3)
# [1, 2, 4, 5]

# Replace and update
replaced = List.replace_at(list, 2, 99)
# [1, 2, 99, 4, 5]
updated = List.update_at(list, 2, fn x -> x * 10 end)
# [1, 2, 30, 4, 5]

# Duplicate elements
duplicated = List.duplicate(:ok, 3)
# [:ok, :ok, :ok]

Enum Module Functions

Most list processing is done with Enum functions, which work with any enumerable:

numbers = [1, 2, 3, 4, 5, 6, 7, 8, 9, 10]

# Basic transformations
doubled = Enum.map(numbers, fn x -> x * 2 end)
# [2, 4, 6, 8, 10, 12, 14, 16, 18, 20]

evens = Enum.filter(numbers, fn x -> rem(x, 2) == 0 end)
# [2, 4, 6, 8, 10]

# Reducing operations
sum = Enum.sum(numbers)                    # 55
product = Enum.reduce(numbers, 1, &*/2)   # 3628800
max_value = Enum.max(numbers)             # 10
min_value = Enum.min(numbers)             # 1

# Finding elements
found = Enum.find(numbers, fn x -> x > 7 end)        # 8
found_index = Enum.find_index(numbers, fn x -> x > 7 end)  # 7
member = Enum.member?(numbers, 5)                    # true

Useful Enum Functions for Lists

data = [3, 1, 4, 1, 5, 9, 2, 6, 5, 3]

# Sorting - result is [1, 1, 2, 3, 3, 4, 5, 5, 6, 9]
sorted = Enum.sort(data)
# Descending sort - result is [9, 6, 5, 5, 4, 3, 3, 2, 1, 1]
sorted_desc = Enum.sort(data, :desc)

# Unique elements - removes duplicates, result is [3, 1, 4, 5, 9, 2, 6]
unique = Enum.uniq(data)

# Frequency counting - counts how many times each appears
frequencies = Enum.frequencies(data)  # %{1 => 2, 2 => 1, 3 => 2, ...}

Testing Enum Functions

iex> data = [3, 1, 4, 1, 5, 9, 2, 6, 5, 3]
[3, 1, 4, 1, 5, 9, 2, 6, 5, 3]
iex> Enum.sort(data)
[1, 1, 2, 3, 3, 4, 5, 5, 6, 9]
iex> Enum.uniq(data)
[3, 1, 4, 5, 9, 2, 6]
iex> Enum.frequencies([1, 2, 1, 3, 2])
%{1 => 2, 2 => 2, 3 => 1}
iex> Enum.take(data, 3)
[3, 1, 4]
iex> Enum.drop(data, 3)
[1, 5, 9, 2, 6, 5, 3]

Combining Multiple Operations

defmodule DataProcessor do
  # Process numbers: filter evens, square them, sum the result
  def process_numbers(numbers) do
    numbers
    |> Enum.filter(fn x -> rem(x, 2) == 0 end)  # Get evens
    |> Enum.map(fn x -> x * x end)              # Square them
    |> Enum.sum()                               # Sum the squares
  end

  # Process transactions: calculate total deposits
  def total_deposits(transactions) do
    transactions
    |> Enum.filter(fn tx -> tx.type == :deposit end)
    |> Enum.map(fn tx -> tx.amount end)
    |> Enum.sum()
  end

  # Process transactions: calculate total withdrawals
  def total_withdrawals(transactions) do
    transactions
    |> Enum.filter(fn tx -> tx.type == :withdrawal end)
    |> Enum.map(fn tx -> tx.amount end)
    |> Enum.sum()
  end
end

Testing in IEx - List Functions

iex> DataProcessor.process_numbers([1, 2, 3, 4, 5, 6, 7, 8, 9, 10])
220
iex> transactions = [%{type: :deposit, amount: 100, date: ~D[2023-01-01]}, %{type: :withdrawal, amount: 50, date: ~D[2023-01-02]}, %{type: :deposit, amount: 200, date: ~D[2023-01-03]}, %{type: :withdrawal, amount: 75, date: ~D[2023-01-04]}]
[%{type: :deposit, amount: 100, date: ~D[2023-01-01]}, ...]
iex> DataProcessor.total_deposits(transactions)
300
iex> DataProcessor.total_withdrawals(transactions)
125
iex> Enum.map([1, 2, 3], &(&1 * 2))
[2, 4, 6]
iex> [1, 2, 3, 4, 5, 6] |> Enum.filter(&(rem(&1, 2) == 0)) |> Enum.sum()
12

Best Practices and Common Patterns

Here are some simple guidelines to help you write better list code:

Do's and Don'ts

✅ DO: Use head and tail pattern matching

def sum([]), do: 0
def sum([head | tail]), do: head + sum(tail)

✅ DO: Use list comprehensions for simple transformations

squares = for n <- 1..5, do: n * n

✅ DO: Use prepending (adding to front)

new_list = [new_item | existing_list]  # Fast!

Testing Best Practices

# Try these examples to see the concepts in action
iex> defmodule ListExamples do; def sum([]), do: 0; def sum([head | tail]), do: head + sum(tail); end
{:module, ListExamples, ...}
iex> ListExamples.sum([1, 2, 3, 4])
10
iex> for n <- 1..5, do: n * n
[1, 4, 9, 16, 25]
iex> existing = [2, 3, 4]
[2, 3, 4]
iex> [1 | existing]
[1, 2, 3, 4]

❌ DON'T: Use appending for building lists

# Slow - avoid this pattern
new_list = existing_list ++ [new_item]

✅ DO: Use Enum functions for data processing

result = numbers
         |> Enum.filter(fn x -> x > 0 end)
         |> Enum.map(fn x -> x * 2 end)

When to Use Lists

Lists are perfect for:

Processing data in order
Building collections piece by piece
Recursive operations
When you mostly work with the first element

Simple Examples

# Building a list efficiently (prepending is O(1))
def build_countdown(0, acc), do: acc  # Base case
def build_countdown(n, acc), do: build_countdown(n - 1, [n | acc])  # Add n to front

# Processing with pattern matching (recursive search)
def find_first_even([]), do: nil  # Empty list - not found
def find_first_even([head | tail]) do
  if rem(head, 2) == 0 do
    head  # Found even number, return it
  else
    find_first_even(tail)  # Keep searching in tail
  end
end

Conclusion

Lists are one of the most important data structures in Elixir. In this article, we've covered:

How lists work internally (linked structure)
Creating and manipulating lists
Head and tail operations
List comprehensions
Essential List and Enum functions
Working with nested lists
Best practices for list code

Understanding lists well will make you much more effective at Elixir programming. They're the foundation for many functional programming patterns and you'll use them constantly in real applications.

Next Steps

With a solid understanding of lists, you're ready to explore Tuples in Elixir. Tuples complement lists perfectly by providing fast random access and representing structured data with a fixed number of elements.

In the next article, we'll explore:

When to choose tuples over lists
Pattern matching with tuples
Tuple-based return values and error handling
Practical applications in real-world Elixir code

The journey through Elixir's data structures continues!

Learning Elixir: Pattern Matching

João Paulo Abreu — Sat, 05 Jul 2025 12:01:09 +0000

Pattern matching is one of Elixir's most powerful features, allowing you to match against data structures and extract values in a single, elegant operation. Think of it as an advanced form of assignment that can also check the shape and content of your data. In this comprehensive article, we'll explore pattern matching in depth - from basic concepts to advanced techniques, covering everything you need to master this fundamental Elixir feature.

Note: The examples in this article use Elixir 1.18.3. While most operations should work across different versions, some functionality might vary.

Introduction
Understanding Pattern Matching
Basic Pattern Matching
Pattern Matching with Data Structures
Pattern Matching in Function Definitions
Guards: Adding Conditions to Patterns
Advanced Matching Techniques
Common Patterns and Best Practices
Conclusion
Further Reading
Next Steps

Introduction

Pattern matching is like a sophisticated puzzle solver. Instead of just assigning values to variables, pattern matching lets you:

Check if data has a specific structure
Extract values from complex data structures
Create multiple function clauses that handle different cases
Write more declarative and readable code

Unlike traditional assignment in other languages, pattern matching in Elixir is about asserting that the right side of the = operator matches the pattern on the left side.

Understanding Pattern Matching

The Match Operator

In Elixir, = is not just an assignment operator—it's a match operator. When we write x = 1, we're actually saying "match the pattern x with the value 1". Since x is an unbound variable, it matches any value and binds to it.

# Simple matching
x = 1
1 = x  # This works! We're asserting that 1 matches x
2 = x  # This fails with MatchError

Testing in IEx:

iex> x = 1
1

iex> 1 = x
1

iex> 2 = x
** (MatchError) no match of right hand side value: 1

Pattern Matching is Structural

Pattern matching works by comparing the structure and values of data:

# Matching tuples
{:ok, result} = {:ok, 42}
# result is now bound to 42

# The pattern must match the structure
{:ok, result} = {:error, "failed"}  # MatchError!

# You can match partial structures
{:user, _, age} = {:user, "Alice", 25}
# age is now 25, we ignored the name with _

Testing in IEx:

iex> {:ok, result} = {:ok, 42}
{:ok, 42}

iex> result
42

iex> {:ok, result} = {:error, "failed"}
** (MatchError) no match of right hand side value: {:error, "failed"}

iex> {:user, _, age} = {:user, "Alice", 25}
{:user, "Alice", 25}

iex> age
25

Basic Pattern Matching

Matching Simple Values

defmodule BasicMatching do
  def describe_number(0), do: "zero"
  def describe_number(1), do: "one"
  def describe_number(2), do: "two"
  def describe_number(n) when n > 0, do: "positive"
  def describe_number(n) when n < 0, do: "negative"

  def process_result({:ok, value}), do: "Success: #{value}"
  def process_result({:error, reason}), do: "Failed: #{reason}"
  def process_result(_), do: "Unknown result"
end

Testing in IEx:

iex> BasicMatching.describe_number(0)
"zero"

iex> BasicMatching.describe_number(42)
"positive"

iex> BasicMatching.describe_number(-5)
"negative"

iex> BasicMatching.process_result({:ok, "data"})
"Success: data"

iex> BasicMatching.process_result({:error, "timeout"})
"Failed: timeout"

The Underscore Pattern

The underscore _ is a special pattern that matches anything but doesn't bind the value:

defmodule UnderscoreExamples do
  # Match any three-element tuple starting with :data
  def extract_id({:data, id, _}), do: id

  # Match a map but only extract specific keys
  def get_name(%{name: name, age: _, email: _}), do: name

  # Use multiple underscores - each is independent
  def third_element({_, _, third}), do: third
end

Testing in IEx:

iex> UnderscoreExamples.extract_id({:data, 123, "extra info"})
123

iex> UnderscoreExamples.get_name(%{name: "Bob", age: 30, email: "bob@example.com"})
"Bob"

iex> UnderscoreExamples.third_element({:a, :b, :c})
:c

Pattern Matching with Data Structures

Lists

Lists have special pattern matching syntax using the [head | tail] notation:

defmodule ListPatterns do
  def empty?([]), do: true
  def empty?([_ | _]), do: false

  def first([head | _]), do: {:ok, head}
  def first([]), do: {:error, "empty list"}

  def second([_, second | _]), do: {:ok, second}
  def second(_), do: {:error, "list too short"}

  # Recursive list processing
  def sum([]), do: 0
  def sum([head | tail]), do: head + sum(tail)

  # Match specific patterns
  def starts_with_zero?([0 | _]), do: true
  def starts_with_zero?(_), do: false
end

Testing in IEx:

iex> ListPatterns.empty?([])
true

iex> ListPatterns.empty?([1, 2, 3])
false

iex> ListPatterns.first([10, 20, 30])
{:ok, 10}

iex> ListPatterns.second([10, 20, 30])
{:ok, 20}

iex> ListPatterns.sum([1, 2, 3, 4, 5])
15

iex> ListPatterns.starts_with_zero?([0, 1, 2])
true

Maps

Map pattern matching is particularly useful for extracting values:

defmodule MapPatterns do
  # Match required keys
  def greet(%{name: name}), do: "Hello, #{name}!"

  # Match multiple keys
  def full_name(%{first: first, last: last}), do: "#{first} #{last}"

  # Optional keys with defaults
  def user_info(%{name: name} = user) do
    age = Map.get(user, :age, "unknown")
    "#{name} (age: #{age})"
  end

  # Nested map matching
  def get_city(%{address: %{city: city}}), do: {:ok, city}
  def get_city(_), do: {:error, "no city found"}

  # Update specific fields
  def birthday(%{age: age} = person) do
    %{person | age: age + 1}
  end
end

Testing in IEx:

iex> MapPatterns.greet(%{name: "Alice", age: 30})
"Hello, Alice!"

iex> MapPatterns.full_name(%{first: "John", last: "Doe", age: 25})
"John Doe"

iex> MapPatterns.user_info(%{name: "Bob"})
"Bob (age: unknown)"

iex> MapPatterns.get_city(%{address: %{city: "Paris", country: "France"}})
{:ok, "Paris"}

iex> MapPatterns.birthday(%{name: "Carol", age: 29})
%{age: 30, name: "Carol"}

Structs

Structs are maps with predefined keys and can be pattern matched like maps:

defmodule User do
  defstruct [:name, :email, :age]
end

defmodule StructPatterns do
  # Match against struct type
  def process(%User{} = user), do: {:user, user}
  def process(%{}), do: {:map, "regular map"}

  # Extract specific fields
  def adult?(%User{age: age}) when age >= 18, do: true
  def adult?(%User{}), do: false

  # Match and update
  def anonymize(%User{} = user) do
    %{user | name: "Anonymous", email: "hidden@example.com"}
  end
end

Testing in IEx:

iex> user = %User{name: "Alice", email: "alice@example.com", age: 25}
%User{age: 25, email: "alice@example.com", name: "Alice"}

iex> StructPatterns.process(user)
{:user, %User{age: 25, email: "alice@example.com", name: "Alice"}}

iex> StructPatterns.process(%{name: "Bob"})
{:map, "regular map"}

iex> StructPatterns.adult?(user)
true

iex> StructPatterns.anonymize(user)
%User{age: 25, email: "hidden@example.com", name: "Anonymous"}

Pattern Matching in Function Definitions

Multiple Function Clauses

Pattern matching in function definitions is idiomatic in Elixir and allows you to write different implementations for different input patterns:

defmodule Calculator do
  # Pattern match on operation atoms
  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: {:ok, a / b}

  # Pattern match on data structure
  def area({:rectangle, width, height}), do: width * height
  def area({:circle, radius}), do: 3.14159 * radius * radius
  def area({:triangle, base, height}), do: 0.5 * base * height
end

Testing in IEx:

iex> Calculator.calculate(:add, 10, 5)
15

iex> Calculator.calculate(:divide, 10, 0)
{:error, "division by zero"}

iex> Calculator.calculate(:divide, 10, 2)
{:ok, 5.0}

iex> Calculator.area({:rectangle, 4, 5})
20

iex> Calculator.area({:circle, 3})
28.27431

Pattern Matching in Anonymous Functions

defmodule AnonymousPatterns do
  def process_list(list) do
    Enum.map(list, fn
      {:ok, value} -> value * 2
      {:error, _} -> 0
      value -> value
    end)
  end

  def classify_numbers(numbers) do
    Enum.map(numbers, fn
      0 -> :zero
      n when n > 0 -> :positive
      _ -> :negative
    end)
  end
end

Testing in IEx:

iex> AnonymousPatterns.process_list([{:ok, 5}, {:error, "failed"}, 10])
[10, 0, 10]

iex> AnonymousPatterns.classify_numbers([-5, 0, 3, -2, 7])
[:negative, :zero, :positive, :negative, :positive]

Guards: Adding Conditions to Patterns

Guards allow you to add additional conditions to pattern matches:

defmodule GuardExamples do
  # Type guards
  def double(x) when is_number(x), do: x * 2
  def double(x) when is_binary(x), do: x <> x

  # Comparison guards
  def grade(score) when score >= 90, do: "A"
  def grade(score) when score >= 80, do: "B"
  def grade(score) when score >= 70, do: "C"
  def grade(score) when score >= 60, do: "D"
  def grade(_), do: "F"

  # Multiple conditions
  def can_vote?(age, citizen) when age >= 18 and citizen == true, do: true
  def can_vote?(_, _), do: false

  # Guards with pattern matching
  def process_user(%{age: age, status: :active} = user) when age >= 18 do
    {:ok, "Adult user: #{user.name}"}
  end
  def process_user(%{age: age}) when age < 18 do
    {:error, "User must be 18 or older"}
  end
  def process_user(_), do: {:error, "Invalid user"}
end

Testing in IEx:

iex> GuardExamples.double(5)
10

iex> GuardExamples.double("hello")
"hellohello"

iex> GuardExamples.grade(85)
"B"

iex> GuardExamples.can_vote?(20, true)
true

iex> GuardExamples.can_vote?(17, true)
false

iex> GuardExamples.process_user(%{name: "Alice", age: 20, status: :active})
{:ok, "Adult user: Alice"}

Advanced Matching Techniques

The Pin Operator (^)

The pin operator ^ allows you to match against existing variable values instead of rebinding:

defmodule PinOperator do
  def match_exact_value(list, target) do
    Enum.any?(list, fn
      ^target -> true
      _ -> false
    end)
  end

  def update_if_matches(map, key, old_value, new_value) do
    case Map.get(map, key) do
      ^old_value -> Map.put(map, key, new_value)
      _ -> {:error, "Value doesn't match"}
    end
  end

  # Finds the first duplicated value and returns its positions  
  def find_duplicate_position(list) do
    list
    |> Enum.with_index()
    |> Enum.reduce_while(nil, fn {value, index}, _ ->
      case Enum.find_index(list, fn x -> x == value end) do
        ^index -> {:cont, nil}  # First occurrence
        other -> {:halt, {value, other, index}}  # Found duplicate
      end
    end)
  end
end

Testing in IEx:

iex> PinOperator.match_exact_value([1, 2, 3, 4], 3)
true

iex> target = 5
5

iex> PinOperator.match_exact_value([1, 2, 3, 4], target)
false

iex> PinOperator.update_if_matches(%{status: :pending}, :status, :pending, :active)
%{status: :active}

iex> PinOperator.update_if_matches(%{status: :active}, :status, :pending, :active)
{:error, "Value doesn't match"}

iex> PinOperator.find_duplicate_position([1, 2, 3, 2, 5])
{2, 1, 3}

Matching with case

The case expression is perfect for pattern matching against multiple possibilities:

defmodule CasePatterns do
  def handle_response(response) do
    case response do
      {:ok, data} when is_list(data) ->
        "Got #{length(data)} items"

      {:ok, data} when is_map(data) ->
        "Got a map with #{map_size(data)} keys"

      {:ok, data} ->
        "Got data: #{inspect(data)}"

      {:error, :not_found} ->
        "Resource not found"

      {:error, reason} when is_binary(reason) ->
        "Error: #{reason}"

      _ ->
        "Unknown response"
    end
  end

  def parse_command(input) do
    case String.split(input, " ", parts: 2) do
      ["get", key] -> {:get, key}
      ["set", rest] ->
        case String.split(rest, "=", parts: 2) do
          [key, value] -> {:set, key, value}
          _ -> {:error, "Invalid set syntax"}
        end
      ["delete", key] -> {:delete, key}
      [cmd | _] -> {:error, "Unknown command: #{cmd}"}
      [] -> {:error, "Empty command"}
    end
  end
end

Testing in IEx:

iex> CasePatterns.handle_response({:ok, [1, 2, 3]})
"Got 3 items"

iex> CasePatterns.handle_response({:ok, %{a: 1, b: 2}})
"Got a map with 2 keys"

iex> CasePatterns.handle_response({:error, "Connection timeout"})
"Error: Connection timeout"

iex> CasePatterns.parse_command("get user:123")
{:get, "user:123"}

iex> CasePatterns.parse_command("set name=Alice")
{:set, "name", "Alice"}

iex> CasePatterns.parse_command("invalid")
{:error, "Unknown command: invalid"}

Common Patterns and Best Practices

1. Use Pattern Matching for Control Flow

Instead of nested if statements, use pattern matching:

# Good: Clear pattern matching
def process_age(age) do
  case age do
    age when age >= 65 -> :senior
    age when age >= 18 -> :adult
    age when age >= 13 -> :teen
    _ -> :child
  end
end

# Less idiomatic: Nested ifs
def process_age_imperative(age) do
  if age >= 65 do
    :senior
  else
    if age >= 18 do
      :adult
    else
      if age >= 13 do
        :teen
      else
        :child
      end
    end
  end
end

2. Order Matters

Put more specific patterns before general ones:

defmodule OrderMatters do
  # Correct order: specific to general
  def classify([]), do: :empty
  def classify([_]), do: :single
  def classify([_, _]), do: :pair
  def classify(list) when is_list(list), do: :many

  # Wrong order: general pattern would catch everything
  # def classify(list) when is_list(list), do: :many  # This would match all lists!
  # def classify([]), do: :empty  # Never reached
end

3. Use Guards for Additional Constraints

defmodule SafeOperations do
  def safe_divide(a, b) when is_number(a) and is_number(b) and b != 0 do
    {:ok, a / b}
  end

  def safe_divide(_, 0), do: {:error, :division_by_zero}
  def safe_divide(_, _), do: {:error, :invalid_arguments}

  def validate_email(email) when is_binary(email) do
    if String.contains?(email, "@") do
      {:ok, email}
    else
      {:error, :invalid_format}
    end
  end

  def validate_email(_), do: {:error, :not_a_string}
end

4. Destructure Only What You Need

defmodule EfficientMatching do
  # Good: Only extract what you need
  def get_user_name(%{user: %{name: name}}), do: name

  # Less efficient: Extracting entire structures unnecessarily
  def get_user_name_verbose(%{user: user}) do
    user.name
  end

  # Good: Ignore irrelevant data
  def process_event({:event, type, _timestamp, _metadata}) do
    "Processing #{type} event"
  end
end

Conclusion

Pattern matching is a cornerstone of Elixir programming that makes code more declarative, readable, and robust. By matching on the structure of data rather than imperatively checking conditions, you can:

Write cleaner, more expressive code
Handle different cases elegantly with function clauses
Extract values from complex data structures easily
Ensure data has the expected shape before processing
Create powerful abstractions with minimal code

Key takeaways:

The = operator is for matching, not just assignment
Patterns can include literals, variables, and underscore
Function clauses with pattern matching replace complex conditionals
Guards add extra power to pattern matching
The pin operator ^ lets you match against existing values
Order matters—put specific patterns before general ones

Master pattern matching, and you'll write Elixir code that's both powerful and beautiful.

Next Steps

Now that we've covered pattern matching comprehensively, in the next article we'll explore Elixir's data structures:

Lists in Elixir

Basic list operations and manipulations
Head/tail decomposition
List comprehensions
Performance characteristics
Common list algorithms

Lists are fundamental to functional programming, and understanding them deeply will help you write more efficient Elixir code.

Learning Elixir: Function Composition

João Paulo Abreu — Sat, 28 Jun 2025 12:12:49 +0000

Function composition is like building with LEGO blocks - you create small, simple pieces that can be connected together to build something bigger. In Elixir, instead of writing one huge function that does everything, we write small functions that do one thing well, then combine them. This makes our code easier to understand, test, and reuse. In this article, we'll start with simple examples and gradually explore different ways to combine functions in Elixir.

Note: The examples in this article use Elixir 1.18.3. While most operations should work across different versions, some functionality might vary.

Introduction
Understanding Function Composition
Basic Composition Techniques
Higher-Order Functions
Partial Application and Currying
Working with Results That Can Fail
Real-World Examples
Best Practices
Conclusion
Further Reading
Next Steps

Introduction

Function composition is about building complex functionality from simple, composable parts. Rather than writing large functions that do many things, we write small functions that do one thing well and combine them to achieve our goals.

If you're familiar with the pipe operator (|>), function composition is a related concept but goes a step further - instead of just chaining function calls, we create entirely new functions by combining existing ones.

Understanding Function Composition

Why Use Function Composition?

Before we dive into the "how", let's understand the "why". Imagine you're making a sandwich:

You could write one big function that does everything (get bread, add mayo, add lettuce, add tomato, etc.)
Or you could write small functions for each step and combine them

The second approach is function composition, and it's better because:

Each function is simple and easy to test
You can reuse functions (maybe use "add mayo" in other recipes)
It's easier to understand what each part does
You can easily change or rearrange steps

What is Function Composition?

Think of function composition like a factory assembly line: one function takes an input and produces an output, which becomes the input for the next function. For example, if we have a function that doubles a number and another that adds 1, we can combine them to create a new function that does both operations in sequence.

In Elixir, we can achieve this in several ways:

defmodule CompositionBasics do
  def double(x), do: x * 2
  def increment(x), do: x + 1

  # Manual composition
  def double_then_increment(x) do
    increment(double(x))
  end

  # Using the pipe operator
  def double_then_increment_piped(x) do
    x |> double() |> increment()
  end

  # Creating a new function by combining two existing functions
  # This might look complex at first, but it's just saying:
  # "make a new function that first applies g, then applies f"
  # The dot notation (f.) is used to call anonymous functions
  def compose(f, g) do
    fn x -> f.(g.(x)) end
  end
end

Testing in IEx:

iex> CompositionBasics.double_then_increment(5)
11

iex> CompositionBasics.double_then_increment_piped(5)
11

iex> # Create a new function by composing increment and double
iex> composed = CompositionBasics.compose(&CompositionBasics.increment/1, &CompositionBasics.double/1)
#Function<...>

iex> # Now we can use our composed function
iex> composed.(5)  # Same as: increment(double(5)) = increment(10) = 11
11

Basic Composition Techniques

Using Anonymous Functions

Let's start with the simplest form of composition. Anonymous functions (functions without names) are perfect for creating small, one-time-use functions:

defmodule SimpleComposition do
  def add(x, y), do: x + y
  def multiply(x, y), do: x * y

  # Create a function that combines two operations:
  # 1. First add 10
  # 2. Then multiply by 2
  # So compose_math_ops().(5) would be: (5 + 10) * 2 = 30
  def compose_math_ops do
    fn x ->
      x
      |> add(10)
      |> multiply(2)
    end
  end

  # Create a pipeline that applies a list of operations in order
  # Each operation is applied to the result of the previous one
  def create_pipeline(operations) do
    fn initial_value ->
      # Start with initial_value, apply each operation in sequence
      Enum.reduce(operations, initial_value, fn operation, acc ->
        operation.(acc)
      end)
    end
  end
end

Testing in IEx:

iex> math_pipeline = SimpleComposition.compose_math_ops()
#Function<...>

iex> math_pipeline.(5)
30

iex> operations = [
       &(&1 + 5),
       &(&1 * 2),
       &(&1 - 3)
]
[#Function<...>, #Function<...>, #Function<...>]

iex> pipeline = SimpleComposition.create_pipeline(operations)
#Function<...>

iex> pipeline.(10)
27

Function Capture and Composition

The capture operator (&) is Elixir's shorthand for creating anonymous functions. It might look strange at first, but it's just a concise way to reference functions:

defmodule CaptureComposition do
  def process_string(string) do
    transformations = [
      &String.trim/1,
      &String.downcase/1,
      &String.replace(&1, " ", "_"),  # &1 refers to the first argument
      &("prefix_" <> &1)                 # <> is the string concatenation operator
    ]

    Enum.reduce(transformations, string, fn f, acc -> f.(acc) end)
  end

  # Composing with different arities
  def compose_validators(validators) do
    fn value ->
      # reduce_while stops iteration when it receives {:halt, value}
      Enum.reduce_while(validators, {:ok, value}, fn validator, {:ok, val} ->
        case validator.(val) do
          {:ok, _} = result -> {:cont, result}
          {:error, _} = error -> {:halt, error}
        end
      end)
    end
  end
end

Testing in IEx:

iex> CaptureComposition.process_string("  Hello World  ")
"prefix_hello_world"

iex> validators = [
  fn x -> if is_binary(x), do: {:ok, x}, else: {:error, "not a string"} end,
  fn x -> if String.length(x) > 2, do: {:ok, x}, else: {:error, "too short"} end,
  fn x -> if String.match?(x, ~r/^[a-z]+$/), do: {:ok, x}, else: {:error, "invalid chars"} end
]

iex> validator = CaptureComposition.compose_validators(validators)
#Function<...>

iex> validator.("hello")
{:ok, "hello"}

iex> validator.("hi")
{:error, "too short"}

iex> validator.("Hello")
{:error, "invalid chars"}

Higher-Order Functions

A higher-order function is simply a function that either takes other functions as arguments or returns a function. Don't let the name intimidate you - you've probably already used them with Enum.map!

defmodule HigherOrder do
  # Function that returns a multiplier function
  def multiplier(factor) do
    fn x -> x * factor end
  end

  # Function that returns a filter function
  def create_filter(predicate) do
    fn list -> Enum.filter(list, predicate) end
  end

  # Function that composes two unary functions
  def compose(f, g) do
    fn x -> f.(g.(x)) end
  end

  # Composes multiple functions in a right-to-left sequence
  # This follows the standard mathematical definition: (f ∘ g ∘ h)(x) = f(g(h(x)))
  # For a list like [f, g, h], the rightmost function (h) is applied first
  # We reverse the list so Enum.reduce applies functions in correct order: h, then g, then f
  def compose_all(functions) do
    fn x ->
      functions
      |> Enum.reverse()
      |> Enum.reduce(x, fn f, acc -> f.(acc) end)
    end
  end

  # Composition for functions that return {:ok, value} or {:error, reason}
  def compose_result(f, g) do
    fn x ->
      case g.(x) do
        {:ok, result} -> f.(result)
        error -> error
      end
    end
  end
end

Testing in IEx:

iex> times_three = HigherOrder.multiplier(3)
#Function<...>

iex> times_three.(7)
21

iex> positive_filter = HigherOrder.create_filter(&(&1 > 0))
#Function<...>

iex> positive_filter.([-2, -1, 0, 1, 2, 3])
[1, 2, 3]

iex> add_one = &(&1 + 1)
#Function<...>

iex> double = &(&1 * 2)
#Function<...>

iex> composed = HigherOrder.compose(add_one, double)
#Function<...>

iex> composed.(5)
11

# Note: this is right-to-left composition: add_one(double(sub_3(10))) = add_one(double(7)) = add_one(14) = 15
iex> pipeline = HigherOrder.compose_all([add_one, double, &(&1 - 3)])
#Function<...>

iex> pipeline.(10)
15

Composition Order: Pipeline vs. Mathematical

You might have noticed that SimpleComposition.create_pipeline and HigherOrder.compose_all compose a list of functions in different orders:

create_pipeline([f, g, h]) creates a left-to-right pipeline: h(g(f(x))). This is intuitive and reads like the pipe operator.
compose_all([f, g, h]) creates a right-to-left composition: f(g(h(x))). This follows the traditional mathematical definition of function composition.

Both patterns are useful. The key is to be consistent and understand which order your composition function uses.

Partial Application and Currying

Sometimes we want to "pre-fill" some arguments of a function and create a new function with fewer arguments. This is called partial application. Currying is a related concept where a function that takes multiple arguments is transformed into a series of functions that each take one argument:

defmodule PartialApplication do
  # Manual currying
  def curry_add do
    # Returns a function that returns another function
    fn a -> fn b -> a + b end end
  end

  # Generic curry for 2-arity functions
  # Transforms a function that takes 2 arguments into nested functions
  def curry2(fun) do
    fn a -> fn b -> fun.(a, b) end end
  end

  # Partial application using closures
  def partial(fun, arg1) do
    fn arg2 -> fun.(arg1, arg2) end
  end

  # More practical example
  def configure_logger(level) do
    fn module, message ->
      IO.puts("[#{level}] #{module}: #{message}")
    end
  end

  # Create a validator that checks data against a set of rules
  # This is a practical example of creating customized functions
  def create_validator(rules) do
    fn data ->
      # Check each field against its rule
      # Pattern match on function arguments directly in the fn
      Enum.reduce(rules, {:ok, data}, fn
        {field, rule}, {:ok, data} ->
          case Map.get(data, field) do
            nil -> {:error, "#{field} is required"}
            value ->
              if rule.(value), do: {:ok, data}, else: {:error, "#{field} is invalid"}
          end
        _, error -> error  # If there's already an error, pass it through
      end)
    end
  end
end

Testing in IEx:

iex> curried_add = PartialApplication.curry_add()
#Function<...>

iex> add_five = curried_add.(5)
#Function<...>

iex> add_five.(3)
8

iex> info_logger = PartialApplication.configure_logger("INFO")
#Function<...>

iex> info_logger.("UserModule", "User logged in")
[INFO] UserModule: User logged in
:ok

iex> rules = %{
  name: &(String.length(&1) > 2),
  age: &(&1 >= 18)
}

iex> validator = PartialApplication.create_validator(rules)
#Function<...>

iex> validator.(%{name: "Alice", age: 25})
{:ok, %{age: 25, name: "Alice"}}

iex> validator.(%{name: "Bo", age: 20})
{:error, "name is invalid"}

Working with Results That Can Fail

In Elixir, it's common to use {:ok, value} and {:error, reason} tuples to represent operations that might fail. Here's how to compose functions that work with these patterns:

defmodule MonadicComposition do
  # Compose functions that return {:ok, value} or {:error, reason}
  # This pattern is common in Elixir for error handling

  # bind: if we have a successful result, apply the next function
  # if we have an error, skip the function and pass the error along
  def bind(result, fun) do
    case result do
      {:ok, value} -> fun.(value)
      error -> error
    end
  end

  # Compose multiple monadic functions
  def pipeline(initial, functions) do
    # Apply each function to the result, stopping on first error
    Enum.reduce(functions, {:ok, initial}, fn fun, acc ->
      bind(acc, fun)
    end)
  end

  # Example functions that might fail
  def parse_int(string) do
    case Integer.parse(string) do
      {int, ""} -> {:ok, int}  # Empty string means all input was parsed
      _ -> {:error, "Invalid integer"}
    end
  end

  def divide_by(number, divisor) do
    if divisor == 0 do
      {:error, "Division by zero"}
    else
      {:ok, number / divisor}
    end
  end

  def ensure_positive(number) do
    if number > 0 do
      {:ok, number}
    else
      {:error, "Number must be positive"}
    end
  end
end

Testing in IEx:

iex> # Using the MonadicComposition module functions

iex> {:ok, 10} |> MonadicComposition.bind(&MonadicComposition.divide_by(&1, 2)) |> MonadicComposition.bind(&MonadicComposition.ensure_positive/1)
{:ok, 5.0}

iex> {:ok, 10} |> MonadicComposition.bind(&MonadicComposition.divide_by(&1, 0)) |> MonadicComposition.bind(&MonadicComposition.ensure_positive/1)
{:error, "Division by zero"}

iex> MonadicComposition.pipeline("42", [
  &MonadicComposition.parse_int/1,
  &MonadicComposition.divide_by(&1, 2),
  &MonadicComposition.ensure_positive/1
])
{:ok, 21.0}

iex> MonadicComposition.pipeline("-10", [
  &MonadicComposition.parse_int/1,
  &MonadicComposition.ensure_positive/1
])
{:error, "Number must be positive"}

Real-World Examples

Data Processing Pipeline

defmodule DataPipeline do
  # Individual processing steps
  def normalize_text(text) do
    text
    |> String.trim()
    |> String.downcase()
  end

  def extract_words(text) do
    # ~r creates a regular expression, \W+ matches non-word characters
    String.split(text, ~r/\W+/, trim: true)
  end

  def filter_stopwords(words) do
    # ~w creates a list of words (strings)
    stopwords = ~w(the a an and or but in on at to for)
    Enum.reject(words, &(&1 in stopwords))
  end

  def count_frequencies(words) do
    Enum.frequencies(words)
  end

  # Compose a text analysis pipeline
  def analyze_text do
    fn text ->
      text
      |> normalize_text()
      |> extract_words()
      |> filter_stopwords()
      |> count_frequencies()
    end
  end

  # More complex: compose with configuration
  def create_analyzer(options \\ []) do
    # Keyword.get retrieves values from keyword lists with defaults
    min_length = Keyword.get(options, :min_word_length, 3)
    top_n = Keyword.get(options, :top_n, 10)

    fn text ->
      text
      |> normalize_text()
      |> extract_words()
      |> filter_stopwords()
      |> Enum.filter(&(String.length(&1) >= min_length))
      |> count_frequencies()
      # _ ignores the word, we only care about count for sorting
      |> Enum.sort_by(fn {_, count} -> count end, :desc)
      |> Enum.take(top_n)
    end
  end
end

Testing in IEx:

iex> text = "The quick brown fox jumps over the lazy dog. The dog was very lazy."

iex> analyzer = DataPipeline.analyze_text()
#Function<...>

iex> analyzer.(text)
%{
  "brown" => 1,
  "dog" => 2,
  "fox" => 1,
  "jumps" => 1,
  "lazy" => 2,
  "over" => 1,
  "quick" => 1,
  "very" => 1,
  "was" => 1
}

iex> custom_analyzer = DataPipeline.create_analyzer(min_word_length: 4, top_n: 5)
#Function<...>

iex> custom_analyzer.(text)
[
  {"lazy", 2},
  {"brown", 1},
  {"jumps", 1},
  {"over", 1},
  {"quick", 1}
]

Middleware Composition

defmodule Middleware do
  # Middleware pattern: each function transforms the conn (connection)
  def compose_middleware(middlewares) do
    fn conn ->
      Enum.reduce(middlewares, conn, fn middleware, acc ->
        middleware.(acc)
      end)
    end
  end

  # Example middlewares
  def logging_middleware(conn) do
    IO.puts("Request: #{conn.method} #{conn.path}")
    conn
  end

  def auth_middleware(conn) do
    if conn.headers["authorization"] do
      Map.put(conn, :authenticated, true)
    else
      conn
      |> Map.put(:status, 401)
      |> Map.put(:halted, true)
    end
  end

  def timing_middleware(conn) do
    # monotonic_time gives a timestamp for measuring elapsed time
    start_time = System.monotonic_time(:millisecond)
    Map.put(conn, :timing_start, start_time)
  end

  # Create a request pipeline
  def create_pipeline do
    compose_middleware([
      &logging_middleware/1,  # & captures a function reference, /1 means arity 1
      &timing_middleware/1,
      &auth_middleware/1
    ])
  end
end

Testing in IEx:

iex> conn = %{method: "GET", path: "/users", headers: %{}, status: 200, halted: false}

iex> pipeline = Middleware.create_pipeline()
#Function<...>

iex> pipeline.(conn)
Request: GET /users
%{
  halted: true,
  headers: %{},
  method: "GET",
  path: "/users",
  status: 401,
  timing_start: -576460751779  # Actual value will vary
}

iex> # The | operator updates specific fields in a map, keeping other fields unchanged
iex> auth_conn = %{conn | headers: %{"authorization" => "Bearer token"}}

iex> pipeline.(auth_conn)
Request: GET /users
%{
  authenticated: true,
  halted: false,
  headers: %{"authorization" => "Bearer token"},
  method: "GET",
  path: "/users",
  status: 200,
  timing_start: -576460751777  # Actual value will vary
}

Best Practices

1. Keep Functions Focused

Each function should do one thing well:

# Good: Each function has a single responsibility
def trim_whitespace(string), do: String.trim(string)
def lowercase(string), do: String.downcase(string)
def replace_spaces(string), do: String.replace(string, " ", "_")

# Less good: Function does too many things
def process_string(string) do
  string
  |> String.trim()
  |> String.downcase()
  |> String.replace(" ", "_")
end

2. Make Functions Composable

Design functions to work well in composition:

# Good: Pure function without side effects
def add_prefix(string, prefix), do: prefix <> string

# Less composable: Side effects break composition
def add_prefix_and_print(string, prefix) do
  result = prefix <> string
  IO.puts(result)
  result
end

3. Use Consistent Return Types

Functions that might fail should use consistent patterns:

# Good: Consistent error handling
def safe_divide(a, 0), do: {:error, "Division by zero"}
def safe_divide(a, b), do: {:ok, a / b}

def safe_sqrt(n) when n < 0, do: {:error, "Cannot take square root of negative"}
def safe_sqrt(n), do: {:ok, :math.sqrt(n)}

# Now they compose well
def calculate(a, b) do
  # 'with' chains operations that might fail
  # If any step returns an error, it short-circuits
  with {:ok, divided} <- safe_divide(a, b),
       {:ok, root} <- safe_sqrt(divided) do
    {:ok, root}
  end
end

4. Document Composition Intent

Make it clear how functions are meant to be composed:

defmodule Pipeline do
  # @moduledoc adds documentation to the module
  @moduledoc """
  Functions designed to be composed in a processing pipeline.
  Each function takes and returns a map with :data and :metadata keys.
  """

  def validate(%{data: data} = input) do
    # validation logic
    input
  end

  def transform(%{data: data} = input) do
    # transformation logic
    input
  end

  def enrich(%{data: data} = input) do
    # enrichment logic
    input
  end
end

Conclusion

Function composition is a fundamental technique in functional programming that enables you to build complex functionality from simple, reusable parts. In Elixir, we have multiple tools and patterns for composition:

Basic composition using anonymous functions and the pipe operator
Higher-order functions that return new functions
Partial application and currying techniques
Advanced patterns for error handling with {:ok, value} tuples
Real-world applications in data processing and middleware

Key takeaways:

Compose small, focused functions rather than writing large, complex ones
Use consistent return types to make composition easier
Leverage Elixir's pipe operator for readable left-to-right composition
Consider higher-order functions when you need to parameterize behavior
Apply composition patterns to solve real problems like data pipelines and middleware

By mastering function composition, you'll write more modular, testable, and maintainable Elixir code.

Next Steps

In the upcoming article, we'll begin exploring Advanced Pattern Matching:

Pattern Matching Fundamentals

Deep dive into pattern matching mechanics
Pattern matching in different contexts (case, cond, with)
Advanced matching techniques
Common patterns and anti-patterns

Pattern matching is one of Elixir's most distinctive features, and mastering it will unlock new ways to write expressive, efficient code.

Build a Cross-Platform Markdown Notes System with Syncthing, Neovim & Markor (Offline, Fast & Private)

João Paulo Abreu — Sat, 07 Jun 2025 11:41:50 +0000

A comprehensive guide to creating a unified, lightweight note-taking ecosystem using Syncthing, Neovim, and Markor

Introduction
System Overview
Desktop Setup (Linux)
Mobile Setup (Android)
Synchronization Configuration
Conclusion

TL;DR: Learn how to create a fast, offline-capable, Markdown-based notes system that syncs across Linux, Android, and tablets — using only free, open-source tools like Syncthing, Neovim, and Markor.

Introduction

In an era of proprietary note-taking applications that lock your data into specific formats and cloud services, many developers and power users seek a more flexible, future-proof solution. This guide presents a complete setup for a cross-platform markdown note-taking system that prioritizes:

Data ownership - your notes remain in plain markdown files
Cross-platform compatibility - seamless access from desktop, mobile, and tablet
Offline functionality - works without internet connectivity
Terminal-centric workflow - integrates with existing development tools
Zero vendor lock-in - portable to any system or application

The system combines the power of Neovim for desktop editing, Markor for mobile markdown editing, and Syncthing for decentralized synchronization, creating a robust ecosystem that adapts to your workflow rather than forcing you to adapt to it.

System Overview

Architecture Components

┌─────────────────┐    ┌─────────────────┐    ┌─────────────────┐
│   Desktop/PC    │    │     Tablet      │    │     Mobile      │
│                 │    │                 │    │                 │
│ • Neovim        │◄──►│ • Markor        │◄──►│ • Markor        │
│ • Syncthing     │    │ • Syncthing     │    │ • Syncthing     │
│ • Git (backup)  │    │                 │    │                 │
│ • Terminal      │    │                 │    │                 │
└─────────────────┘    └─────────────────┘    └─────────────────┘
        │                       │                       │
        └───────────────────────┼───────────────────────┘
                                │
                    ┌─────────────────┐
                    │ Shared Markdown │
                    │   File System   │
                    │                 │
                    │ ~/Notes/        │
                    │ ├── dev/        │
                    │ ├── personal/   │
                    │ ├── knowledge/  │
                    │ ├── projects/   │
                    │ ├── inbox/      │
                    │ └── archive/    │
                    └─────────────────┘

Key Features

Unified file structure across all devices
Real-time synchronization without cloud dependencies
Quick capture capabilities on mobile devices
Powerful search and organization tools
Git integration for version control and backup

Desktop Setup (Linux)

Prerequisites

This guide assumes you're using a Linux distribution with a package manager. Commands are shown for Arch-based systems (pacman), but can be adapted for other distributions.

Step 1: Install Required Packages

# Install core components
sudo pacman -S neovim git syncthing

# Optional: ripgrep for enhanced searching
sudo pacman -S ripgrep

Step 2: Create Directory Structure

# Create the main notes directory and subdirectories
mkdir -p ~/Notes/{dev,personal,knowledge,projects,inbox,archive}

# Verify structure
tree ~/Notes

Directory Purpose:

dev/ - Development notes, code snippets, tutorials
personal/ - Personal thoughts, diary entries, ideas
knowledge/ - Learning materials, research, reference
projects/ - Project-specific documentation
inbox/ - Quick captures, temporary notes
archive/ - Completed or obsolete notes

Step 3: Configure Syncthing

# Enable and start Syncthing service
systemctl --user enable syncthing
systemctl --user start syncthing

# Open web interface
firefox http://localhost:8384

Initial Syncthing Configuration:

Access the web interface at http://localhost:8384
Add your Notes folder by clicking "Add Folder"
Set Folder Path: /home/yourusername/Notes/
Set Folder Label: "Notes"

Step 4: Add Notes Folder to Syncthing

The Notes folder should already be added during initial configuration. If not:

Click "Add Folder" in the web interface
Folder Path: /home/yourusername/Notes/
Folder Label: "Notes"
Click "Save"

Mobile Setup (Android)

Step 1: Install Syncthing

Install Syncthing from Google Play Store or download the APK directly.

Step 2: Install Markdown Editor

Installing Markor

Since Markor is no longer available on Google Play Store:

Visit https://github.com/gsantner/markor/releases
Download the latest APK file
Enable "Install from unknown sources" in Android settings
Install the APK manually

Step 3: Configure Syncthing on Mobile

Open Syncthing app
Grant storage permissions
Note your Device ID for connecting to desktop

Step 4: Open Markor

Open Markor app
Grant storage permissions
Navigate to your Notes folder and start creating/editing markdown files

Synchronization Configuration

Connecting Devices

From Desktop to Mobile:

On Desktop: Open Syncthing web interface
Click "Add Device"
Option A: Scan QR code from mobile device
Option B: Enter Device ID manually
Give device a name (e.g., "Android Phone")
Click "Save"

From Mobile to Desktop:

On Mobile: Open Syncthing app
Tap "+" → "Add Device"
Option A: Scan QR code from desktop
Option B: Enter Desktop Device ID
Name the device (e.g., "Linux Desktop")
Tap "Save"

Sharing Folders

Desktop Side:

In Syncthing web interface, find "Notes" folder
Click folder icon → "Edit"
Go to "Sharing" tab
Select your mobile device
Click "Save"

Mobile Side:

Accept the folder share notification
Set Folder Path to your Notes folder location
Set Folder Type: "Send & Receive"
Tap "Save"

Verification

Create a test file on desktop and verify it appears on mobile device within seconds.

Conclusion

This markdown note-taking system provides a robust, future-proof solution for managing notes across multiple devices without vendor lock-in. The combination of Syncthing's decentralized synchronization, Neovim's powerful editing capabilities, and Markor's mobile-friendly interface creates a seamless workflow that adapts to your needs.

Key Benefits Achieved:

✅ Data Ownership - Your notes remain in standard markdown format\
✅ Cross-Platform Access - Seamless editing on desktop, tablet, and mobile\
✅ Offline Functionality - Works completely without internet\
✅ Terminal Integration - Fits naturally into developer workflows\
✅ Extensibility - Easy to customize and extend with scripts\
✅ No Vendor Lock-in - Portable to any system or application\
✅ Quick Capture - Instant note creation from any device

Next Steps:

Create your first notes to test the system
Develop a consistent naming convention for your files
Organize notes into appropriate folders as your collection grows
Set up regular backup routines if desired
Customize the system based on your specific needs

The beauty of this system lies in its simplicity and flexibility. As your needs evolve, you can easily adapt and extend the system without being constrained by the limitations of proprietary software. Your notes remain yours, in a format that will be readable decades from now, accessible from any device, and editable with any text editor.

Whether you're a developer documenting code, a student taking research notes, or a professional managing projects, this system provides the foundation for a lifetime of organized, accessible note-taking.

This guide represents a living document. As tools evolve and new solutions emerge, the principles of data ownership, cross-platform compatibility, and workflow integration remain constant guides for building sustainable knowledge management systems.

Scholar.nvim: A Sepia Theme for Academic Coding

João Paulo Abreu — Mon, 02 Jun 2025 07:55:26 +0000

Comfortable coding inspired by vintage manuscripts

Why I Created Scholar

As a developer who codes for long hours, I got tired of eye strain from typical dark themes with bright neon colors. Most themes are made for quick coding sessions, not the deep work that research and documentation require.

I needed something that encourages focus and comfort over flashiness.

The Solution: Academic Sepia

The inspiration came from the Readera reading app, which uses warm sepia tones that reduce eye strain during long reading sessions. I thought: why not apply this to coding?

Scholar.nvim brings the comfort of academic manuscripts to your Neovim setup.

Scholar's dual theme showcase

What Makes Scholar Different

Dual Themes

Light theme (primary) - great for daytime coding
Dark theme (companion) - same aesthetic for nighttime

Sepia Colors

Warm, paper-like backgrounds
Excellent readability without harsh contrast
Subtle syntax highlighting that doesn't distract

Modern Features

Full Treesitter and LSP support
Works with popular plugins
Highly customizable

Quick Setup

{
  "abreujp/scholar.nvim",
  priority = 1000,
  config = function()
    require("scholar").setup()

    vim.o.background = "light"  -- or "dark"
    vim.cmd("colorscheme scholar")
  end,
}

Perfect For

Long coding sessions
Academic and research work
Documentation writing
Presentations and teaching
Anyone who wants less eye strain

Why Light Themes?

I know dark themes are popular, but light themes have advantages:

Better for extended reading
Less visual distraction
Professional appearance
Natural for academic work

Scholar's light theme isn't just inverted dark - it's carefully designed for comfort.

Try It Out

Repository: https://github.com/abreujp/scholar.nvim

Scholar includes documentation, examples, and active support. Whether you're writing algorithms, documentation, or just want a more comfortable coding experience, give it a try.

Do you use light or dark themes? What's your experience with eye strain during long coding sessions?

DEV Community: João Paulo Abreu

Learning Elixir: Error Handling Basics

Table of Contents

Introduction

The Ok/Error Tuple Pattern

The Core Convention

Why Tagged Tuples?

Standard Library Examples

Returning Results from Functions

Basic Function Patterns

Validation Functions

Enriching Error Reasons

Handling Results at the Call Site

Using case

Pattern Matching in Function Clauses

Extracting Values Safely

Chaining Operations with with

Basic with Usage

with and Custom Error Handling

Mixing Different Result Shapes

The Bang Convention

Functions with ! Suffix

When to Use Each

Practical Patterns

A Complete Service Layer

Collecting Multiple Errors

Working with Lists of Results

Best Practices

Conclusion

Further Reading

Next Steps

Learning Elixir: Ranges

Table of Contents

Introduction

Understanding How Ranges Work

The Internal Structure

Inclusivity

Empty Ranges

Creating and Working with Range Syntax

Basic Range Syntax

Ranges with Steps

Using Range.new/2 and Range.new/3

The Full-Slice Range

Range Enumeration Patterns

Working with Enum Functions

Using Ranges in Comprehensions

Streaming with Ranges

Lazy Evaluation and Memory Efficiency

Understanding Lazy Evaluation

Memory Comparison

Practical Lazy Evaluation Examples

Using Ranges for Slicing and Pattern Matching

Slicing Collections with Ranges

String Slicing

Pattern Matching with Ranges

Using Ranges in Function Guards

Performance Characteristics

Understanding Range Efficiency

Working Efficiently with Ranges

Memory Considerations

Applications in Data Processing

Iteration Patterns

Common Algorithms

Data Generation

Conclusion

Further Reading

Next Steps

Learning Elixir: Binaries and Bitstrings

Table of Contents

Introduction

Understanding Binaries and Bitstrings

Fundamental Concepts

Understanding Bitstring Syntax

Basic Syntax Patterns

Bit Patterns and Storage

Handling Overflow and Truncation

Complex Concatenations

Reading IEx Output

Size Functions and Inspection

Memory Representation and Efficiency