Module: Enumerable

Included in:
Array, Dir, Range, String, Struct
Defined in:
enum.c

Overview

The Enumerable mixin provides collection classes with several traversal and searching methods, and with the ability to sort. The class must provide a method each, which yields successive members of the collection. If Enumerable#max, #min, or #sort is used, the objects in the collection must also implement a meaningful <=> operator, as these methods rely on an ordering between members of the collection.

Instance Method Summary collapse

Instance Method Details

#all? {|obj| ... } ⇒ Boolean

Passes each element of the collection to the given block. The method returns true if the block never returns false or nil. If the block is not given, Ruby adds an implicit block of {|obj| obj} (that is all? will return true only if none of the collection members are false or nil.)

%w{ ant bear cat}.all? {|word| word.length >= 3}   #=> true
%w{ ant bear cat}.all? {|word| word.length >= 4}   #=> false
[ nil, true, 99 ].all?                             #=> false

Yields:

  • (obj)

Returns:

  • (Boolean) 


541
542
543
 
# File 'enum.c', line 541

static VALUE
enum_all(obj)
VALUE obj;

#any? {|obj| ... } ⇒ Boolean

Passes each element of the collection to the given block. The method returns true if the block ever returns a value other than false or nil. If the block is not given, Ruby adds an implicit block of {|obj| obj} (that is any? will return true if at least one of the collection members is not false or nil.

%w{ ant bear cat}.any? {|word| word.length >= 3}   #=> true
%w{ ant bear cat}.any? {|word| word.length >= 4}   #=> true
[ nil, true, 99 ].any?                             #=> true

Yields:

  • (obj)

Returns:

  • (Boolean) 


593
594
595
 
# File 'enum.c', line 593

static VALUE
enum_any(obj)
VALUE obj;

#collect {|obj| ... } ⇒ Array #map {|obj| ... } ⇒ Array

Returns a new array with the results of running block once for every element in enum.

(1..4).collect {|i| i*i }   #=> [1, 4, 9, 16]
(1..4).collect { "cat"  }   #=> ["cat", "cat", "cat", "cat"]

Overloads:

  • #collect {|obj| ... } ⇒ Array

    Yields:

    • (obj)

    Returns:

  • #map {|obj| ... } ⇒ Array

    Yields:

    • (obj)

    Returns:



224
225
226
 
# File 'enum.c', line 224

static VALUE
enum_collect(obj)
VALUE obj;

#detect(ifnone = nil) {|obj| ... } ⇒ Object? #find(ifnone = nil) {|obj| ... } ⇒ Object?

Passes each entry in enum to block. Returns the first for which block is not false. If no object matches, calls ifnone and returns its result when it is specified, or returns nil

(1..10).detect  {|i| i % 5 == 0 and i % 7 == 0 }   #=> nil
(1..100).detect {|i| i % 5 == 0 and i % 7 == 0 }   #=> 35

Overloads:

  • #detect(ifnone = nil) {|obj| ... } ⇒ Object?

    Yields:

    • (obj)

    Returns:

  • #find(ifnone = nil) {|obj| ... } ⇒ Object?

    Yields:

    • (obj)

    Returns:



107
108
109
 
# File 'enum.c', line 107

static VALUE
enum_find(argc, argv, obj)
int argc;

#each_with_index {|obj, i| ... } ⇒ Enumerator

Calls block with two arguments, the item and its index, for each item in enum.

hash = Hash.new
%w(cat dog wombat).each_with_index {|item, index|
  hash[item] = index
}
hash   #=> {"cat"=>0, "wombat"=>2, "dog"=>1}

Yields:

  • (obj, i)

Returns:

  • (Enumerator) 


806
807
808
 
# File 'enum.c', line 806

static VALUE
enum_each_with_index(obj)
VALUE obj;

#to_a ⇒ Array #entries ⇒ Array

Returns an array containing the items in enum.

(1..7).to_a                       #=> [1, 2, 3, 4, 5, 6, 7]
{ 'a'=>1, 'b'=>2, 'c'=>3 }.to_a   #=> [["a", 1], ["b", 2], ["c", 3]]

Overloads:



245
246
247
 
# File 'enum.c', line 245

static VALUE
enum_to_a(obj)
VALUE obj;

#detect(ifnone = nil) {|obj| ... } ⇒ Object? #find(ifnone = nil) {|obj| ... } ⇒ Object?

Passes each entry in enum to block. Returns the first for which block is not false. If no object matches, calls ifnone and returns its result when it is specified, or returns nil

(1..10).detect  {|i| i % 5 == 0 and i % 7 == 0 }   #=> nil
(1..100).detect {|i| i % 5 == 0 and i % 7 == 0 }   #=> 35

Overloads:

  • #detect(ifnone = nil) {|obj| ... } ⇒ Object?

    Yields:

    • (obj)

    Returns:

  • #find(ifnone = nil) {|obj| ... } ⇒ Object?

    Yields:

    • (obj)

    Returns:



107
108
109
 
# File 'enum.c', line 107

static VALUE
enum_find(argc, argv, obj)
int argc;

#find_all {|obj| ... } ⇒ Array #select {|obj| ... } ⇒ Array

Returns an array containing all elements of enum for which block is not false (see also Enumerable#reject).

(1..10).find_all {|i|  i % 3 == 0 }   #=> [3, 6, 9]

Overloads:

  • #find_all {|obj| ... } ⇒ Array

    Yields:

    • (obj)

    Returns:

  • #select {|obj| ... } ⇒ Array

    Yields:

    • (obj)

    Returns:



150
151
152
 
# File 'enum.c', line 150

static VALUE
enum_find_all(obj)
VALUE obj;

#grep(pattern) ⇒ Array #grep(pattern) {|obj| ... } ⇒ Array

Returns an array of every element in enum for which Pattern === element. If the optional block is supplied, each matching element is passed to it, and the block’s result is stored in the output array.

(1..100).grep 38..44   #=> [38, 39, 40, 41, 42, 43, 44]
c = IO.constants
c.grep(/SEEK/)         #=> ["SEEK_END", "SEEK_SET", "SEEK_CUR"]
res = c.grep(/SEEK/) {|v| IO.const_get(v) }
res                    #=> [2, 0, 1]

Overloads:

  • #grep(pattern) ⇒ Array

    Returns:

  • #grep(pattern) {|obj| ... } ⇒ Array

    Yields:

    • (obj)

    Returns:



65
66
67
 
# File 'enum.c', line 65

static VALUE
enum_grep(obj, pat)
VALUE obj, pat;

#include?(obj) ⇒ Boolean #member?(obj) ⇒ Boolean

Returns true if any member of enum equals obj. Equality is tested using ==.

IO.constants.include? "SEEK_SET"          #=> true
IO.constants.include? "SEEK_NO_FURTHER"   #=> false

Overloads:

  • #include?(obj) ⇒ Boolean

    Returns:

    • (Boolean)
  • #member?(obj) ⇒ Boolean

    Returns:

    • (Boolean) 


769
770
771
 
# File 'enum.c', line 769

static VALUE
enum_member(obj, val)
VALUE obj, val;

#inject(initial) {|memo, obj| ... } ⇒ Object #inject {|memo, obj| ... } ⇒ Object

Combines the elements of enum by applying the block to an accumulator value (memo) and each element in turn. At each step, memo is set to the value returned by the block. The first form lets you supply an initial value for memo. The second form uses the first element of the collection as a the initial value (and skips that element while iterating).

# Sum some numbers
(5..10).inject {|sum, n| sum + n }              #=> 45
# Multiply some numbers
(5..10).inject(1) {|product, n| product * n }   #=> 151200

# find the longest word
longest = %w{ cat sheep bear }.inject do |memo,word|
   memo.length > word.length ? memo : word
end
longest                                         #=> "sheep"

# find the length of the longest word
longest = %w{ cat sheep bear }.inject(0) do |memo,word|
   memo >= word.length ? memo : word.length
end
longest                                         #=> 5

Overloads:

  • #inject(initial) {|memo, obj| ... } ⇒ Object

    Yields:

    • (memo, obj)

    Returns:

  • #inject {|memo, obj| ... } ⇒ Object

    Yields:

    • (memo, obj)

    Returns:



301
302
303
 
# File 'enum.c', line 301

static VALUE
enum_inject(argc, argv, obj)
int argc;

#collect {|obj| ... } ⇒ Array #map {|obj| ... } ⇒ Array

Returns a new array with the results of running block once for every element in enum.

(1..4).collect {|i| i*i }   #=> [1, 4, 9, 16]
(1..4).collect { "cat"  }   #=> ["cat", "cat", "cat", "cat"]

Overloads:

  • #collect {|obj| ... } ⇒ Array

    Yields:

    • (obj)

    Returns:

  • #map {|obj| ... } ⇒ Array

    Yields:

    • (obj)

    Returns:



224
225
226
 
# File 'enum.c', line 224

static VALUE
enum_collect(obj)
VALUE obj;

#max ⇒ Object #max {|a, b| ... } ⇒ Object

Returns the object in enum with the maximum value. The first form assumes all objects implement Comparable; the second uses the block to return a <=> b.

a = %w(albatross dog horse)
a.max                                  #=> "horse"
a.max {|a,b| a.length <=> b.length }   #=> "albatross"

Overloads:



733
734
735
 
# File 'enum.c', line 733

static VALUE
enum_max(obj)
VALUE obj;

#include?(obj) ⇒ Boolean #member?(obj) ⇒ Boolean

Returns true if any member of enum equals obj. Equality is tested using ==.

IO.constants.include? "SEEK_SET"          #=> true
IO.constants.include? "SEEK_NO_FURTHER"   #=> false

Overloads:

  • #include?(obj) ⇒ Boolean

    Returns:

    • (Boolean)
  • #member?(obj) ⇒ Boolean

    Returns:

    • (Boolean) 


769
770
771
 
# File 'enum.c', line 769

static VALUE
enum_member(obj, val)
VALUE obj, val;

#min ⇒ Object #min {|a, b| ... } ⇒ Object

Returns the object in enum with the minimum value. The first form assumes all objects implement Comparable; the second uses the block to return a <=> b.

a = %w(albatross dog horse)
a.min                                  #=> "albatross"
a.min {|a,b| a.length <=> b.length }   #=> "dog"

Overloads:



656
657
658
 
# File 'enum.c', line 656

static VALUE
enum_min(obj)
VALUE obj;

#partition {|obj| ... } ⇒ Array

Returns two arrays, the first containing the elements of enum for which the block evaluates to true, the second containing the rest.

(1..6).partition {|i| (i&1).zero?}   #=> [[2, 4, 6], [1, 3, 5]]

Yields:

  • (obj)

Returns:



340
341
342
 
# File 'enum.c', line 340

static VALUE
enum_partition(obj)
VALUE obj;

#reject {|obj| ... } ⇒ Array

Returns an array for all elements of enum for which block is false (see also Enumerable#find_all).

(1..10).reject {|i|  i % 3 == 0 }   #=> [1, 2, 4, 5, 7, 8, 10]

Yields:

  • (obj)

Returns:



182
183
184
 
# File 'enum.c', line 182

static VALUE
enum_reject(obj)
VALUE obj;

#find_all {|obj| ... } ⇒ Array #select {|obj| ... } ⇒ Array

Returns an array containing all elements of enum for which block is not false (see also Enumerable#reject).

(1..10).find_all {|i|  i % 3 == 0 }   #=> [3, 6, 9]

Overloads:

  • #find_all {|obj| ... } ⇒ Array

    Yields:

    • (obj)

    Returns:

  • #select {|obj| ... } ⇒ Array

    Yields:

    • (obj)

    Returns:



150
151
152
 
# File 'enum.c', line 150

static VALUE
enum_find_all(obj)
VALUE obj;

#sort ⇒ Array #sort {|a, b| ... } ⇒ Array

Returns an array containing the items in enum sorted, either according to their own <=> method, or by using the results of the supplied block. The block should return -1, 0, or +1 depending on the comparison between a and b. As of Ruby 1.8, the method Enumerable#sort_by implements a built-in Schwartzian Transform, useful when key computation or comparison is expensive..

%w(rhea kea flea).sort         #=> ["flea", "kea", "rhea"]
(1..10).sort {|a,b| b <=> a}   #=> [10, 9, 8, 7, 6, 5, 4, 3, 2, 1]

Overloads:



370
371
372
 
# File 'enum.c', line 370

static VALUE
enum_sort(obj)
VALUE obj;

#sort_by {|obj| ... } ⇒ Array

Sorts enum using a set of keys generated by mapping the values in enum through the given block.

%w{ apple pear fig }.sort_by {|word| word.length}
               #=> ["fig", "pear", "apple"]

The current implementation of sort_by generates an array of tuples containing the original collection element and the mapped value. This makes sort_by fairly expensive when the keysets are simple

require 'benchmark'
include Benchmark

a = (1..100000).map {rand(100000)}

bm(10) do |b|
  b.report("Sort")    { a.sort }
  b.report("Sort by") { a.sort_by {|a| a} }
end

produces:

user     system      total        real
Sort        0.180000   0.000000   0.180000 (  0.175469)
Sort by     1.980000   0.040000   2.020000 (  2.013586)

However, consider the case where comparing the keys is a non-trivial operation. The following code sorts some files on modification time using the basic sort method.

files = Dir["*"]
sorted = files.sort {|a,b| File.new(a).mtime <=> File.new(b).mtime}
sorted   #=> ["mon", "tues", "wed", "thurs"]

This sort is inefficient: it generates two new File objects during every comparison. A slightly better technique is to use the Kernel#test method to generate the modification times directly.

files = Dir["*"]
sorted = files.sort { |a,b|
  test(?M, a) <=> test(?M, b)
}
sorted   #=> ["mon", "tues", "wed", "thurs"]

This still generates many unnecessary Time objects. A more efficient technique is to cache the sort keys (modification times in this case) before the sort. Perl users often call this approach a Schwartzian Transform, after Randal Schwartz. We construct a temporary array, where each element is an array containing our sort key along with the filename. We sort this array, and then extract the filename from the result.

sorted = Dir["*"].collect { |f|
   [test(?M, f), f]
}.sort.collect { |f| f[1] }
sorted   #=> ["mon", "tues", "wed", "thurs"]

This is exactly what sort_by does internally.

sorted = Dir["*"].sort_by {|f| test(?M, f)}
sorted   #=> ["mon", "tues", "wed", "thurs"]

Yields:

  • (obj)

Returns:



472
473
474
 
# File 'enum.c', line 472

static VALUE
enum_sort_by(obj)
VALUE obj;

#to_a ⇒ Array #entries ⇒ Array

Returns an array containing the items in enum.

(1..7).to_a                       #=> [1, 2, 3, 4, 5, 6, 7]
{ 'a'=>1, 'b'=>2, 'c'=>3 }.to_a   #=> [["a", 1], ["b", 2], ["c", 3]]

Overloads:



245
246
247
 
# File 'enum.c', line 245

static VALUE
enum_to_a(obj)
VALUE obj;

#zip(arg, ...) ⇒ Array #zip(arg, ...) {|arr| ... } ⇒ nil

Converts any arguments to arrays, then merges elements of enum with corresponding elements from each argument. This generates a sequence of enum#size n-element arrays, where n is one more that the count of arguments. If the size of any argument is less than enum#size, nil values are supplied. If a block given, it is invoked for each output array, otherwise an array of arrays is returned.

a = [ 4, 5, 6 ]
b = [ 7, 8, 9 ]

(1..3).zip(a, b)      #=> [[1, 4, 7], [2, 5, 8], [3, 6, 9]]
"cat\ndog".zip([1])   #=> [["cat\n", 1], ["dog", nil]]
(1..3).zip            #=> [[1], [2], [3]]

Overloads:

  • #zip(arg, ...) ⇒ Array

    Returns:

  • #zip(arg, ...) {|arr| ... } ⇒ nil

    Yields:

    • (arr)

    Returns:

    • (nil) 


865
866
867
 
# File 'enum.c', line 865

static VALUE
enum_zip(argc, argv, obj)
int argc;