Array#each vs. Array#map

Array#each executes the given block for each element of the array, then returns the array itself.

Array#map also executes the given block for each element of the array, but returns a new array whose values are the return values of each iteration of the block.

Example: assume you have an array defined thusly:

arr = ["tokyo", "london", "rio"]

Then try executing each:

arr.each { |element| element.capitalize }
# => ["tokyo", "london", "rio"]

Note the return value is simply the same array. The code inside the each block gets executed, but the calculated values are not returned; and as the code has no side effects, this example performs no useful work.

In contrast, calling the array's map method returns a new array whose elements are the return values of each round of executing the map block:

arr.map { |element| element.capitalize }
# => ["Tokyo", "London", "Rio"]

The side effects are the same which is adding some confusion to your reverse engineering.

Yes, both iterate over the array (actually, over anything that mixes in Enumerable) but map will return an Array composed of the block results while each will just return the original Array.

The return value of each is just the original array and is rarely used in Ruby code but map is one of the most important functional tools.

What map does is return an array which contains the results of the block or named method that is passed. For example:

    2.2.3 :001 > [:how, :now, :brown, :cow].map &:to_s
 => ["how", "now", "brown", "cow"]

In this case I didn't pass a block but just a Symbol, however class Symbol objects have a to_proc method which will result in:

[:how.to_s, :now.to_s, ...]

BTW, you may be having a hard time finding the documentation because map is a method in Enumerable while each (the one method required by the Enumerable module) is a method in Array.

As a trivia note: the map implementation is based on each.

Here's a quick demo of how map differs from each

a = ["a", "b", "c"];
#Array.map
p a.map {|item| "map_" + item}
#prints ["map_a", "map_b", "map_c"]

#Array.each
p a.each {|item| "map_" + item}
#prints ["a", "b", "c"]

You see that map returns ["map_a", "map_b", "map_c"] whereas each just iterates but returns the original array: ["a", "b", "c"].

So each is used for processing an array and map is used to do something with a processed array.