Skip to content
LumenaryAcademy
Foundations 60 min

Collections and Enumerable

Arrays, hashes, ranges and sets, and the Enumerable module that gives every collection the same rich vocabulary of transforming, filtering, grouping and searching.

Code tested · 4AI-draftedAwaiting review by a computer scientist
MotivationH

Saying what, not how

Here is a task: from a list of sales, find the total revenue per seller, best seller first. In a language without good collection tools you would write a loop, a dictionary of running totals, an if to start each total at zero, and then a sort. In Ruby you write:

ruby
sales.group_by { it[:seller] }
     .transform_values { |rows| rows.sum { |s| s[:kg] * s[:price] } }
     .sort_by { |_, total| -total }

Each step names what it does: group, total, sort. There is no index variable to get wrong and no empty-collection special case. This style is possible because Ruby's collections share one big vocabulary, the Enumerable module, and because blocks make it cheap to pass a little behaviour to each step.

This lesson covers the four collections you will use daily (arrays, hashes, ranges and sets), then Enumerable itself, then enumerators, which let you work with sequences too long, or too slow, to build all at once.

Worked examplesH

Arrays, hashes and sets

ruby
# Arrays: ordered, any mix of objects, indexed from 0 (negative from the end).
cities = %w[Accra Quito Hanoi Tbilisi Perth]
p cities[0], cities[-1], cities[1, 2], cities[1..], cities.first(2)
cities << "Lagos"
cities.push("Cusco").unshift("Oslo")
p cities.size, cities.shift, cities.pop, cities
p cities.include?("Hanoi"), cities.index("Hanoi"), cities.sort.first, cities.reverse.first
p [3, [1, [4, nil]], nil].flatten.compact, [1, 2, 2, 3, 3, 3].uniq, [1, 2, 3].rotate
p [1, 2, 3].zip(%w[a b c]), [1, 2].product([:x, :y]), (1..7).each_slice(3).to_a

first, *middle, last = [10, 20, 30, 40]
p first, middle, last

# Hashes: key => value, in insertion order.
capitals = { "Kenya" => "Nairobi", "Peru" => "Lima" }
capitals["Viet Nam"] = "Hanoi"
p capitals, capitals["Peru"], capitals["Chad"], capitals.fetch("Chad", "unknown")
p capitals.keys, capitals.size, capitals.key?("Kenya"), capitals.to_a.first

stock = { mangoes: 12, yams: 0, dates: 5 }
p stock.select { |_, n| n.positive? }, stock.transform_values { it * 2 }, stock.sum { |_, n| n }
p stock.min_by { |_, n| n }, stock.sort_by { |name, _| name }.to_h, stock.merge({ yams: 4, figs: 9 }) { |_, old, new| old + new }

order = { customer: { name: "Mele", address: { city: "Nukuʻalofa" } } }
p order.dig(:customer, :address, :city), order.dig(:customer, :phone, :mobile)

# Counting with a default value of 0.
counts = Hash.new(0)
"mississippi".each_char { |c| counts[c] += 1 }
p counts

# Sets: unique members, fast membership (a core class in Ruby 4.0).
seen = Set[1, 2, 3]
seen << 2 << 4
p seen, seen.include?(4), seen & Set[3, 4, 5], seen | Set[9]
text
"Accra"
"Perth"
["Quito", "Hanoi"]
["Quito", "Hanoi", "Tbilisi", "Perth"]
["Accra", "Quito"]
8
"Oslo"
"Cusco"
["Accra", "Quito", "Hanoi", "Tbilisi", "Perth", "Lagos"]
true
2
"Accra"
"Lagos"
[3, 1, 4]
[1, 2, 3]
[2, 3, 1]
[[1, "a"], [2, "b"], [3, "c"]]
[[1, :x], [1, :y], [2, :x], [2, :y]]
[[1, 2, 3], [4, 5, 6], [7]]
10
[20, 30]
40
{"Kenya" => "Nairobi", "Peru" => "Lima", "Viet Nam" => "Hanoi"}
"Lima"
nil
"unknown"
["Kenya", "Peru", "Viet Nam"]
3
true
["Kenya", "Nairobi"]
{mangoes: 12, dates: 5}
{mangoes: 24, yams: 0, dates: 10}
17
[:yams, 0]
{dates: 5, mangoes: 12, yams: 0}
{mangoes: 12, yams: 4, dates: 5, figs: 9}
"Nukuʻalofa"
nil
{"m" => 1, "i" => 4, "s" => 4, "p" => 2}
Set[1, 2, 3, 4]
true
Set[3, 4]
Set[1, 2, 3, 4, 9]

