Module: Enumerable

Included in:
Array, Dir, Enumerator, 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.

Defined Under Namespace

Classes: Enumerator

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) 


905
906
907
 
# File 'enum.c', line 905

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) 


953
954
955
 
# File 'enum.c', line 953

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:



427
428
429
 
# File 'enum.c', line 427

static VALUE
enum_collect(obj)
VALUE obj;

#count ⇒ Integer #count(item) ⇒ Integer #count {|obj| ... } ⇒ Integer

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

Overloads:



172
173
174
 
# File 'enum.c', line 172

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

#cycle {|obj| ... } ⇒ Object #cycle(n) {|obj| ... } ⇒ Object

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.

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.

Overloads:

  • #cycle {|obj| ... } ⇒ Object

    Yields:

    • (obj)
  • #cycle(n) {|obj| ... } ⇒ Object

    Yields:

    • (obj) 


1795
1796
1797
 
# File 'enum.c', line 1795

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

#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:



232
233
234
 
# File 'enum.c', line 232

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

#drop(n) ⇒ Array

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]

Returns:



1707
1708
1709
 
# File 'enum.c', line 1707

static VALUE
enum_drop(obj, n)
VALUE obj;

#drop_while {|arr| ... } ⇒ Array

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.

a = [1, 2, 3, 4, 5, 0]
a.drop_while {|i| i < 3 }   # => [3, 4, 5, 0]

Yields:

  • (arr)

Returns:



1753
1754
1755
 
# File 'enum.c', line 1753

static VALUE
enum_drop_while(obj)
VALUE obj;

#each_cons(n) { ... } ⇒ Object #each_cons(n) ⇒ Object

Iterates the given block for each array of consecutive <n> elements. If no block is given, returns an enumerator.a

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]

Overloads:

  • #each_cons(n) { ... } ⇒ Object

    Yields:



194
195
196
 
# File 'enumerator.c', line 194

static VALUE
enum_each_cons(obj, n)
VALUE obj, n;

#each_slice(n) { ... } ⇒ Object #each_slice(n) ⇒ Object

Iterates the given block for each slice of <n> elements. If no block is given, returns an enumerator.

e.g.:

(1..10).each_slice(3) {|a| p a}
# outputs below
[1, 2, 3]
[4, 5, 6]
[7, 8, 9]
[10]

Overloads:

  • #each_slice(n) { ... } ⇒ Object

    Yields:



134
135
136
 
# File 'enumerator.c', line 134

static VALUE
enum_each_slice(obj, n)
VALUE obj, n;

#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:



1499
1500
1501
 
# File 'enum.c', line 1499

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:



448
449
450
 
# File 'enum.c', line 448

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

#each_cons(n) { ... } ⇒ Object #each_cons(n) ⇒ Object

Iterates the given block for each array of consecutive <n> elements. If no block is given, returns an enumerator.a

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]

Overloads:

  • #each_cons(n) { ... } ⇒ Object

    Yields:



194
195
196
 
# File 'enumerator.c', line 194

static VALUE
enum_each_cons(obj, n)
VALUE obj, n;

#each_slice(n) { ... } ⇒ Object #each_slice(n) ⇒ Object

Iterates the given block for each slice of <n> elements. If no block is given, returns an enumerator.

e.g.:

(1..10).each_slice(3) {|a| p a}
# outputs below
[1, 2, 3]
[4, 5, 6]
[7, 8, 9]
[10]

Overloads:

  • #each_slice(n) { ... } ⇒ Object

    Yields:



134
135
136
 
# File 'enumerator.c', line 134

static VALUE
enum_each_slice(obj, n)
VALUE obj, n;

#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:



1499
1500
1501
 
# File 'enum.c', line 1499

