Module: Enumerable
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.
Defined Under Namespace
Classes: Enumerator
Instance Method Summary (collapse)
-
- _count
Returns the number of items in enum, where #size is called if it responds to it, otherwise the items are counted through enumeration.
- - all?
- - any?
-
- collect
Returns a new array with the results of running block once for every element in enum.
-
- collect_concat
Returns a new array with the concatenated results of running block once for every element in enum.
-
- count
Returns the number of items in enum, where #size is called if it responds to it, otherwise the items are counted through enumeration.
-
- cycle
Calls block for each element of enum repeatedly n times or forever if none or nil is given.
-
- detect
Passes each entry in enum to block.
-
- drop
Drops first n elements from enum, and returns rest elements in an array.
-
- drop_while
Drops elements up to, but not including, the first element for which the block returns nil or false and returns an array containing the remaining elements.
-
- each_cons
Iterates the given block for each array of consecutive
elements. -
- each_entry
Calls block once for each element in self, passing that element as a parameter, converting multiple values from yield to an array.
-
- each_slice
Iterates the given block for each slice of
elements. -
- each_with_index
Calls block with two arguments, the item and its index, for each item in enum.
-
- each_with_object
Iterates the given block for each element with an arbitrary object given, and returns the initially given object.
-
- entries
Returns an array containing the items in enum.
-
- find
Passes each entry in enum to block.
-
- find_all
Returns an array containing all elements of enum for which block is not false (see also Enumerable#reject).
-
- find_index
Compares each entry in enum with value or passes to block.
-
- first
Returns the first element, or the first n elements, of the enumerable.
-
- flat_map
Returns a new array with the concatenated results of running block once for every element in enum.
-
- grep
Returns an array of every element in enum for which Pattern === element.
-
- group_by
Returns a hash, which keys are evaluated result from the block, and values are arrays of elements in enum corresponding to the key.
-
- include?
Returns true if any member of enum equals obj.
-
- inject
Combines all elements of enum by applying a binary operation, specified by a block or a symbol that names a method or operator.
-
- map
Returns a new array with the results of running block once for every element in enum.
-
- max
Returns the object in enum with the maximum value.
-
- max_by
Returns the object in enum that gives the maximum value from the given block.
-
- member?
Returns true if any member of enum equals obj.
-
- min
Returns the object in enum with the minimum value.
-
- min_by
Returns the object in enum that gives the minimum value from the given block.
-
- minmax
Returns two elements array which contains the minimum and the maximum value in the enumerable.
-
- minmax_by
Returns two elements array array containing the objects in enum that gives the minimum and maximum values respectively from the given block.
- - none?
- - one?
-
- partition
Returns two arrays, the first containing the elements of enum for which the block evaluates to true, the second containing the rest.
-
- reduce
Combines all elements of enum by applying a binary operation, specified by a block or a symbol that names a method or operator.
-
- reject
Returns an array for all elements of enum for which block is false (see also Enumerable#find_all).
-
- reverse_each
Builds a temporary array and traverses that array in reverse order.
-
- select
Returns an array containing all elements of enum for which block is not false (see also Enumerable#reject).
-
- sort
Returns an array containing the items in enum sorted, either according to their own method, or by using the results of the supplied block.
-
- sort_by
Sorts enum using a set of keys generated by mapping the values in enum through the given block.
-
- take
Returns first n elements from enum.
-
- take_while
Passes elements to the block until the block returns nil or false, then stops iterating and returns an array of all prior elements.
-
- to_a
Returns an array containing the items in enum.
-
- zip
Takes one element from enum and merges corresponding elements from each args.
Instance Method Details
- (Integer) count - (Integer) count(item) - (Integer) count {|obj| ... }
Returns the number of items in enum, where #size is called if it responds to it, otherwise the items are counted through enumeration. If an argument is given, counts the number of items in enum, for which equals to item. If a block is given, counts the number of elements yielding a true value.
ary = [1, 2, 4, 2]
ary.count #=> 4
ary.count(2) #=> 2
ary.count{|x|x%2==0} #=> 3
- (Boolean) all?
- (Boolean) any?
- (Array) collect {|obj| ... } - (Array) map {|obj| ... } - (Enumerator) collect - (Enumerator) map
Returns a new array with the results of running block once for every element in enum.
If no block is given, an enumerator is returned instead.
(1..4).collect {|i| i*i } #=> [1, 4, 9, 16]
(1..4).collect { "cat" } #=> ["cat", "cat", "cat", "cat"]
- (Array) flat_map {|obj| ... } - (Array) collect_concat {|obj| ... } - (Enumerator) flat_map - (Enumerator) collect_concat
Returns a new array with the concatenated results of running block once for every element in enum.
If no block is given, an enumerator is returned instead.
[[1,2],[3,4]].flat_map {|i| i } #=> [1, 2, 3, 4]
- (Integer) count - (Integer) count(item) - (Integer) count {|obj| ... }
Returns the number of items in enum, where #size is called if it responds to it, otherwise the items are counted through enumeration. If an argument is given, counts the number of items in enum, for which equals to item. If a block is given, counts the number of elements yielding a true value.
ary = [1, 2, 4, 2]
ary.count #=> 4
ary.count(2) #=> 2
ary.count{|x|x%2==0} #=> 3
- (nil) cycle(n = nil) {|obj| ... } - (Enumerator) cycle(n = nil)
Calls block for each element of enum repeatedly n times or forever if none or nil is given. If a non-positive number is given or the collection is empty, does nothing. Returns nil if the loop has finished without getting interrupted.
Enumerable#cycle saves elements in an internal array so changes to enum after the first pass have no effect.
If no block is given, an enumerator is returned instead.
a = ["a", "b", "c"]
a.cycle {|x| puts x } # print, a, b, c, a, b, c,.. forever.
a.cycle(2) {|x| puts x } # print, a, b, c, a, b, c.
- (Object?) detect(ifnone = nil) {|obj| ... } - (Object?) find(ifnone = nil) {|obj| ... } - (Enumerator) detect(ifnone = nil) - (Enumerator) find(ifnone = nil)
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 otherwise.
If no block is given, an enumerator is returned instead.
(1..10).detect {|i| i % 5 == 0 and i % 7 == 0 } #=> nil
(1..100).detect {|i| i % 5 == 0 and i % 7 == 0 } #=> 35
- (Array) drop(n)
Drops first n elements from enum, and returns rest elements in an array.
a = [1, 2, 3, 4, 5, 0]
a.drop(3) #=> [4, 5, 0]
- (Array) drop_while {|arr| ... } - (Enumerator) drop_while
Drops elements up to, but not including, the first element for which the block returns nil or false and returns an array containing the remaining elements.
If no block is given, an enumerator is returned instead.
a = [1, 2, 3, 4, 5, 0]
a.drop_while {|i| i < 3 } #=> [3, 4, 5, 0]
- (Object) each_cons(n) { ... } - (Object) each_cons(n)
Iterates the given block for each array of consecutive
e.g.:
(1..10).each_cons(3) {|a| p a}
# outputs below
[1, 2, 3]
[2, 3, 4]
[3, 4, 5]
[4, 5, 6]
[5, 6, 7]
[6, 7, 8]
[7, 8, 9]
[8, 9, 10]
- (Enumerator) each_entry {|obj| ... } - (Enumerator) each_entry
Calls block once for each element in self, passing that element as a parameter, converting multiple values from yield to an array.
If no block is given, an enumerator is returned instead.
class Foo
include Enumerable
def each
yield 1
yield 1,2
yield
end
end
Foo.new.each_entry{|o| p o }
produces:
1
[1, 2]
nil
- (Object) each_slice(n) { ... } - (Object) each_slice(n)
Iterates the given block for each slice of
e.g.:
(1..10).each_slice(3) {|a| p a}
# outputs below
[1, 2, 3]
[4, 5, 6]
[7, 8, 9]
[10]
- (Enumerator) each_with_index(*args) {|obj, i| ... } - (Enumerator) each_with_index(*args)
Calls block with two arguments, the item and its index, for each item in enum. Given arguments are passed through to #each().
If no block is given, an enumerator is returned instead.
hash = Hash.new
%w(cat dog wombat).each_with_index {|item, index|
hash[item] = index
}
hash #=> {"cat"=>0, "dog"=>1, "wombat"=>2}
- (Object) each_with_object(obj) {|(*args), memo_obj| ... } - (Enumerator) each_with_object(obj)
Iterates the given block for each element with an arbitrary object given, and returns the initially given object.
If no block is given, returns an enumerator.
e.g.:
evens = (1..10).each_with_object([]) {|i, a| a << i*2 }
# => [2, 4, 6, 8, 10, 12, 14, 16, 18, 20]
- (Array) to_a - (Array) entries
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]]
- (Object?) detect(ifnone = nil) {|obj| ... } - (Object?) find(ifnone = nil) {|obj| ... } - (Enumerator) detect(ifnone = nil) - (Enumerator) find(ifnone = nil)
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 otherwise.
If no block is given, an enumerator is returned instead.
(1..10).detect {|i| i % 5 == 0 and i % 7 == 0 } #=> nil
(1..100).detect {|i| i % 5 == 0 and i % 7 == 0 } #=> 35
- (Array) find_all {|obj| ... } - (Array) select {|obj| ... } - (Enumerator) find_all - (Enumerator) select
Returns an array containing all elements of enum for which block is not false (see also Enumerable#reject).
If no block is given, an enumerator is returned instead.
(1..10).find_all {|i| i % 3 == 0 } #=> [3, 6, 9]
- (Integer?) find_index(value) - (Integer?) find_index {|obj| ... } - (Enumerator) find_index
Compares each entry in enum with value or passes to block. Returns the index for the first for which the evaluated value is non-false. If no object matches, returns nil
If neither block nor argument is given, an enumerator is returned instead.
(1..10).find_index {|i| i % 5 == 0 and i % 7 == 0 } #=> nil
(1..100).find_index {|i| i % 5 == 0 and i % 7 == 0 } #=> 34
(1..100).find_index(50) #=> 49
- (Object?) first - (Array) first(n)
Returns the first element, or the first n elements, of the enumerable. If the enumerable is empty, the first form returns nil, and the second form returns an empty array.
%w[foo bar baz].first #=> "foo"
%w[foo bar baz].first(2) #=> ["foo", "bar"]
%w[foo bar baz].first(10) #=> ["foo", "bar", "baz"]
[].first #=> nil
- (Array) flat_map {|obj| ... } - (Array) collect_concat {|obj| ... } - (Enumerator) flat_map - (Enumerator) collect_concat
Returns a new array with the concatenated results of running block once for every element in enum.
If no block is given, an enumerator is returned instead.
[[1,2],[3,4]].flat_map {|i| i } #=> [1, 2, 3, 4]
- (Array) grep(pattern) - (Array) grep(pattern) {|obj| ... }
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_SET, :SEEK_CUR, :SEEK_END]
res = c.grep(/SEEK/) {|v| IO.const_get(v) }
res #=> [0, 1, 2]
- (Hash) group_by {|obj| ... } - (Enumerator) group_by
Returns a hash, which keys are evaluated result from the block, and values are arrays of elements in enum corresponding to the key.
If no block is given, an enumerator is returned instead.
(1..6).group_by {|i| i%3} #=> {0=>[3, 6], 1=>[1, 4], 2=>[2, 5]}
- (Boolean) include?(obj) - (Boolean) member?(obj)
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
- (Object) inject(initial, sym) - (Object) inject(sym) - (Object) inject(initial) {|memo, obj| ... } - (Object) inject {|memo, obj| ... } - (Object) reduce(initial, sym) - (Object) reduce(sym) - (Object) reduce(initial) {|memo, obj| ... } - (Object) reduce {|memo, obj| ... }
Combines all elements of enum by applying a binary operation, specified by a block or a symbol that names a method or operator.
If you specify a block, then for each element in enum the block is passed an accumulator value (memo) and the element. If you specify a symbol instead, then each element in the collection will be passed to the named method of memo. In either case, the result becomes the new value for memo. At the end of the iteration, the final value of memo is the return value for the method.
If you do not explicitly specify an initial value for memo, then uses the first element of collection is used as the initial value of memo.
Examples:
# Sum some numbers
(5..10).reduce(:+) #=> 45
# Same using a block and inject
(5..10).inject {|sum, n| sum + n } #=> 45
# Multiply some numbers
(5..10).reduce(1, :*) #=> 151200
# Same using a block
(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"
- (Array) collect {|obj| ... } - (Array) map {|obj| ... } - (Enumerator) collect - (Enumerator) map
Returns a new array with the results of running block once for every element in enum.
If no block is given, an enumerator is returned instead.
(1..4).collect {|i| i*i } #=> [1, 4, 9, 16]
(1..4).collect { "cat" } #=> ["cat", "cat", "cat", "cat"]
- (Object) max - (Object) max {|a, b| ... }
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"
- (Object) max_by {|obj| ... } - (Enumerator) max_by
Returns the object in enum that gives the maximum value from the given block.
If no block is given, an enumerator is returned instead.
a = %w(albatross dog horse)
a.max_by {|x| x.length } #=> "albatross"
- (Boolean) include?(obj) - (Boolean) member?(obj)
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
- (Object) min - (Object) min {|a, b| ... }
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"
- (Object) min_by {|obj| ... } - (Enumerator) min_by
Returns the object in enum that gives the minimum value from the given block.
If no block is given, an enumerator is returned instead.
a = %w(albatross dog horse)
a.min_by {|x| x.length } #=> "dog"
- (Array) minmax - (Array) minmax {|a, b| ... }
Returns two elements array which contains the minimum and the maximum value in the enumerable. The first form assumes all objects implement Comparable; the second uses the block to return a b.
a = %w(albatross dog horse)
a.minmax #=> ["albatross", "horse"]
a.minmax {|a,b| a.length <=> b.length } #=> ["dog", "albatross"]
- (Array) minmax_by {|obj| ... } - (Enumerator) minmax_by
Returns two elements array array containing the objects in enum that gives the minimum and maximum values respectively from the given block.
If no block is given, an enumerator is returned instead.
a = %w(albatross dog horse)
a.minmax_by {|x| x.length } #=> ["dog", "albatross"]
- (Boolean) none?
- (Boolean) one?
- (Array) partition {|obj| ... } - (Enumerator) partition
Returns two arrays, the first containing the elements of enum for which the block evaluates to true, the second containing the rest.
If no block is given, an enumerator is returned instead.
(1..6).partition {|v| v.even? } #=> [[2, 4, 6], [1, 3, 5]]
- (Object) inject(initial, sym) - (Object) inject(sym) - (Object) inject(initial) {|memo, obj| ... } - (Object) inject {|memo, obj| ... } - (Object) reduce(initial, sym) - (Object) reduce(sym) - (Object) reduce(initial) {|memo, obj| ... } - (Object) reduce {|memo, obj| ... }
Combines all elements of enum by applying a binary operation, specified by a block or a symbol that names a method or operator.
If you specify a block, then for each element in enum the block is passed an accumulator value (memo) and the element. If you specify a symbol instead, then each element in the collection will be passed to the named method of memo. In either case, the result becomes the new value for memo. At the end of the iteration, the final value of memo is the return value for the method.
If you do not explicitly specify an initial value for memo, then uses the first element of collection is used as the initial value of memo.
Examples:
# Sum some numbers
(5..10).reduce(:+) #=> 45
# Same using a block and inject
(5..10).inject {|sum, n| sum + n } #=> 45
# Multiply some numbers
(5..10).reduce(1, :*) #=> 151200
# Same using a block
(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"
- (Array) reject {|obj| ... } - (Enumerator) reject
Returns an array for all elements of enum for which block is false (see also Enumerable#find_all).
If no block is given, an enumerator is returned instead.
(1..10).reject {|i| i % 3 == 0 } #=> [1, 2, 4, 5, 7, 8, 10]
- (Enumerator) reverse_each(*args) {|item| ... } - (Enumerator) reverse_each(*args)
Builds a temporary array and traverses that array in reverse order.
If no block is given, an enumerator is returned instead.
(1..3).reverse_each {|v| p v }
produces:
3
2
1
- (Array) find_all {|obj| ... } - (Array) select {|obj| ... } - (Enumerator) find_all - (Enumerator) select
Returns an array containing all elements of enum for which block is not false (see also Enumerable#reject).
If no block is given, an enumerator is returned instead.
(1..10).find_all {|i| i % 3 == 0 } #=> [3, 6, 9]
- (Array) sort - (Array) sort {|a, b| ... }
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]
- (Array) sort_by {|obj| ... } - (Enumerator) sort_by
Sorts enum using a set of keys generated by mapping the values in enum through the given block.
If no block is given, an enumerator is returned instead.
%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'
a = (1..100000).map {rand(100000)}
Benchmark.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"]
- (Array) take(n)
Returns first n elements from enum.
a = [1, 2, 3, 4, 5, 0]
a.take(3) #=> [1, 2, 3]
- (Array) take_while {|arr| ... } - (Enumerator) take_while
Passes elements to the block until the block returns nil or false, then stops iterating and returns an array of all prior elements.
If no block is given, an enumerator is returned instead.
a = [1, 2, 3, 4, 5, 0]
a.take_while {|i| i < 3 } #=> [1, 2]
- (Array) to_a - (Array) entries
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]]
- (Object) zip(arg, ...) - (nil) zip(arg, ...) {|arr| ... }
Takes one element from enum and merges corresponding elements from each args. This generates a sequence of n-element arrays, where n is one more than the count of arguments. The length of the resulting sequence will be enum#size. If the size of any argument is less than enum#size, nil values are supplied. If a block is given, it is invoked for each output array, otherwise an array of arrays is returned.
a = [ 4, 5, 6 ]
b = [ 7, 8, 9 ]
[1,2,3].zip(a, b) #=> [[1, 4, 7], [2, 5, 8], [3, 6, 9]]
[1,2].zip(a,b) #=> [[1, 4, 7], [2, 5, 8]]
a.zip([1,2],[8]) #=> [[4, 1, 8], [5, 2, nil], [6, nil, nil]]