Enumerable is a module in the Ruby standard library. Classes that include it have to define an instance method called each, which yields the elements of the collection in succession. Once the iterator is defined and Enumerable is mixed in, the class now supports all sorts of collection-related behavior. Also, keep in mind, that although Enumerable adds common functionality to each of the collection classes that includes it, each of them actually overrides some of the methods.
class MyArray
include Enumerable
def each
# yield elements of the collection
end
end
You can query which methods Enumerable provides by sending the messageinstance_methods to it and passing the false argument so you get only methods defined in the module itself.
irb(main):001:0> Enumerable.instance_methods(false)
In order to understand Enumerable at a deeper level, let’s write a few of its methods while trying to cover as many operations as posible.
Methods for Querying
Some Enumerable methods return information about the collection other than the elements themselves. Some return either true or false if one or more element matches certain criteria.
#include?
Returns true if the item yielded to the block is equal the argument passed, falseotherwise.
def include?(value)
self.each { |item| return true if item == value }
return false
end
# (1..5).include?(2)
# => true
This works just fine for Arrays but if we were querying a Hash, we would need to adjust for the fact that when you iterate through a Hash with each it yields back one key/value pair at a time (two-element arrays). The Hash#include? method checks for key inclusion
#any?
Returns true if any element meets a specified criteria, false otherwise.
def any?
return self.length >= 1 unless block_given?
self.each do |element|
return true if yield(element)
end
return false
end
# => (1..5).any? { |n| n > 3 }
# => true
#count
Returns the count of elements based on a criteria passed as argument or a block, if given.
def count(value=nil)
counter = 0
self.each do |element|
if value
counter += 1 if element == value
elsif block_given?
counter += 1 if yield(element)
else
counter += 1
end
end
warn("warning: given block not used") if value && block_given?
return counter
end
# (1..5).count { |value| value > 3 }
# => 2
#tally
Counts the ocurrences of each element. Returning a Hash with the collection’s elements as keys and corresponding counts as values.
def tally
tally = Hash.new(0)
self.each { |element| tally[element] += 1 }
return tally
end
# [1, 2, 2, 2, 3, 3, 4].tally
# => {1=>1, 2=>3, 3=>2, 4=>1}
Methods for Searching and Filtering
It’s common to want to filter a collection of objects based on a selection criteria. We’ll look at several facilities for filtering and searching collections. All of them expect a code block, where you difine your selection criteria (your tests for inclusion or exclusion).
#find aliased as #detect
Returns the first element in the collection for which the code block returns true. If no code block is provided, it returns an instance of Enumerator.
def find
return self.enum_for( __method__ ) unless block_given?
self.each { |element| return element if yield(element) }
return nil
end
alias :detect :find
# (1..5).find {|value| value > 2}
# => 3
#find_all aliased as #select
Returns an Array containing all the elements of the original collection that matched the criteria in the code block. If no matching elements are found, it returns an empty collection. Also, if no code block is provided, it returns an instance of Enumerator.
def find_all
return self.enum_for( __method__ ) unless block_given?
matches = []
self.each do |element|
matches << element if yield(element)
end
return matches
end
alias :select :find_all
# (1..9).find_all {|value| value % 3 == 0 }
# => [3, 6, 9]
#find_index
Returns the index of the first element that meets the specified criteria, or nil if no element matches the criteria. It returns an instance of Enumerator if neither a code block nor an argument are provided.
For this method to work, make sure your #each implementation returns anEnumerator when no code block is provided. This will allow us to chain methods, as in .each.with_index.
def find_index(value=nil)
return self.enum_for( __method__ ) unless value || block_given?
self.each.with_index do |element, index|
if value
return index if element == value
else
return index if yield(element)
end
end
return nil
end
# (1..5).find_index(2)
# => 1
#group_by
When given a code block, it returns a Hash. For each unique value returned by the block, the results hash gets a key; the value for that key is an Array of all the elements of the collection for which the block returned that value. If no code block is given, it returns an instance of Enumerator.
def group_by
return self.enum_for( __method__ ) unless block_given?
groups = Hash.new([])
self.each do |element|
groups[yield(element)] << element
end
return groups
end
# colors = [{group: 'primary'}, {group: 'secondary'}, {group: 'primary'}]
# colors.group_by { |value| value[:group] }
# => {"primary"=>[{:group=>"primary"}, {:group=>"primary"}], "secondary"=>[{:group=>"secondary"}]}
#map aliased as #collect
Returns an Array when given a block. Returns and Enumerator otherwise. The returned array is always the same size as the original collection. Its elements are the result of calling the code block on each element in the original object.
def map
return self.enum_for( __method__ ) unless block_given?
collection = []
self.each { |element| collection << yield(element) }
return collection
end
alias :collect :map
# (1..5).map { |value| value * value }
# => [1, 4, 9, 16, 25]
#inject aliased as #reduce
Works by initializing an accumulator object, performs a calculation on each iteration and reset the accumulator to the result of that calculation. Returns the return value from the last block call.
def inject(operand=0)
accumulator = operand
self.each do |element|
accumulator = yield(accumulator, element)
end
return accumulator
end
alias :reduce :inject
# (1..5).inject { |sum, value| sum + value }
# => 15
We’ve gotten to know Enumerable in a more detailed way and it will better positioned us to handle everyday programming as we’ll use the enumeration-related facilities of the language virtually every time we write a Ruby program.
Top comments (3)
I've only just started wrapping my head around enumerable. This is a great article, thank you🙏
Thank you! I'm really glad it helps.
Nice article @rmontas !!