static VALUE
enum_each_with_index(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:



232
233
234
 
# File 'enum.c', line 232

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:



351
352
353
 
# File 'enum.c', line 351

static VALUE
enum_find_all(obj)
VALUE obj;

#find_index(value) ⇒ Integer? #find_index {|obj| ... } ⇒ Integer?

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

(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

Overloads:



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

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

#first ⇒ Object? #first(n) ⇒ Array

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.

Overloads:



691
692
693
 
# File 'enum.c', line 691

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

#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:



101
102
103
 
# File 'enum.c', line 101

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

#group_by {|obj| ... } ⇒ Hash

Returns a hash, which keys are evaluated result from the block, and values are arrays of elements in enum corresponding to the key.

(1..6).group_by {|i| i%3}   #=> {0=>[3, 6], 1=>[1, 4], 2=>[2, 5]}

Yields:

  • (obj)

Returns:

  • (Hash) 


644
645
646
 
# File 'enum.c', line 644

static VALUE
enum_group_by(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) 


1462
1463
1464
 
# File 'enum.c', line 1462

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

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

enum.reduce(initial, sym) => obj

enum.reduce(sym)          => obj
enum.reduce(initial) {| memo, obj | block }  => obj
enum.reduce          {| memo, obj | block }  => 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<i> the block is passed an accumulator value (<i>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 fo 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"

Overloads:

  • #inject(initial, sym) ⇒ Object

    Returns:

  • #inject(sym) ⇒ Object

    Returns:

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

    Yields:

    • (memo, obj)

    Returns:

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

    Yields:

    • (memo, obj)

    Returns:



539
540
541
 
# File 'enum.c', line 539

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:



427
428
429
 
# File 'enum.c', line 427

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:



1192
1193
1194
 
# File 'enum.c', line 1192

static VALUE
enum_max(obj)
VALUE obj;

#max_by {|obj| ... } ⇒ Object

Returns the object in enum that gives the maximum value from the given block.

a = %w(albatross dog horse)
a.max_by {|x| x.length }   #=> "albatross"

Yields:

  • (obj)

Returns:



1368
1369
1370
 
# File 'enum.c', line 1368

static VALUE
enum_max_by(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) 


1462
1463
1464
 
# File 'enum.c', line 1462

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:



1115
1116
1117
 
# File 'enum.c', line 1115

static VALUE
enum_min(obj)
VALUE obj;

#min_by {|obj| ... } ⇒ Object

Returns the object in enum that gives the minimum value from the given block.

a = %w(albatross dog horse)
a.min_by {|x| x.length }   #=> "dog"

Yields:

  • (obj)

Returns:



1324
1325
1326
 
# File 'enum.c', line 1324

static VALUE
enum_min_by(obj)
VALUE obj;

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

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"]

Overloads:

  • #minmax ⇒ Array

    Returns:

  • #minmax {|a, b| ... } ⇒ Array

    Yields:

    • (a, b)

    Returns:



1272
1273
1274
 
# File 'enum.c', line 1272

static VALUE
enum_minmax(obj)
VALUE obj;

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

Returns two elements array array containing the objects in enum that gives the minimum and maximum values respectively from the given block.

a = %w(albatross dog horse)
a.minmax_by {|x| x.length }   #=> ["dog", "albatross"]

Yields:

  • (obj)

Returns:



1421
1422
1423
 
# File 'enum.c', line 1421

static VALUE
enum_minmax_by(obj)
VALUE obj;

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

Passes each element of the collection to the given block. The method returns true if the block never returns true for all elements. If the block is not given, none? will return true only if none of the collection members is true.

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

Yields:

  • (obj)

Returns:

  • (Boolean) 


1052
1053
1054
 
# File 'enum.c', line 1052

static VALUE
enum_none(obj)
VALUE obj;

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

Passes each element of the collection to the given block. The method returns true if the block returns true exactly once. If the block is not given, one? will return true only if exactly one of the collection members is true.

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

Yields:

  • (obj)

Returns:

  • (Boolean) 


1006
1007
1008
 
# File 'enum.c', line 1006

static VALUE
enum_one(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:



598
599
600
 
# File 'enum.c', line 598

static VALUE
enum_partition(obj)
VALUE obj;

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

enum.reduce(initial, sym) => obj

enum.reduce(sym)          => obj
enum.reduce(initial) {| memo, obj | block }  => obj
enum.reduce          {| memo, obj | block }  => 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<i> the block is passed an accumulator value (<i>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 fo 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"

Overloads:

  • #inject(initial, sym) ⇒ Object

    Returns:

  • #inject(sym) ⇒ Object

    Returns:

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

    Yields:

    • (memo, obj)

    Returns:

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

    Yields:

    • (memo, obj)

    Returns:



539
540
541
 
# File 'enum.c', line 539

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

#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:



384
385
386
 
# File 'enum.c', line 384

static VALUE
enum_reject(obj)
VALUE obj;

#reverse_each {|item| ... } ⇒ Object

Traverses enum in reverse order.

Yields:

  • (item) 


1519
1520
1521
1522
1523
1524
1525
1526
1527
1528
1529
1530
1531
1532
1533
1534
 
# File 'enum.c', line 1519

static VALUE
enum_reverse_each(int argc, VALUE *argv, VALUE obj)
{
    VALUE ary;
    long i;

    RETURN_ENUMERATOR(obj, argc, argv);

    ary = enum_to_a(argc, argv, obj);

    for (i = RARRAY_LEN(ary); --i >= 0; ) {
	rb_yield(RARRAY_PTR(ary)[i]);
    }

    return 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:



351
352
353
 
# File 'enum.c', line 351

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:



730
731
732
 
# File 'enum.c', line 730

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:



837
838
839
 
# File 'enum.c', line 837

static VALUE
enum_sort_by(obj)
VALUE obj;

#take(n) ⇒ Array

Returns first n elements from enum.

a = [1, 2, 3, 4, 5, 0]
a.take(3)             # => [1, 2, 3]

Returns:



1628
1629
1630
 
# File 'enum.c', line 1628

static VALUE
enum_take(obj, n)
VALUE obj;

#take_while {|arr| ... } ⇒ Array

Passes elements to the block until the block returns nil or false, then stops iterating and returns an array of all prior elements.

a = [1, 2, 3, 4, 5, 0]
a.take_while {|i| i < 3 }   # => [1, 2]

Yields:

  • (arr)

Returns:



1669
1670
1671
 
# File 'enum.c', line 1669

static VALUE
enum_take_while(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:



448
449
450
 
# File 'enum.c', line 448

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

#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) 


1585
1586
1587
 
# File 'enum.c', line 1585

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