collections

Here we are the third installment of Enumerating Enumerable, my attempt to do a better job of documenting Ruby’s Enumerable module than RubyDoc.org does. In this installment, I cover Enumerable#collect and its syntactic sugar twin (and the one I prefer), Enumerable#map.

In case you missed the earlier installments, they’re listed (and linked) below:

  1. all?
  2. any?

Enumerable#collect/Enumerable#map Quick Summary

Graphic representation of Ruby\'s \"Enumerable#collect / Enumerable#map\" methods

In the simplest possible terms Create a new array by performing some operation on every item in the given collection. collect and map are synonyms — you can use either. I personally prefer map as it’s shorter and makes sense if you think of the method as being like functional mapping.
Ruby version 1.8 and 1.9
Expects A block containing the criteria. This block is optional, but you’re likely to use one in most cases.
Returns An array made up of items created by performing some operation on the given collection.
RubyDoc.org’s entry Enumerable#collect / Enumerable#map

Enumerable#collect/Enumerable#map and Arrays

When used on an array and a block is provided, collect/map passes each item to the block, where the operation in the block is performed on the item and the result is then added to the result array. Note the the result array has the same number of elements as the given array.

[1, 2, 3, 4].map {|number| number ** 2}
=> [1, 4, 9, 16]

["Aqua", "Bat", "Super", "Wonder Wo"].map {|adjective| adjective + "man"}
=> ["Aquaman", "Batman", "Superman", "Wonder Woman"]

When the block is omitted, collect/map uses this implied block: {|item| item}, which means when applied on an array without a block, collect/map is the identity function — the resulting array is the same as the given array.

[1, 2, 3, 4].map
=> [1, 2, 3, 4]

["Aqua", "Bat", "Super", "Wonder Wo"].map
=> ["Aqua", "Bat", "Super", "Wonder Wo"]

Enumerable#collect/Enumerable#map and Hashes

When used on a hash and a block is provided, collect and map pass each key/value pair in the hash to the block, which you can “catch” as either:

  1. A two-element array, with the key as element 0 and its corresponding value as element 1, or
  2. Two separate items, with the key as the first item and its corresponding value as the second item.

Each key/value pair is passed to the block, where the operation in the block is performed on the item and the result is then added to the result array. Note the the result array has the same number of elements as the given array.

burgers = {"Big Mac" => 300, "Whopper with cheese" => 450, "Wendy's Double with cheese" => 320}

# What if I had just half a burger?
burgers.map {|burger| burger[1] / 2}
=> [160, 150, 225]

burgers.map {|sandwich, calories| calories / 2}
=> [160, 150, 225]

burgers.map {|burger| "Have a tasty #{burger[0]}!"}
=> ["Have a tasty Wendy's Double with cheese!", "Have a tasty Big Mac!",
 "Have a tasty Whopper with cheese!"]

burgers.map {|sandwich, calories| "Have a tasty #{sandwich}!"}
=> ["Have a tasty Wendy's Double with cheese!", "Have a tasty Big Mac!",
 "Have a tasty Whopper with cheese!"]

burgers.map {|sandwich, calories| ["Half a #{sandwich}", calories / 2]}
=> [["Half a Wendy's Double with cheese", 160], ["Half a Big Mac", 150],
 ["Half a Whopper with cheese", 225]]

When the block is omitted, collect/map uses this implied block: {|item| item}, which means when applied on an hash without a block, collect/map returns an array containing a set of two-item arrays, one for each key/value pair in the hash. For each two-item array, item 0 is the key and item 1 is the corresponding value.

burgers = {"Big Mac" => 300, "Whopper with cheese" => 450, "Wendy's Double with cheese" => 320}

burgers.map
=> [["Wendy's Double with cheese", 320], ["Big Mac", 300], ["Whopper with cheese", 450]]

Special Case: Using Enumerable#collect/Enumerable#map on Empty Arrays and Hashes

When applied to an empty array or hash, with or without a block, collect and map always return an empty array.

# Let's try it with an empty array
[].map
=> []

[].map {|item| item * 2}
=> []

# Now let's try it with an empty hash
{}.map
=> []

{}.map {|sandwich, calories| "Have a tasty #{sandwich}!"}
=> []

{ 9 comments }

Enumerating Enumerable: Enumerable#any?

by Joey deVilla on June 24, 2008

