Enumerating Enumerable: Enumerable#first

by Joey deVilla on August 15, 2008

Enumerating Enumerable

Welcome to another installment of Enumerating Enumerable, my series of articles in I attempt to do a better job of documenting Ruby’s Enumerable module than Ruby-Doc.org. In this installment, I cover the first method.

In case you missed any of the previous articles, they’re listed and linked below:

  1. all?
  2. any?
  3. collect / map
  4. count
  5. cycle
  6. detect / find
  7. drop
  8. drop_while
  9. each_cons
  10. each_slice
  11. each_with_index
  12. entries / to_a
  13. find_all / select
  14. find_index

Enumerable#first Quick Summary

Graphic representing the "first" method in Ruby's "Enumerable" module

In the simplest possible terms What are the first n items in the collection?
Ruby version 1.8 and 1.9
Expects An optional integer n that specifies the first n items of the collection to return. If this integer is not given, n is 1 by default.
Returns If first is applied to a collection containing m elements:

  • The first item in the collection, if m > 0 and no argument n is provided.
  • An array containing the first n items in the collection, if m > 0 and an argument n is provided.
  • nil if the collection is empty and no argument n is provided.
  • The empty array [] if the collection is empty and an argument n is provided.
RubyDoc.org’s entry Enumerable#first

Enumerable#first and Arrays

When used on an array without an argument, first returns the first item in the array:

posts = ["First post!", "Second post!", "Third post!"]
=> ["First post!", "Second post!", "Third post!"]

# What's the first item in posts?
posts.first
=> "First post!"

# Here's the equivalent using array notation:
posts[0]
=> "First post!"

When used on an array with an integer argument n, first returns an array containing the first n items in the original array:

# What are the first 2 items in posts?
posts.first 2
=> ["First post!", "Second post!"]

# Note that when you provide an argument of 1,
# the result is still an array -- with just one element.
# If you want a scalar, don't use an argument.
posts.first 1
=> ["First post!"]

# Here's the equivalent using array slice notation:
posts[0..1]
=> ["First post!", "Second post!"]

posts[0...2]
=> ["First post!", "Second post!"]

When used on an empty array, first returns:

  • nil if no argument n is provided
  • The empty array, [], if an argument n is provided

[].first
=> nil

[].first 2
=> []

Enumerable#first and Hashes

In Ruby 1.8 and previous versions, hash order is seemingly arbitrary. Starting with Ruby 1.9, hashes retain the order in which they were defined, which makes the first method a little more applicable.

When used on a hash without an argument, first returns the first item in the hash as a two-element array, with the key as the first element and the corresponding value as the second element.

# Let's see what stages of partying our friends are in
party_stages = {"Alice" => :party_mineral,
                "Bob"   => :party_animal,
                "Carol" => :party_reptile,
                "Dave"  => :party_vegetable}
=> {"Alice"=>:party_mineral, "Bob"=>:party_animal, "Carol"=>:party_reptile, "Dave"=>:party_vegetable}

# Who's the first partier and what state is s/he in?
party_stages.first
=> ["Alice", :party_mineral]

When used on a hash with an integer argument n, first returns an array containing the first n items in the hash, with each item represented as a two-element array:

party_stages.first 2
=> [["Alice", :party_mineral], ["Bob", :party_animal]]

# Note that when you provide an argument of 1,
# the result is still an array -- with just one element.
# If you want a scalar, don't use an argument.
party_stages.first 1
=> [["Alice", :party_mineral]]

When used on an empty hash, first returns:

  • nil if no argument n is provided
  • The empty array, [], if an argument n is provided

{}.first
=> nil

{}.first 2
=> []

Leave a Comment

Previous post:

Next post: