Welcome to the third installment in my series of articles on the methods of Ruby’s Enumerable module. This series is meant to address some of the shortcomings in the official documentation

In case you missed the first two, here they are:

1. all? and any?
2. collect/map

In this installment, I’m going to cover the find method. This is a particularly interesting one because it covers detect/find’s little-talked about optional parameter.

detect, a.k.a. find

detect and find are synonyms — you can use either. I personally prefer find, as it’s shorter and a good match with a related method, find_all. I also just think that “find” conveys the method’s functionality much better than “detect”.

Using detect/find with Arrays

When used on an array without an argument, detect/find passes each item from the collection to the block and…

• If the current item causes the block to return a value that doesn’t evaluate to false, detect/find stops going through collection and returns the item.
• If no item in the collection causes the block to return a value that doesn’t evaluate to false, detect/find returns nil.

classic_rock_bands = ["AC/DC", "Black Sabbath", "Queen", "Scorpions"]

classic_rock_bands.find {|band| band > "Led Zeppelin"}
=> "Queen"

classic_rock_bands.find {|band| band > "ZZ Top"}
=> nil

Using the optional argument is a topic big enough to merit its own section, which appears later in this article.

Using detect/find with Hashes

With hashes, detect/find 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.

detect/find is one of those methods of Enumerable that works a little oddly since:

• The result it returns depends on the order of the collection
• We’re always told that hashes don’t really any order (there seems to be one, but it’s shrouded in mystery).

metacritic_ratings = {"Juno" => 81, "American Gangster" => 76, \
                      "Golden Compass" => 51, "Meet the Spartans" => 9}
=> {"American Gangster"=>76, "Golden Compass"=>51, "Juno"=>81, "Meet the Spartans"=>9}

metacritic_ratings.find {|metacritic_rating| metacritic_rating[1] > 80}
=> ["Juno", 81]

metacritic_ratings.find {|film, rating| rating > 80}
=> ["Juno", 81]

metacritic_ratings.find {|film, rating| rating > 90}
=> nil

Using detect/find with the Optional Argument

detect/find’s optional argument lets you specify a proc or lambda whose return value will be the result in cases where no object in the collection matches the criteria.

(Unfortunately, a complete discussion of procs and lambdas is beyond the scope of this article. I highly recommend looking at Eli Bendersky’s very informative article, Understanding Ruby blocks, Procs and methods.)

I think that the optional argument is best explained through examples…

classic_rock_bands = ["AC/DC", "Black Sabbath", "Queen", "Scorpions"]

# Let's define a proc that will simply return the default band's name
# for cases where none of the bands in the array meets the criteria.
default_band = Proc.new {"ABBA"}

# Procs are objects, so using a proc's name alone isn't sufficient
to invoke its code -- doing so will simply return the proc object.
default_band
=> #<Proc:0x00553f34@(irb):31>
# (The actual value will be different for you, but you get the idea.)

# To call a proc, you have to use its "call" method:
default_band.call
=> "ABBA"

# detect/find calls the "call" method of the object you provide as the argument
# if no item in the collection matches the criteria in the block.
classic_rock_bands.find(default_band) {|band| band > "Led Zeppelin"}
=> "Queen"

classic_rock_bands.find(default_band) {|band| band > "ZZ Top"}
=> "ABBA"

# Let's try something a little fancier, and use a lambda this time.
# The differences between procs and lambdas are very fine -- I suggest
# you check Eli Bendersky's article for those differences.
random_band = lambda do
	fallback_bands = ["Britney Spears", "Christina Aguilera", "Ashlee Simpson"]
	fallback_bands[rand(fallback_bands.size)]
end

# Let's give it a try...
classic_rock_bands.find(random_band) {|band| band > "ZZ Top"}
=> "Britney Spears"
>> classic_rock_bands.find(random_band) {|band| band > "ZZ Top"}
=> "Ashlee Simpson"
>> classic_rock_bands.find(random_band) {|band| band > "ZZ Top"}
=> "Christina Aguilera"

To see a “real” application of detect/find's optional argument, see this Ruby Quiz problem.

In the last article in this series covering the methods in Ruby’s Enumerable module, I covered all? and any?. In this installment, I’ll look at the collect method, a.k.a. the map method.

collect, a.k.a. map

• In plain language: Create an array by performing some operation on every item in the given collection.
• Ruby.Doc.org’s entry: Enumerable#collect / Enumerable#map
• Expects: A block containing the operation (it’s optional, but you’re likely to use one most of the time).
• Returns: An array made up of items created by performing some operation on the given collection.

collect and map are synonyms — you can use either. I personally prefer map as it’s shorter and makes more sense: I view the operation as using a function to map a collection to an array.

Using collect/map with 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"]

Using collect/map with Hashes

When used on a hash and a block is provided, collect/map 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.

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 collect/map on Empty Arrays and Hashes

When applied to an empty array or hash, with or without a block, all? always returns true.

[].map
=> []

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

{}.map
=> []

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

In the Next Installment…

…the detect (a.k.a. find) method.