Programs made of functions
In an object-oriented language, code is organised around objects: data bundled with the methods that change it. Elixir has no objects. Data is plain and immutable, and code is a collection of functions that take data in and return new data out. Functions are grouped into modules, which are simply named collections of functions with no state of their own.
That might sound restrictive, but it gives you something valuable: a function's result depends only on its arguments (apart from deliberate side effects such as printing or sending a message). You can understand, test and reuse a function on its own, without first setting up the object it belongs to.
Elixir functions also bring two features that change how you write everyday code. The first is that a function can have several clauses, each with its own pattern, so the shape of the input chooses which code runs, exactly like the case expressions from the last lesson. The second is the pipe operator |>, which lets you write a chain of transformations in the order they happen, the way you would describe them aloud. By the end of this lesson both will feel natural.
Anonymous functions and captures
An anonymous function is created with fn ... -> ... end and stored like any other value. Call it with a dot before the parentheses:
add = fn a, b -> a + b end
IO.puts(add.(2, 3))
# Several clauses, chosen by pattern, like a case expression.
describe = fn
0 -> "zero"
n when n < 0 -> "negative"
_ -> "positive"
end
IO.puts(describe.(-4))
# A closure remembers the values it could see when it was created.
make_greeter = fn greeting -> fn name -> "#{greeting}, #{name}!" end end
hola = make_greeter.("Hola")
IO.puts(hola.("Lucía"))
# The capture operator: &Module.function/arity names an existing function...
upcase = &String.upcase/1
IO.puts(upcase.("quiet"))
# ...and &(...) builds a small function, with &1, &2 for its arguments.
triple = &(&1 * 3)
IO.inspect(Enum.map([1, 2, 3], triple))
IO.inspect(Enum.map(["a", "b"], &String.duplicate(&1, 3)))It prints:
5
negative
Hola, Lucía!
QUIET
[3, 6, 9]
["aaa", "bbb"]The dot in add.(2, 3) is not decoration: it tells the reader, and the compiler, that add is a variable holding a function, not a named function called add. make_greeter returns a function that closes over greeting; hola remembers "Hola" long after make_greeter finished.
The capture operator & has two uses. &String.upcase/1 turns a named function into a value you can pass around. &(&1 * 3) is shorthand for fn x -> x * 3 end, where &1 is the first argument, &2 the second, and so on. Use the short form for tiny functions; once it has more than one operator or argument, a full fn is easier to read.
Named functions in modules
Named functions live in modules. def defines a public function, defp a private one, visible only inside its module. A function is identified by its name and its arity (number of arguments), written name/arity: String.split/1 and String.split/2 are two different functions that happen to share a name.
defmodule Shipping do
@moduledoc "Shipping costs for a small online shop, in cents."
@free_threshold 50_00
@rates %{standard: 4_99, express: 12_99}
@doc "The shipping cost for an order total, in cents."
def cost(total, speed \\ :standard)
def cost(total, :standard) when total >= @free_threshold, do: 0
def cost(_total, speed) when is_map_key(@rates, speed), do: @rates[speed]
def cost(_total, speed) do
raise ArgumentError, "unknown shipping speed: #{inspect(speed)}"
end
def format(cents) when is_integer(cents) and cents >= 0 do
"#{div(cents, 100)}.#{pad(rem(cents, 100))}"
end
defp pad(n) when n < 10, do: "0#{n}"
defp pad(n), do: Integer.to_string(n)
end
IO.puts(Shipping.format(Shipping.cost(23_50)))
IO.puts(Shipping.format(Shipping.cost(80_00)))
IO.puts(Shipping.format(Shipping.cost(80_00, :express)))
IO.puts(Shipping.format(5))
IO.inspect(function_exported?(Shipping, :pad, 1))It prints:
4.99
0.00
12.99
0.05
falseThere is a lot packed into that module:
- Module attributes such as
@free_thresholdare constants fixed at compile time.@moduledocand@docare special attributes holding documentation, whichh Shipping.costiniexwill show you. def cost(total, speed \\ :standard)is a function head: no body, just a declaration thatspeeddefaults to:standard. When a function with defaults has several clauses, Elixir wants the defaults declared once, in a head like this. Defaults actually create two functions,cost/1andcost/2.- The clauses are tried in order. Free standard shipping for orders of 50.00 or more must come before the general clause, or it would never be chosen.
- Guards (
when ...) refine a pattern with a condition. Only a fixed set of expressions is allowed in guards (comparisons, arithmetic, type checks such asis_integer/1,is_map_key/2,map_size/1and a few more), because guards must be fast and free of side effects. If a guard raises an error, the clause simply does not match. - The
do:form (def pad(n), do: ...) is a one-line shorthand fordo ... end. - Money is kept in integer cents, avoiding the floating-point surprise from the previous lesson.
pad/1is private, sofunction_exported?/3reports that the outside world cannot call it.
Elixir naming conventions carry meaning. A function ending in ? returns a boolean (String.contains?/2). A function ending in ! raises an exception on failure instead of returning {:error, reason}, and usually has a sibling without the ! (File.read/1 and File.read!/1). Functions that are allowed in guards begin with is_.
Inside a module you will also see four directives that control how names and code are brought in. alias MyApp.Accounts.User lets you write User instead of the full name. import Integer, only: [is_even: 1] makes functions callable without their module prefix; use it sparingly and always with only:. require Logger is needed before using a module's macros. And use GenServer runs code from another module to inject definitions into yours; you will use it for GenServers and tests.
Module names can contain dots, as in Shop.Cart or MyApp.Accounts.User, and projects use them to group related modules by feature. The dots are only part of the name: there is no runtime hierarchy, Shop.Cart is not "inside" Shop in any way that affects behaviour, and either can exist without the other. A module defined inside another one (defmodule Shop do defmodule Cart do ... end end) simply gets the combined name Shop.Cart and an automatic alias within the outer module.
Recursion instead of loops
Elixir has no while loop and no for loop that changes a counter, because there is nothing to change. Repetition is expressed with recursion: a function that calls itself on a smaller problem, with a clause for the smallest problem of all. Lists, built as a head and a tail, fit this perfectly.
defmodule MyList do
# Body recursion: the addition happens after the recursive call returns.
def sum([]), do: 0
def sum([head | tail]), do: head + sum(tail)
# Tail recursion: the recursive call is the last thing the function does,
# and the running total travels along in an accumulator.
def sum_tail(list), do: sum_tail(list, 0)
defp sum_tail([], acc), do: acc
defp sum_tail([head | tail], acc), do: sum_tail(tail, acc + head)
# Run-length encoding: "aaabcc" becomes [{"a", 3}, {"b", 1}, {"c", 2}].
def encode(string), do: string |> String.graphemes() |> encode([])
defp encode([], acc), do: Enum.reverse(acc)
defp encode([g | rest], [{g, n} | acc]), do: encode(rest, [{g, n + 1} | acc])
defp encode([g | rest], acc), do: encode(rest, [{g, 1} | acc])
end
IO.puts(MyList.sum([4, 8, 15, 16, 23, 42]))
IO.puts(MyList.sum_tail(Enum.to_list(1..1_000_000)))
IO.inspect(MyList.encode("aaabccddddé"))It prints:
108
500000500000
[{"a", 3}, {"b", 1}, {"c", 2}, {"d", 4}, {"é", 1}]sum/1 reads like a definition: the sum of an empty list is 0, and the sum of a non-empty list is its head plus the sum of its tail. Each call waits for the next to return, so the BEAM keeps a stack frame per element until it reaches the end.
sum_tail/2 carries the running total in an accumulator. Its recursive call is the very last thing it does (a tail call), so the BEAM reuses the current frame instead of adding one: tail recursion runs in constant stack space, the functional equivalent of a loop. The public sum_tail/1 hides the accumulator from callers, a pattern you will see everywhere.
encode/2 shows how much a pattern can say. The second clause, encode([g | rest], [{g, n} | acc]), uses the variable g twice: it only matches when the next grapheme is the same one the accumulator is currently counting. Building the result backwards and reversing it once at the end is the standard idiom, because adding to the front of a list is cheap and adding to the end is not.
In practice you will write explicit recursion less often than you might expect: the Enum module, the subject of the next lesson, already contains map, filter, reduce and dozens more, all built on this idea. But knowing how they work lets you write the cases they do not cover.
The pipe operator
Here is a small text-processing task written the nested way:
Enum.take(Enum.sort_by(Enum.frequencies(String.split(String.downcase(text))), fn {_, n} -> -n end), 3)You have to read it from the inside out. The pipe operator x |> f(y) means f(x, y): it passes the value on its left as the first argument of the call on its right. With it, the same computation reads in the order it happens:
text = """
The river runs past the mill and the mill turns, and the miller
sings to the river while the river runs on to the sea.
"""
text
|> String.downcase()
|> String.split(~r/[^\p{L}]+/u, trim: true)
|> Enum.frequencies()
|> Enum.sort_by(fn {word, count} -> {-count, word} end)
|> Enum.take(4)
|> IO.inspect()
# then/2 pipes into a function that does not take the value first;
# tap/2 runs a side effect and passes the value through unchanged.
21
|> tap(&IO.puts("starting with #{&1}"))
|> Kernel.*(2)
|> then(&Integer.pow(2, &1))
|> IO.puts()It prints:
[{"the", 7}, {"river", 3}, {"and", 2}, {"mill", 2}]
starting with 21
4398046511104The text uses a heredoc, a multi-line string between triple quotes. ~r/.../u is a regular expression sigil; \p{L} matches any letter in any script, so the split works for words in Yoruba or Vietnamese as well as English. Sorting by {-count, word} puts higher counts first and breaks ties alphabetically, because tuples compare element by element.
The second pipeline shows the escape hatches. Kernel.*(2) is the multiplication operator called as an ordinary function, so 21 |> Kernel.*(2) is 21 * 2. then/2 lets you pipe into a position other than the first (here the exponent of Integer.pow/2), and tap/2 lets you look at a value mid-pipeline without changing it.
This is why Elixir libraries put the data being transformed as the first argument of their functions: String.split(string, pattern), Map.put(map, key, value), Enum.map(list, fun). Follow the same convention in your own modules, and your functions will slot into pipelines naturally.
Note
When a pipeline misbehaves, add |> dbg() at the end. The dbg/2 macro (added in Elixir 1.14) prints the code of each step of the pipeline next to its result; started as iex --dbg pry, the shell instead pauses at that point so you can inspect the variables. Remove it before you commit; the formatter and code review will remind you if you forget.
How Elixir developers write functions
Knowing the syntax is half the job; the other half is the set of habits that make Elixir code easy to read six months later. These are the ones you will see in well-kept codebases.
Let the shape of the input choose the clause. When the decision depends on what the arguments look like, write several clauses rather than one function with a case inside. When it depends on something computed partway through, use case there. Both are pattern matching; the question is only where the decision naturally lives.
Be assertive. If your program cannot do anything sensible when a configuration file is missing, write {:ok, text} = File.read("config.json") and let the MatchError stop it with a clear message, instead of threading an error value through ten functions that cannot handle it either. Match on the values you expect, and let unexpected ones fail loudly. You will see in the Professional lessons how supervisors turn this habit, "let it crash", into a reliability strategy.
Write the data first, and keep functions small. Put the main data as the first argument so the function fits in a pipeline, give it a name that says what it returns, and split it when it grows past what fits on a screen. Private helpers (defp) are free, and good names in them act as documentation.
Document with examples that run. A @doc can contain examples written as iex sessions:
@doc """
Formats an amount of cents as a decimal string.
iex> Shipping.format(1250)
"12.50"
iex> Shipping.format(7)
"0.07"
"""
def format(cents) when is_integer(cents) and cents >= 0 do
...
endAdd the line doctest Shipping to a test module, and mix test runs every one of those examples and checks the results, so the documentation cannot drift away from the code. Doctests are one of the reasons Elixir library documentation is unusually trustworthy. mix docs, from the ex_doc package, turns the same text into the HTML pages you see on HexDocs.
Let the formatter decide the layout. mix format rewrites your files into the community's standard style: two-space indentation, parentheses on calls, line breaks in long pipelines. Teams run it on save in the editor and check it in continuous integration with mix format --check-formatted, so code review never needs to discuss whitespace.
Common mistakes
Misconception
"The pipe puts the value in the last argument." It always fills the first argument. "a-b" |> String.split("-") is String.split("a-b", "-"). If the value belongs elsewhere, use then/2 or end the pipeline and call the function normally.
Misconception
"add(1, 2) should work when add holds a function." Without the dot, Elixir looks for a named function add/2. Anonymous functions are always called as add.(1, 2).
Misconception
"Clause order does not matter, the most specific clause wins." Elixir tries clauses strictly from top to bottom. A general clause placed first hides every clause below it; the compiler (and, in Elixir 1.20, the type checker) will often warn that a later clause can never match, so read those warnings.
Misconception
"Tail recursion is always better." For long or unbounded loops (a server's main loop, a million-element list) a tail call keeps memory flat. But body recursion like sum/1 is often just as fast on the BEAM for ordinary list sizes and avoids a final Enum.reverse. Write the clearer version first, and reach for the standard library before either.
Exercises
1. Functions, modules and the pipe operator
Warm-upComputationalAfter square = fn x -> x * x end, which expression returns 16?
2. Functions, modules and the pipe operator
Warm-upComputationalWhat does this line print?
"a,b,c" |> String.split(",") |> Enum.join("-") |> IO.puts()
3. Functions, modules and the pipe operator
CoreComputationalWhat does this program print?
defmodule Grade do
def letter(score) when score >= 90, do: "A"
def letter(score) when score >= 75, do: "B"
def letter(_), do: "C"
end
IO.puts(Grade.letter(75) <> Grade.letter(89) <> Grade.letter(91))
4. Functions, modules and the pipe operator
CoreHumanHow many public functions (distinct name/arity pairs) does this module define?
defmodule M do
def greet(name, greeting \\ "Hi"), do: "#{greeting}, #{name}"
def greet(), do: greet("you")
end
5. Functions, modules and the pipe operator
CoreComputationalWhat does IO.inspect(Enum.map([1, 2, 3], &(&1 * &1 + 1))) print?
6. Functions, modules and the pipe operator
StretchComputationalWhat does this program print?
defmodule Count do
def down(0, acc), do: [0 | acc]
def down(n, acc), do: down(n - 1, [n | acc])
end
IO.inspect(Count.down(3, []))
7. Functions, modules and the pipe operator
StretchHumanWhich of these definitions of a list-length function is tail recursive?
Further reading and resources
- Getting started: Anonymous functionsThe official chapter on
fn, closures and the capture operator. - Getting started: Modules and functionsNamed functions, guards, default arguments and function capturing.
- Naming conventionsWhat trailing
?and!mean, and other naming rules the community follows. - Writing documentationHow
@moduledoc,@docand doctests work. - The Kernel moduleThe functions and macros available everywhere, including
|>,then/2,tap/2and the guards.