Skip to content
Tutorials Center
My learning

Topics

Lesson 16 of 48 ยท Enumerables and Data Processing

The Enum Module

Learn the Elixir Enum module: map, filter, reduce, sort, group_by, zip, chunk_every, frequencies and more, how eager evaluation works and when to use Stream.

Almost every program spends its time working on collections: lists of users, maps of settings, ranges of numbers. In Elixir the toolbox for this is the Enum module. It has over a hundred functions, and a handful of them (map, filter, reduce, sort, group_by) cover most daily needs. They replace the loops you would write in other languages and combine well with the pipe operator.

Enum works on anything that is enumerable: lists, maps, ranges, keyword lists, and anything that implements the Enumerable protocol. All Enum functions are eager: they go through the whole collection immediately and return a result (usually a list). The next lessons cover the lazy alternative.

Elixir does not run on this site, so the Elixir examples are read-only. The JavaScript TryIts reproduce the same results with array methods. They are stand-ins, not Elixir.

Transforming and filtering

Enum.map/2 applies a function to each element and returns a list of the results. Enum.filter/2 keeps the elements for which the function returns a truthy value; Enum.reject/2 does the opposite.

ELIXIR
Enum.map([1, 2, 3], fn n -> n * n end)          # [1, 4, 9]
Enum.map([1, 2, 3], &(&1 * 2))                  # [2, 4, 6]  (capture syntax)
Enum.filter(1..10, fn n -> rem(n, 3) == 0 end)  # [3, 6, 9]
Enum.reject(1..10, &(rem(&1, 2) == 0))          # [1, 3, 5, 7, 9]

When the function is named, capture it: Enum.map(names, &String.upcase/1). A map is enumerated as {key, value} tuples, so you can destructure them in the function head:

ELIXIR
prices = %{apple: 3, pear: 5, plum: 2}
Enum.map(prices, fn {name, price} -> {name, price * 2} end)
# [apple: 6, pear: 10, plum: 4]   (a list of tuples)

Note that map on a map returns a list of tuples. To get a map back, use Map.new/2 or Enum.into/2:

ELIXIR
Map.new(prices, fn {k, v} -> {k, v * 2} end)    # %{apple: 6, pear: 10, plum: 4}
JS map, filter and reject

Press Run (or Ctrl + Enter) to see the console output here.

No output.

Folding with reduce

Enum.reduce/3 is the general tool: it walks the collection and carries an accumulator. You give it the starting value and a function fn element, acc -> new_acc end. Note the argument order: the element comes first, the accumulator second.

ELIXIR
Enum.reduce([3, 5, 2], 0, fn n, acc -> acc + n end)     # 10

Enum.reduce(["a", "bb", "a"], %{}, fn word, acc ->
  Map.update(acc, word, 1, fn count -> count + 1 end)
end)
# %{"a" => 2, "bb" => 1}

Many functions are shortcuts over reduce: Enum.sum/1, Enum.count/1, Enum.max/1, Enum.min/1, Enum.product/1. If a built-in does what you need, prefer it. Without an initial value, Enum.reduce/2 uses the first element as the accumulator (and fails on an empty collection).

Counting, finding and testing

ELIXIR
Enum.count([1, 2, 3, 4], &(&1 > 2))       # 2
Enum.find([4, 7, 10], &(&1 > 5))          # 7
Enum.find_index([4, 7, 10], &(&1 > 5))    # 1
Enum.any?([1, 3, 4], &(rem(&1, 2) == 0))  # true
Enum.all?([2, 4, 5], &(rem(&1, 2) == 0))  # false
Enum.member?(1..5, 3)                     # true
Enum.max([4, 9, 2])                       # 9
Enum.min_by(["pear", "fig", "banana"], &String.length/1)   # "fig"

Enum.find/2 returns nil when nothing matches (you can pass a default as the third argument). any? and all? stop early once the answer is known.

The Enum workhorses

map Transform every element.
filter Keep what passes a test.
reduce Fold many values into one.
sort Put elements in order.

Most pipelines are just these four.

1 / 2

Sorting

Enum.sort/1 sorts by Elixir's standard term ordering. Pass :desc or :asc, or a comparison function. Enum.sort_by/2 sorts by a key you compute:

ELIXIR
Enum.sort([3, 1, 2])                          # [1, 2, 3]
Enum.sort([3, 1, 2], :desc)                   # [3, 2, 1]
Enum.sort_by(["pear", "fig", "banana"], &String.length/1)
# ["fig", "pear", "banana"]
Enum.sort_by(users, & &1.age, :desc)