Arrays hold any objects in order. Indexing accepts negative positions (from the end), a start and a length (cities[1, 2]) or a range (cities[1..]). << and push add at the end, unshift at the front; pop and shift remove and return. Methods with no ! return new arrays and leave the receiver alone; sort!, uniq!, compact! and friends change it. The splat in first, *middle, last = … collects the elements in between.

Hashes map keys to values and remember insertion order. Reading a missing key with [] returns nil, which is often a silent bug, so fetch is the professional default when a key should exist: it raises KeyError, or returns the default you give it. dig follows a path through nested hashes (and arrays) and returns nil if any step is missing, which is ideal for data parsed from JSON. Hashes are enumerable too, yielding [key, value] pairs: select, min_by, sort_by and sum all work, and transform_values, to_h and merge (with a block that resolves conflicts) build new hashes. Hash.new(0) gives every missing key the default 0, which makes counting one line; use the block form Hash.new { |h, k| h[k] = [] } when the default is a mutable object, so each key gets its own. One protective detail: when you use a mutable string as a key, the hash stores a frozen copy of it, so changing the original string later cannot silently corrupt the hash. (We checked: after h[k] = 1 and then k << "!", the hash still had the key "amina" while k had become "amina!".) Other mutable keys, such as arrays, get no such protection, so do not mutate an object while it is a hash key.

Sets hold unique members with fast membership tests and the operators & (intersection), | (union) and - (difference). In Ruby 4.0 Set became a core class, implemented in C and available without a require. When you only need "have I seen this?", a set says so more clearly than a hash of true values.

Ranges, from the previous lesson, are enumerable as well: (1..10).sum, (1..7).each_slice(3).

ExplanationH

The Enumerable vocabulary

Array, Hash, Range, Set, and many library classes include the module Enumerable. Enumerable needs only one thing from a class, a method each that yields each element, and in return supplies more than fifty methods. Here is a tour on the market-stall data from the PHP course's equivalent lesson, written the Ruby way:

ruby
sales = [
  { seller: "Ngozi", item: "mangoes", kg: 12, price: 150 },
  { seller: "Diego", item: "potatoes", kg: 30, price: 45 },
  { seller: "Ngozi", item: "yams", kg: 8, price: 220 },
  { seller: "Leila", item: "dates", kg: 5, price: 600 },
  { seller: "Diego", item: "maize", kg: 20, price: 35 },
]

totals = sales.map { |s| s[:kg] * s[:price] }
p totals, totals.sum, totals.minmax

big, small = sales.partition { |s| s[:kg] * s[:price] >= 1750 }
p big.map { it[:item] }, small.map { it[:item] }

by_seller = sales.group_by { it[:seller] }.transform_values { |rows| rows.sum { |s| s[:kg] * s[:price] } }
p by_seller, by_seller.max_by { |_, total| total }
p by_seller.sort_by { |_, total| -total }