Welcome to the second installment of Enumerating Enumerable, my project to do a better job of documenting Ruby’s Enumerable module than RubyDoc.org. This installment will cover Enumerable#any?, which I like to think of as Enumerable.all?‘s more easy-going cousin (I covered Enumerable.all? in the previous installment).

Enumerable#any? Quick Summary

Graphic representing Ruby\'s Enumerable#any? method

In the simplest possible terms Do any of the items in the collection meet the given criteria?
Ruby version 1.8 and 1.9
Expects A block containing the criteria. This block is optional, but you’re likely to use one in most cases.
Returns true if any of the items in the collection meet the given criteria.

false if none of the items in the collection does not meet the given criteria.

RubyDoc.org’s entry Enumerable#any?

Enumerable#any? and Arrays

When used on an array and a block is provided, any? passes each item to the block. If the block returns true for any item during this process, any? returns true; otherwise, it returns false.

# "Fromage de Montagne de Savoie" is the longest-named cheese in this list
# at a whopping 29 characters
cheeses = ["feta", "cheddar", "stilton", "camembert", "mozzarella", "Fromage de Montagne de Savoie"]

cheeses.any? {|cheese| cheese.length >= 25}
=> true

cheeses.any? {|cheese| cheese.length >= 35}
=> false

When the block is omitted, any? uses this implied block: {|item| item}. Since everything in Ruby evaluates to true except for false and nil, using any? without a block is effectively a test to see if any of the items in the collection evaluate to true (or conversely, if all the values in the array evaluate to false or nil).

cheeses.any?
=> true

cheeses = [false, nil]
=> [false, nil]

cheeses.any?
=> false

# Remember that in Ruby, everything except for false and nil evaluates to true:
cheeses << 0
=> [false, nil, 0]

>> cheeses.any?
=> true

Enumerable#any? and Hashes

When used on a hash and a block is provided, any? passes each key/value pair in the hash to the block, which you can “catch” as either:

  1. A two-element array, with the key as element 0 and its corresponding value as element 1, or
  2. Two separate items, with the key as the first item and its corresponding value as the second item.

If the block returns true for any item during this process, any? returns true; otherwise, it returns false.

# Here's a hash where for each key/value pair, the key is a programming language and
# the corresponding value is the year when that language was first released
# The keys range in value from "Javascript" to "Ruby", and the values range from
# 1987 to 1996
languages = {"Javascript" => 1996, "PHP" => 1994, "Perl" => 1987, "Python" => 1991, "Ruby" => 1993}

languages.any? {|language| language[0] < "Pascal"}
=> true

languages.any? {|language, year_created| language < "Pascal"}
=> true

languages.any? {|language| language[0] < "Fortran"}
=> false

languages.any? {|language, year_created| language < "Fortran"}
=> false

languages.any? {|language| language[0] >= "Basic" and language[1] <= 1995}
=> true

languages.any? {|language, year_created| language >= "Basic" and year_created <= 1995}
=> true

languages.any? {|language| language[0] >= "Basic" and language[1] <= 1985}
=> false

languages.any? {|language, year_created| language >= "Basic" and year_created <= 1985}
=> false

Using any? without a block on a hash is meaningless, as it will always return true. When the block is omitted, any? uses this implied block: {|item| item}. In the case of a hash, item will always be a two-element array, which means that it will never evaluate as false nor nil.

And yes, even this hash, when run through any?, will still return true:

{false => false, nil => nil}.any?
=> true

Special Case: Using Enumerable#any? on Empty Arrays and Hashes

When applied to an empty array or hash, with or without a block, any? always returns false. That’s because with an empty collection, there are no values to process and return a true value.

Let’s look at the case of empty arrays:

cheeses = []
=> []

cheeses.any? {|cheese| cheese.length >= 25}
=> false

cheeses.any?
=> false

# Let's try applying "any?" to a non-empty array
# using a block that ALWAYS returns true:
["Gruyere"].any? {|cheese| true}
=> true

# ...but watch what happens when we try the same thing
# with an EMPTY array!
[].any? {|cheese| true}
=> false

…now let’s look at the case of empty hashes:

languages = {}
=> {}

languages.any? {|language| language[0] < "Pascal"}
=> false

languages.any? {|language, year_created| language < "Pascal"}
=> false

languages.any?
=> false

# Let's try applying "any?" to a non-empty hash
# using a block that ALWAYS returns true:
{"Lisp" => 1959}.any? {|language| true}
=> true

# ...but watch what happens when we try the same thing
# with an EMPTY hash!
{}.any? {|language| true}
=> false

{ 14 comments }