each vs map in Ruby: what is the difference?

languages = ["python", "ruby", "php"]

languages.each { |l| puts l.capitalize }   # prints; returns the ORIGINAL array
languages.map  { |l| l.capitalize }        # ["Python", "Ruby", "Php"]

#The pattern to recognise

result = []
languages.each { |l| result << l.upcase }

That is map written the long way. Three lines become one:

result = languages.map(&:upcase)

Whenever you see each pushing into an accumulator array, it wants to be map.

#The &: shorthand

map(&:upcase) is shorthand for map { |x| x.upcase }. It works with any method that takes no arguments — &:to_i, &:strip, &:even?.

#Use each when there is nothing to build

users.each { |u| send_email(u) }

Here map would build an array of return values you do not want. That is misleading to read and pointless to allocate.

#The bang versions mutate

languages.map! { |l| l.upcase }   # changes languages in place, returns it

Reach for map! rarely. Returning a new collection keeps functions easier to reason about.