p sales.sum { it[:kg] }, sales.count { it[:price] > 100 }, sales.map { it[:seller] }.tally
p sales.sort_by { |s| [-s[:kg], s[:item]] }.map { it[:item] }
p sales.find { it[:price] > 200 }&.fetch(:item), sales.any? { it[:kg] > 25 }, sales.all? { it[:kg] > 1 }
p sales.filter_map { "#{it[:item]} (#{it[:kg]} kg)" if it[:kg] < 10 }
p sales.each_with_object(Hash.new { |h, k| h[k] = [] }) { |s, acc| acc[s[:seller]] << s[:item] }
p sales.map { it[:kg] }.reduce(:+), sales.map { it[:kg] }.each_cons(2).map { |a, b| b - a }
p sales.flat_map { [it[:seller], it[:item]] }.first(4), sales.map { it[:kg] }.take_while { it > 10 }
text
[1800, 1350, 1760, 3000, 700]
8610
[700, 3000]
["mangoes", "yams", "dates"]
["potatoes", "maize"]
{"Ngozi" => 3560, "Diego" => 2050, "Leila" => 3000}
["Ngozi", 3560]
[["Ngozi", 3560], ["Leila", 3000], ["Diego", 2050]]
75
3
{"Ngozi" => 2, "Diego" => 2, "Leila" => 1}
["potatoes", "maize", "mangoes", "yams", "dates"]
"yams"
true
true
["yams (8 kg)", "dates (5 kg)"]
{"Ngozi" => ["mangoes", "yams"], "Diego" => ["potatoes", "maize"], "Leila" => ["dates"]}
75
[18, -22, -3, 15]
["Ngozi", "mangoes", "Diego", "potatoes"]
[12, 30]

Grouped by purpose, the methods you will reach for most:

PurposeMethods
Transformmap, flat_map, filter_map (map, dropping nils), each_with_object, zip
Filterselect (alias filter), reject, partition (both halves at once), take_while, drop_while, uniq
Aggregatesum, count, tally (count each value), minmax, min_by, max_by, reduce (alias inject)
Group and ordergroup_by, sort_by, chunk_while, slice_when, each_slice, each_cons
Search and testfind (alias detect), find_index, any?, all?, none?, include?

Some notes from the output:

  • sort_by with an array key sorts by several criteria: [-s[:kg], s[:item]] means kilograms descending (negating a number reverses its order), then item name ascending.
  • find returns the first match or nil, so &.fetch(:item) guards against no match.
  • reduce(:+) folds the list with +; sum is clearer and faster for adding, and reduce with a block handles any other combination.
  • each_cons(2) yields overlapping pairs, perfect for differences between neighbours; each_slice(3) yields non-overlapping groups.
  • each_with_object threads one accumulator (here a hash of arrays) through the iteration, which is often clearer than reduce when the accumulator is a mutable object.

Reading a chain. Take the pipeline from the start of the lesson apart, using the output above. group_by { it[:seller] } produces a hash from each seller's name to the array of their rows. transform_values replaces each array with a number, the seller's revenue, giving {"Ngozi" => 3560, "Diego" => 2050, "Leila" => 3000}. Finally sort_by { |_, total| -total } turns the hash into an array of [name, total] pairs, highest first; the underscore names a block parameter you deliberately ignore. When a chain does not do what you expect, this is how to debug it: look at the shape after each step, either in irb or by inserting .tap { p it } between two steps. Long chains are written one step per line, with the dot at the start of each continuation line, so each step can be read, commented out or tapped on its own.

The habit to build: when you are about to write result = [], then each, then result << …, stop and look for the Enumerable method that already does it. Your code becomes shorter, and readers recognise the method name faster than they can read your loop.

Worked examplesH

Your own enumerable classes, and enumerators

ruby
# Any class with an each method can include Enumerable and get dozens of methods.
class Playlist
  include Enumerable

  Track = Data.define(:title, :seconds)

  def initialize(name)
    @name = name
    @tracks = []
  end

  def add(title, seconds)
    @tracks << Track.new(title:, seconds:)
    self
  end

  def each(&block)
    return enum_for(:each) unless block

    @tracks.each(&block)
    self
  end
end

list = Playlist.new("Evening")
  .add("Morning in Bamako", 245)
  .add("Rain on the Plaza", 221)
  .add("Night Ferry", 312)

p list.map(&:title), list.sum(&:seconds), list.max_by(&:seconds).title
p list.sort_by(&:seconds).map(&:title).first, list.select { it.seconds > 230 }.size, list.include?(list.first)
p list.each_with_index.map { |t, i| "#{i + 1}. #{t.title}" }