The sort is stable: elements with equal keys keep their original order. If you pass a function to sort/2, use <= or >= (not <), or equal elements may swap. Enum.reverse/1, Enum.uniq/1, Enum.take/2, Enum.drop/2, Enum.at/2 and Enum.slice/3 round out the basics.

Grouping, zipping and chunking

Enum.group_by/2 builds a map of key to list of elements. Enum.frequencies/1 counts equal elements. Enum.zip/2 pairs elements from two collections (stopping at the shorter one), and Enum.chunk_every/2 cuts a list into pieces:

ELIXIR
words = ["apple", "avocado", "banana", "blueberry", "cherry"]

Enum.group_by(words, &String.first/1)
# %{"a" => ["apple", "avocado"], "b" => ["banana", "blueberry"], "c" => ["cherry"]}

Enum.frequencies(["x", "y", "x", "x"])      # %{"x" => 3, "y" => 1}
Enum.zip([1, 2, 3], [:a, :b, :c])           # [{1, :a}, {2, :b}, {3, :c}]
Enum.unzip([{1, :a}, {2, :b}])              # {[1, 2], [:a, :b]}
Enum.chunk_every([1, 2, 3, 4, 5], 2)        # [[1, 2], [3, 4], [5]]
Enum.with_index(["a", "b"])                 # [{"a", 0}, {"b", 1}]
Enum.flat_map([1, 2], fn n -> [n, n * 10] end)  # [1, 10, 2, 20]
Enum.split_with(1..6, &(&1 > 4))            # {[5, 6], [1, 2, 3, 4]}
JS group_by, frequencies, zip and chunk

Press Run (or Ctrl + Enter) to see the console output here.

No output.

A realistic pipeline

Here is a small report: given orders, find the total revenue per customer, largest first, top two.

ELIXIR
orders = [
  %{customer: "ana", total: 30},
  %{customer: "ben", total: 12},
  %{customer: "ana", total: 25},
  %{customer: "cho", total: 40},
  %{customer: "ben", total: 50}
]

orders
|> Enum.group_by(& &1.customer, & &1.total)
|> Enum.map(fn {name, totals} -> {name, Enum.sum(totals)} end)
|> Enum.sort_by(fn {_name, sum} -> sum end, :desc)
|> Enum.take(2)
# [{"ben", 62}, {"ana", 55}]

group_by/3 takes a key function and a value function, so totals is already a list of numbers. Each step produces a plain collection for the next, which is exactly what makes Enum pipeline friendly.

JS Revenue per customer

Press Run (or Ctrl + Enter) to see the console output here.

No output.

Eager evaluation and its cost

Because every Enum call finishes before the next starts, a pipeline of five Enum steps builds four intermediate lists:

ELIXIR
1..1_000_000
|> Enum.map(&(&1 * 3))
|> Enum.filter(&(rem(&1, 2) == 0))
|> Enum.take(5)

This creates a million-element list, then a half-million-element list, only to keep five items. That is fine for small data and wasteful for large or infinite data. When you only need part of a large source, switch the same pipeline to Stream (the lazy processing lesson shows how), or use Enum.reduce_while/3 to stop early. Also remember that Enum.at/2, Enum.count/1 and Enum.reverse/1 on a list walk the list, since lists are linked.

You can also convert results into another collection with Enum.into/2, for example Enum.into(pairs, %{}). Comprehensions with for, covered next in Comprehensions with for, are an alternative way to express map-and-filter.

Check your understanding

Quick check ยท 4 questions

of 4 answered You scored / 4 ยท perfect!

  1. 1. What does Enum.map/2 return when called on a map such as %{a: 1, b: 2}?

    A map is enumerated as {key, value} tuples, and map/2 returns a list of results. Use Map.new/2 or Enum.into/2 to build a map back.
  2. 2. In Enum.reduce(list, 0, fn x, acc -> ... end), which parameter is the accumulator?

    The function receives the current element first and the accumulator second, and must return the new accumulator.
  3. 3. What does Enum.frequencies(["a", "b", "a"]) return?

    frequencies/1 returns a map from each distinct element to the number of times it appears.
  4. 4. What is the main drawback of long Enum pipelines on very large collections?

    Enum is eager, so every step finishes before the next one starts. Stream processes elements lazily and avoids the intermediate collections.

Summary

  • Enum works on all enumerables (lists, maps, ranges, keyword lists) and is eager.
  • map, filter, reject, reduce, sort, sort_by, group_by, zip, chunk_every, frequencies, find and any?/all? handle most tasks.
  • reduce/3 takes fn element, acc -> new_acc end and an initial accumulator.
  • Mapping a map gives a list of tuples; use Map.new/2 or Enum.into/2 to get a map back.
  • Long eager pipelines create intermediate collections; use Stream for large or infinite sources.

Next: Comprehensions with for.