# An Enumerator can be stepped through by hand with next.
e = list.each
p e.next.title, e.next.title

# Enumerator.new builds a sequence on demand, even an infinite one; lazy keeps it on demand.
primes = Enumerator.new do |yielder|
  n = 2
  loop do
    yielder << n if (2..Integer.sqrt(n)).none? { n % it == 0 }
    n += 1
  end
end
p primes.take(10)
p primes.lazy.select { it % 10 == 3 }.map { it * it }.first(3)
p (1..Float::INFINITY).lazy.map { it**2 }.reject(&:even?).first(5)
text
["Morning in Bamako", "Rain on the Plaza", "Night Ferry"]
778
"Night Ferry"
"Rain on the Plaza"
2
true
["1. Morning in Bamako", "2. Rain on the Plaza", "3. Night Ferry"]
"Morning in Bamako"
"Rain on the Plaza"
[2, 3, 5, 7, 11, 13, 17, 19, 23, 29]
[9, 169, 529]
[1, 9, 25, 49, 81]

Including Enumerable. Playlist stores its tracks privately and defines each, which yields them. One line, include Enumerable, then gives it map, sum, max_by, sort_by, select, include?, first, each_with_index and the rest. (A mixin like this is the subject of the next lesson; Track = Data.define(:title, :seconds) defines a small immutable value class, which that lesson also covers.) Note that each returns an Enumerator when called without a block, the convention from the last lesson, which is what makes each_with_index.map and list.each (with no block) work. For sort, min and max without a block, the elements must be comparable with <=>; with _by versions you choose the key.

External iteration. Normally a collection drives the loop and calls your block (internal iteration). An Enumerator can be driven from outside instead: each next returns the following element. That is useful when you need to step through two sequences in step, or to pause in the middle.

Generators. Enumerator.new { |yielder| … } describes a sequence by writing a loop that pushes values into yielder. The loop can be infinite, as in primes, because it only runs as far as someone asks: take(10) asks for ten. Ruby implements this with a fiber, a lightweight coroutine you will meet again in the lesson on concurrency.

Lazy pipelines. Ordinarily, map and select each build a complete new array before the next step starts, which is impossible for an infinite sequence and wasteful for a huge one. After .lazy, each element flows through the whole pipeline one at a time, and work stops as soon as first(3) has its three results. Use lazy for infinite sequences, very large files (File.foreach(path).lazy) and expensive steps where you need only the first few results. For ordinary small arrays, plain eager methods are faster and simpler.

ComputationC

What collection operations cost, and what copies copy

Choosing the right collection matters as much as choosing the right method, because the costs differ by orders of magnitude on large data.

OperationCostNotes
array[i], array << x, array.popconstantArrays are contiguous; appending is amortised constant time
array.include?(x), array.index(x), findlinearLooks at elements one by one
array.insert(i, x), array.delete_at(i) in the middlelinearElements after i move
hash[key], hash[key] = v, set.include?(x)constant on averageHash tables; keys need sensible hash and eql? methods
sort, sort_byn log nsort_by computes each key once, so it is the faster choice for expensive keys

Three patterns follow from the table, and the program below shows them along with a subtlety about copying:

ruby
users = [
  { id: 7, name: "Ana", country: "BR" },
  { id: 3, name: "Bo", country: "SE" },
  { id: 12, name: "Chen", country: "TW" },
]

# Build an index once, then every lookup by id is a hash lookup instead of a scan.
by_id = users.to_h { [it[:id], it] }
p by_id[3][:name], by_id.keys

# Membership: a Set (or Hash) answers in constant time; Array#include? checks every element.
banned = Set["mallory", "trudy"]
p %w[bo trudy].map { "#{it}: #{banned.include?(it) ? 'refused' : 'welcome'}" }

# Batching: write ten records in groups of four.
(1..10).each_slice(4) { |batch| puts "insert #{batch.inspect}" }

# dup copies the outer array only: the inner arrays are shared.
original = [[1, 2], [3]]
copy = original.dup
copy << [4]
copy[0] << 99
p original, copy

# freeze is shallow too.
config = { "hosts" => ["a.example", "b.example"] }.freeze
begin
  config["port"] = 80
rescue FrozenError => e
  puts "FrozenError: #{e.message}"
end
config["hosts"] << "c.example"
p config
text
"Bo"
[7, 3, 12]
["bo: welcome", "trudy: refused"]
insert [1, 2, 3, 4]
insert [5, 6, 7, 8]
insert [9, 10]
[[1, 2, 99], [3]]
[[1, 2, 99], [3], [4]]
FrozenError: can't modify frozen Hash: {"hosts" => ["a.example", "b.example"]}
{"hosts" => ["a.example", "b.example", "c.example"]}
  • Index once, look up many times. If you will look up users by id repeatedly, to_h { [it[:id], it] } builds a hash in one pass. Searching the array with find each time is a linear scan per lookup; for thousands of lookups in thousands of rows, that difference is the difference between instant and minutes.
  • Use a Set or Hash for "is this one of those?". Checking each incoming name against a large array with include? scans the array every time.
  • Batch with each_slice when talking to databases or APIs: a few large requests are much faster than many small ones.

Copies are shallow. dup (and clone) copy the outer collection, but the elements are the same objects. Adding [4] to copy did not affect original, but pushing 99 into copy[0] changed the inner array that both share. Likewise, freeze stops the hash itself from changing (the FrozenError shows the hash's contents), but the array inside it can still grow. When you need a truly independent or truly immutable structure, copy or freeze each level, or build your data from immutable values in the first place: frozen strings, symbols, numbers and Data objects, which the next lesson introduces.

Common misconceptionsH

Common misunderstandings

Misconception

"Hash.new([]) gives each key its own empty array." It gives every missing key the same array object as default. h = Hash.new([]); h[:a] << 1 changes that shared default, so h[:b] now looks like [1] too, while h itself is still empty because << never assigned a key. Use Hash.new { |hash, key| hash[key] = [] }, which creates and stores a new array for each key.

Misconception

"map and each are interchangeable." each is for side effects and returns the original collection; map builds and returns a new array of the block's results. Using each and then wondering why the result did not change, or using map just to print and throwing the new array away, are both signs of choosing the wrong one.

Misconception

"Chaining many Enumerable methods is slow." Each step allocates an intermediate array, which matters only for very large collections in hot code. Readable chains are the default in professional Ruby. When profiling shows a chain is a bottleneck, combine steps (filter_map instead of select then map, sum with a block instead of map then sum) or use lazy for long sequences.

Misconception

"Modifying an array while iterating over it is fine." Adding or deleting elements of an array inside its own each gives confusing results, such as skipped elements. Build a new collection (reject, select), or use the in-place methods designed for it (reject!, delete_if, keep_if).

Exercises

Exercises

1. Collections and Enumerable

Warm-upComputational

What does this print?

p [1, 2, 3, 4].partition(&:even?)

2. Collections and Enumerable

Warm-upComputational

What does this print (Ruby 3.4 or later)?

p %w[a b a c b a].tally

3. Collections and Enumerable

CoreComputational

What does this print?

puts (1..10).select(&:even?).map { it * it }.sum

4. Collections and Enumerable

CoreComputational

What does this program print?

h = Hash.new([])
h[:x] << 1
p [h[:y], h.size]

5. Collections and Enumerable

CoreComputational

What does this print?

p (1..5).each_cons(2).map { |a, b| a * b }

6. Collections and Enumerable

StretchComputational

What does this program print?

a = [[0]]
b = a.dup
b[0] << 1
b << [2]
p a

7. Collections and Enumerable

CoreComputational

What does this print?

p (1..Float::INFINITY).lazy.map { it * 3 }.select(&:even?).first(3)

8. Collections and Enumerable

CoreHuman

A configuration hash must contain :api_key. Which read makes a missing key fail at once, with a message naming the key?

Choose one

Further reading and resources