Module: Enumerable

Included in:
Array, Dir, Enumerator, Enumerator::Generator, Hash, IO, ObjectSpace::WeakMap, Range, 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 #all?(pattern) ⇒ 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 } which will cause #all? to return true when none of the collection members are false or nil.

If instead a pattern is supplied, the method returns whether pattern === element for every collection member.

%w[ant bear cat].all? { |word| word.length >= 3 } #=> true
%w[ant bear cat].all? { |word| word.length >= 4 } #=> false
%w[ant bear cat].all?(/t/)                        #=> false
[1, 2i, 3.14].all?(Numeric)                       #=> true
[nil, true, 99].all?                              #=> false
[].all?                                           #=> true

Overloads:

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

    Yields:

    • (obj)

    Returns:

    • (Boolean)
  • #all?(pattern) ⇒ Boolean

    Returns:

    • (Boolean) 


1342
1343
1344
1345
1346
1347
1348
1349
 
# File 'enum.c', line 1342

static VALUE
enum_all(int argc, VALUE *argv, VALUE obj)
{
    struct MEMO *memo = MEMO_ENUM_NEW(Qtrue);
    WARN_UNUSED_BLOCK(argc);
    rb_block_call(obj, id_each, 0, 0, ENUMFUNC(all), (VALUE)memo);
    return memo->v1;
}

#any? {|obj| ... } ⇒ Boolean #any?(pattern) ⇒ 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 will cause #any? to return true if at least one of the collection members is not false or nil.

If instead a pattern is supplied, the method returns whether pattern === element for any collection member.

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

Overloads:

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

    Yields:

    • (obj)

    Returns:

    • (Boolean)
  • #any?(pattern) ⇒ Boolean

    Returns:

    • (Boolean) 


1384
1385
1386
1387
1388
1389
1390
1391
 
# File 'enum.c', line 1384

static VALUE
enum_any(int argc, VALUE *argv, VALUE obj)
{
    struct MEMO *memo = MEMO_ENUM_NEW(Qfalse);
    WARN_UNUSED_BLOCK(argc);
    rb_block_call(obj, id_each, 0, 0, ENUMFUNC(any), (VALUE)memo);
    return memo->v1;
}

#chain(*enums) ⇒ Object

Returns an enumerator object generated from this enumerator and given enumerables.

e = (1..3).chain([4, 5])
e.to_a #=> [1, 2, 3, 4, 5]



3271
3272
3273
3274
3275
3276
3277
3278
 
# File 'enumerator.c', line 3271

static VALUE
enum_chain(int argc, VALUE *argv, VALUE obj)
{
    VALUE enums = rb_ary_new_from_values(1, &obj);
    rb_ary_cat(enums, argv, argc);

    return enum_chain_initialize(enum_chain_allocate(rb_cEnumChain), enums);
}

#chunk {|elt| ... } ⇒ Object

Enumerates over the items, chunking them together based on the return value of the block.

Consecutive elements which return the same block value are chunked together.

For example, consecutive even numbers and odd numbers can be chunked as follows.

[3, 1, 4, 1, 5, 9, 2, 6, 5, 3, 5].chunk { |n|
  n.even?
}.each { |even, ary|
  p [even, ary]
}
#=> [false, [3, 1]]
#   [true, [4]]
#   [false, [1, 5, 9]]
#   [true, [2, 6]]
#   [false, [5, 3, 5]]

This method is especially useful for sorted series of elements. The following example counts words for each initial letter.

open("/usr/share/dict/words", "r:iso-8859-1") { |f|
  f.chunk { |line| line.ord }.each { |ch, lines| p [ch.chr, lines.length] }
}
#=> ["\n", 1]
#   ["A", 1327]
#   ["B", 1372]
#   ["C", 1507]
#   ["D", 791]
#   ...

The following key values have special meaning:

  • nil and :_separator specifies that the elements should be dropped.

  • :_alone specifies that the element should be chunked by itself.

Any other symbols that begin with an underscore will raise an error:

items.chunk { |item| :_underscore }
#=> RuntimeError: symbols beginning with an underscore are reserved

nil and :_separator can be used to ignore some elements.

For example, the sequence of hyphens in svn log can be eliminated as follows:

sep = "-"*72 + "\n"
IO.popen("svn log README") { |f|
  f.chunk { |line|
    line != sep || nil
  }.each { |_, lines|
    pp lines
  }
}
#=> ["r20018 | knu | 2008-10-29 13:20:42 +0900 (Wed, 29 Oct 2008) | 2 lines\n",
#    "\n",
#    "* README, README.ja: Update the portability section.\n",
#    "\n"]
#   ["r16725 | knu | 2008-05-31 23:34:23 +0900 (Sat, 31 May 2008) | 2 lines\n",
#    "\n",
#    "* README, README.ja: Add a note about default C flags.\n",
#    "\n"]
#   ...

Paragraphs separated by empty lines can be parsed as follows:

File.foreach("README").chunk { |line|
  /\A\s*\z/ !~ line || nil
}.each { |_, lines|
  pp lines
}

:_alone can be used to force items into their own chunk. For example, you can put lines that contain a URL by themselves, and chunk the rest of the lines together, like this:

pattern = /http/
open(filename) { |f|
  f.chunk { |line| line =~ pattern ? :_alone : true }.each { |key, lines|
    pp lines
  }
}

If no block is given, an enumerator to ‘chunk` is returned instead.

Yields:

  • (elt) 


3260
3261
3262
3263
3264
3265
3266
3267
3268
3269
3270
3271
3272
 
# File 'enum.c', line 3260

static VALUE
enum_chunk(VALUE enumerable)
{
    VALUE enumerator;

    RETURN_SIZED_ENUMERATOR(enumerable, 0, 0, enum_size);

    enumerator = rb_obj_alloc(rb_cEnumerator);
    rb_ivar_set(enumerator, rb_intern("chunk_enumerable"), enumerable);
    rb_ivar_set(enumerator, rb_intern("chunk_categorize"), rb_block_proc());
    rb_block_call(enumerator, idInitialize, 0, 0, chunk_i, enumerator);
    return enumerator;
}

#chunk_while {|elt_before, elt_after| ... } ⇒ Object

Creates an enumerator for each chunked elements. The beginnings of chunks are defined by the block.

This method split each chunk using adjacent elements, elt_before and elt_after, in the receiver enumerator. This method split chunks between elt_before and elt_after where the block returns false.

The block is called the length of the receiver enumerator minus one.

The result enumerator yields the chunked elements as an array. So each method can be called as follows:

enum.chunk_while { |elt_before, elt_after| bool }.each { |ary| ... }

Other methods of the Enumerator class and Enumerable module, such as to_a, map, etc., are also usable.

For example, one-by-one increasing subsequence can be chunked as follows:

a = [1,2,4,9,10,11,12,15,16,19,20,21]
b = a.chunk_while {|i, j| i+1 == j }
p b.to_a #=> [[1, 2], [4], [9, 10, 11, 12], [15, 16], [19, 20, 21]]
c = b.map {|a| a.length < 3 ? a : "#{a.first}-#{a.last}" }
p c #=> [[1, 2], [4], "9-12", [15, 16], "19-21"]
d = c.join(",")
p d #=> "1,2,4,9-12,15,16,19-21"

Increasing (non-decreasing) subsequence can be chunked as follows:

a = [0, 9, 2, 2, 3, 2, 7, 5, 9, 5]
p a.chunk_while {|i, j| i <= j }.to_a
#=> [[0, 9], [2, 2, 3], [2, 7], [5, 9], [5]]

Adjacent evens and odds can be chunked as follows: (Enumerable#chunk is another way to do it.)

a = [7, 5, 9, 2, 0, 7, 9, 4, 2, 0]
p a.chunk_while {|i, j| i.even? == j.even? }.to_a
#=> [[7, 5, 9], [2, 0], [7, 9], [4, 2, 0]]

Enumerable#slice_when does the same, except splitting when the block returns true instead of false.

Yields:

  • (elt_before, elt_after) 


3818
3819
3820
3821
3822
3823
3824
3825
3826
3827
3828
3829
3830
3831
3832
3833
 
# File 'enum.c', line 3818

static VALUE
enum_chunk_while(VALUE enumerable)
{
    VALUE enumerator;
    VALUE pred;

    pred = rb_block_proc();

    enumerator = rb_obj_alloc(rb_cEnumerator);
    rb_ivar_set(enumerator, rb_intern("slicewhen_enum"), enumerable);
    rb_ivar_set(enumerator, rb_intern("slicewhen_pred"), pred);
    rb_ivar_set(enumerator, rb_intern("slicewhen_inverted"), Qtrue);

    rb_block_call(enumerator, idInitialize, 0, 0, slicewhen_i, enumerator);
    return enumerator;
}

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

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).map { |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:



571
572
573
574
575
576
577
578
579
580
581
582
583
584
 
# File 'enum.c', line 571

static VALUE
enum_collect(VALUE obj)
{
    VALUE ary;
    int min_argc, max_argc;

    RETURN_SIZED_ENUMERATOR(obj, 0, 0, enum_size);

    ary = rb_ary_new();
    min_argc = rb_block_min_max_arity(&max_argc);
    rb_lambda_call(obj, id_each, 0, 0, collect_i, min_argc, max_argc, ary);

    return ary;
}

#flat_map {|obj| ... } ⇒ Array #collect_concat {|obj| ... } ⇒ Array #flat_map ⇒ Object #collect_concat ⇒ Object

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 { |e| [e, -e] } #=> [1, -1, 2, -2, 3, -3, 4, -4]
[[1, 2], [3, 4]].flat_map { |e| e + [100] } #=> [1, 2, 100, 3, 4, 100]

Overloads:

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

    Yields:

    • (obj)

    Returns:

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

    Yields:

    • (obj)

    Returns:



620
621
622
623
624
625
626
627
628
629
630
631
 
# File 'enum.c', line 620

static VALUE
enum_flat_map(VALUE obj)
{
    VALUE ary;

    RETURN_SIZED_ENUMERATOR(obj, 0, 0, enum_size);

    ary = rb_ary_new();
    rb_block_call(obj, id_each, 0, 0, flat_map_i, ary);

    return ary;
}

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

Returns the number of items in enum through enumeration. If an argument is given, the number of items in enum that are equal to item are counted. If a block is given, it 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:



224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
 
# File 'enum.c', line 224

static VALUE
enum_count(int argc, VALUE *argv, VALUE obj)
{
    VALUE item = Qnil;
    struct MEMO *memo;
    rb_block_call_func *func;

    if (argc == 0) {
  if (rb_block_given_p()) {
      func = count_iter_i;
  }
  else {
      func = count_all_i;
  }
    }
    else {
  rb_scan_args(argc, argv, "1", &item);
  if (rb_block_given_p()) {
      rb_warn("given block not used");
  }
        func = count_i;
    }

    memo = MEMO_NEW(item, 0, 0);
    rb_block_call(obj, id_each, 0, 0, func, (VALUE)memo);
    return imemo_count_value(memo);
}

#cycle(n = nil) {|obj| ... } ⇒ nil #cycle(n = nil) ⇒ 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.

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.

Overloads:

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

    Yields:

    • (obj)

    Returns:

    • (nil) 


3062
3063
3064
3065
3066
3067
3068
3069
3070
3071
3072
3073
3074
3075
3076
3077
3078
3079
3080
3081
3082
3083
3084
3085
3086
3087
3088
3089
3090
 
# File 'enum.c', line 3062

static VALUE
enum_cycle(int argc, VALUE *argv, VALUE obj)
{
    VALUE ary;
    VALUE nv = Qnil;
    long n, i, len;

    rb_check_arity(argc, 0, 1);

    RETURN_SIZED_ENUMERATOR(obj, argc, argv, enum_cycle_size);
    if (!argc || NIL_P(nv = argv[0])) {
        n = -1;
    }
    else {
        n = NUM2LONG(nv);
        if (n <= 0) return Qnil;
    }
    ary = rb_ary_new();
    RBASIC_CLEAR_CLASS(ary);
    rb_block_call(obj, id_each, 0, 0, cycle_i, ary);
    len = RARRAY_LEN(ary);
    if (len == 0) return Qnil;
    while (n < 0 || 0 < --n) {
        for (i=0; i<len; i++) {
      enum_yield_array(RARRAY_AREF(ary, i));
        }
    }
    return Qnil;
}

#detect(ifnone = nil) {|obj| ... } ⇒ Object? #find(ifnone = nil) {|obj| ... } ⇒ Object? #detect(ifnone = nil) ⇒ Object #find(ifnone = nil) ⇒ 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 otherwise.

If no block is given, an enumerator is returned instead.

(1..100).detect  #=> #<Enumerator: 1..100:detect>
(1..100).find    #=> #<Enumerator: 1..100:find>

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

Overloads:

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

    Yields:

    • (obj)

    Returns:

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

    Yields:

    • (obj)

    Returns:



292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
 
# File 'enum.c', line 292

static VALUE
enum_find(int argc, VALUE *argv, VALUE obj)
{
    struct MEMO *memo;
    VALUE if_none;

    if_none = rb_check_arity(argc, 0, 1) ? argv[0] : Qnil;
    RETURN_ENUMERATOR(obj, argc, argv);
    memo = MEMO_NEW(Qundef, 0, 0);
    rb_block_call(obj, id_each, 0, 0, find_i, (VALUE)memo);
    if (memo->u3.cnt) {
  return memo->v1;
    }
    if (!NIL_P(if_none)) {
  return rb_funcallv(if_none, id_call, 0, 0);
    }
    return Qnil;
}

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



2948
2949
2950
2951
2952
2953
2954
2955
2956
2957
2958
2959
2960
2961
2962
2963
 
# File 'enum.c', line 2948

static VALUE
enum_drop(VALUE obj, VALUE n)
{
    VALUE result;
    struct MEMO *memo;
    long len = NUM2LONG(n);

    if (len < 0) {
  rb_raise(rb_eArgError, "attempt to drop negative size");
    }

    result = rb_ary_new();
    memo = MEMO_NEW(result, 0, len);
    rb_block_call(obj, id_each, 0, 0, drop_i, (VALUE)memo);
    return result;
}

#drop_while {|obj| ... } ⇒ Array #drop_while ⇒ Object

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]

Overloads:

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

    Yields:

    • (obj)

    Returns:



2997
2998
2999
3000
3001
3002
3003
3004
3005
3006
3007
3008
 
# File 'enum.c', line 2997

static VALUE
enum_drop_while(VALUE obj)
{
    VALUE result;
    struct MEMO *memo;

    RETURN_ENUMERATOR(obj, 0, 0);
    result = rb_ary_new();
    memo = MEMO_NEW(result, 0, FALSE);
    rb_block_call(obj, id_each, 0, 0, drop_while_i, (VALUE)memo);
    return result;
}

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

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

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) { ... } ⇒ nil

    Yields:

    Returns:

    • (nil) 


2645
2646
2647
2648
2649
2650
2651
2652
2653
2654
2655
2656
2657
2658
2659
2660
 
# File 'enum.c', line 2645

static VALUE
enum_each_cons(VALUE obj, VALUE n)
{
    long size = NUM2LONG(n);
    struct MEMO *memo;
    int arity;

    if (size <= 0) rb_raise(rb_eArgError, "invalid size");
    RETURN_SIZED_ENUMERATOR(obj, 1, &n, enum_each_cons_size);
    arity = rb_block_arity();
    if (enum_size_over_p(obj, size)) return Qnil;
    memo = MEMO_NEW(rb_ary_new2(size), dont_recycle_block_arg(arity), size);
    rb_block_call(obj, id_each, 0, 0, each_cons_i, (VALUE)memo);

    return Qnil;
}

#each_entry {|obj| ... } ⇒ Enumerator #each_entry ⇒ Object

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

Overloads:



2479
2480
2481
2482
2483
2484
2485
 
# File 'enum.c', line 2479

static VALUE
enum_each_entry(int argc, VALUE *argv, VALUE obj)
{
    RETURN_SIZED_ENUMERATOR(obj, argc, argv, enum_size);
    rb_block_call(obj, id_each, argc, argv, each_val_i, 0);
    return obj;
}

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

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

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

Overloads:

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

    Yields:

    Returns:

    • (nil) 


2565
2566
2567
2568
2569
2570
2571
2572
2573
2574
2575
2576
2577
2578
2579
2580
2581
2582
2583
2584
 
# File 'enum.c', line 2565

static VALUE
enum_each_slice(VALUE obj, VALUE n)
{
    long size = NUM2LONG(n);
    VALUE ary;
    struct MEMO *memo;
    int arity;

    if (size <= 0) rb_raise(rb_eArgError, "invalid slice size");
    RETURN_SIZED_ENUMERATOR(obj, 1, &n, enum_each_slice_size);
    size = limit_by_enum_size(obj, size);
    ary = rb_ary_new2(size);
    arity = rb_block_arity();
    memo = MEMO_NEW(ary, dont_recycle_block_arg(arity), size);
    rb_block_call(obj, id_each, 0, 0, each_slice_i, (VALUE)memo);
    ary = memo->v1;
    if (RARRAY_LEN(ary) > 0) rb_yield(ary);

    return Qnil;
}

#each_with_index(*args) {|obj, i| ... } ⇒ Enumerator #each_with_index(*args) ⇒ Object

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}

Overloads:



2387
2388
2389
2390
2391
2392
2393
2394
2395
2396
2397
 
# File 'enum.c', line 2387

static VALUE
enum_each_with_index(int argc, VALUE *argv, VALUE obj)
{
    struct MEMO *memo;

    RETURN_SIZED_ENUMERATOR(obj, argc, argv, enum_size);

    memo = MEMO_NEW(0, 0, 0);
    rb_block_call(obj, id_each, argc, argv, each_with_index_i, (VALUE)memo);
    return obj;
}

#each_with_object(obj) {|(*args), memo_obj| ... } ⇒ Object #each_with_object(obj) ⇒ Object

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.

evens = (1..10).each_with_object([]) { |i, a| a << i*2 }
#=> [2, 4, 6, 8, 10, 12, 14, 16, 18, 20]

Overloads:

  • #each_with_object(obj) {|(*args), memo_obj| ... } ⇒ Object

    Yields:

    • ((*args), memo_obj)

    Returns:



2683
2684
2685
2686
2687
2688
2689
2690
2691
 
# File 'enum.c', line 2683

static VALUE
enum_each_with_object(VALUE obj, VALUE memo)
{
    RETURN_SIZED_ENUMERATOR(obj, 1, &memo, enum_size);

    rb_block_call(obj, id_each, 0, 0, each_with_object_i, memo);

    return memo;
}

#to_a(*args) ⇒ Array #entries(*args) ⇒ 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]]

require 'prime'
Prime.entries 10                  #=> [2, 3, 5, 7]

Overloads:



646
647
648
649
650
651
652
653
654
 
# File 'enum.c', line 646

static VALUE
enum_to_a(int argc, VALUE *argv, VALUE obj)
{
    VALUE ary = rb_ary_new();

    rb_block_call(obj, id_each, argc, argv, collect_all, ary);

    return ary;
}

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

Returns an array containing all elements of enum for which the given block returns a true value.

The find_all and select methods are aliases. There is no performance benefit to either.

If no block is given, an Enumerator is returned instead.

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

[1,2,3,4,5].select { |num|  num.even?  }   #=> [2, 4]

[:foo, :bar].filter { |x| x == :foo }   #=> [:foo]

See also Enumerable#reject, Enumerable#grep.

Overloads:

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

    Yields:

    • (obj)

    Returns:

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

    Yields:

    • (obj)

    Returns:

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

    Yields:

    • (obj)

    Returns:



444
445
446
447
448
449
450
451
452
453
454
455
 
# File 'enum.c', line 444

static VALUE
enum_find_all(VALUE obj)
{
    VALUE ary;

    RETURN_SIZED_ENUMERATOR(obj, 0, 0, enum_size);

    ary = rb_ary_new();
    rb_block_call(obj, id_each, 0, 0, find_all_i, ary);

    return ary;
}

#filter_map {|obj| ... } ⇒ Array #filter_map ⇒ Object

Returns a new array containing the truthy results (everything except false or nil) of running the block for every element in enum.

If no block is given, an Enumerator is returned instead.

(1..10).filter_map { |i| i * 2 if i.even? } #=> [4, 8, 12, 16, 20]

Overloads:

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

    Yields:

    • (obj)

    Returns:



483
484
485
486
487
488
489
490
491
492
493
494
 
# File 'enum.c', line 483

static VALUE
enum_filter_map(VALUE obj)
{
    VALUE ary;

    RETURN_SIZED_ENUMERATOR(obj, 0, 0, enum_size);

    ary = rb_ary_new();
    rb_block_call(obj, id_each, 0, 0, filter_map_i, ary);

    return ary;
}

#detect(ifnone = nil) {|obj| ... } ⇒ Object? #find(ifnone = nil) {|obj| ... } ⇒ Object? #detect(ifnone = nil) ⇒ Object #find(ifnone = nil) ⇒ 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 otherwise.

If no block is given, an enumerator is returned instead.

(1..100).detect  #=> #<Enumerator: 1..100:detect>
(1..100).find    #=> #<Enumerator: 1..100:find>

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

Overloads:

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

    Yields:

    • (obj)

    Returns:

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

    Yields:

    • (obj)

    Returns:



292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
 
# File 'enum.c', line 292

static VALUE
enum_find(int argc, VALUE *argv, VALUE obj)
{
    struct MEMO *memo;
    VALUE if_none;

    if_none = rb_check_arity(argc, 0, 1) ? argv[0] : Qnil;
    RETURN_ENUMERATOR(obj, argc, argv);
    memo = MEMO_NEW(Qundef, 0, 0);
    rb_block_call(obj, id_each, 0, 0, find_i, (VALUE)memo);
    if (memo->u3.cnt) {
  return memo->v1;
    }
    if (!NIL_P(if_none)) {
  return rb_funcallv(if_none, id_call, 0, 0);
    }
    return Qnil;
}

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

Returns an array containing all elements of enum for which the given block returns a true value.

The find_all and select methods are aliases. There is no performance benefit to either.

If no block is given, an Enumerator is returned instead.

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

[1,2,3,4,5].select { |num|  num.even?  }   #=> [2, 4]

[:foo, :bar].filter { |x| x == :foo }   #=> [:foo]

See also Enumerable#reject, Enumerable#grep.

Overloads:

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

    Yields:

    • (obj)

    Returns:

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

    Yields:

    • (obj)

    Returns:

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

    Yields:

    • (obj)

    Returns:



444
445
446
447
448
449
450
451
452
453
454
455
 
# File 'enum.c', line 444

static VALUE
enum_find_all(VALUE obj)
{
    VALUE ary;

    RETURN_SIZED_ENUMERATOR(obj, 0, 0, enum_size);

    ary = rb_ary_new();
    rb_block_call(obj, id_each, 0, 0, find_all_i, ary);

    return ary;
}

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

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 && i % 7 == 0 }  #=> nil
(1..100).find_index { |i| i % 5 == 0 && i % 7 == 0 }  #=> 34
(1..100).find_index(50)                               #=> 49

Overloads:



358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
 
# File 'enum.c', line 358

static VALUE
enum_find_index(int argc, VALUE *argv, VALUE obj)
{
    struct MEMO *memo;  /* [return value, current index, ] */
    VALUE condition_value = Qnil;
    rb_block_call_func *func;

    if (argc == 0) {
        RETURN_ENUMERATOR(obj, 0, 0);
        func = find_index_iter_i;
    }
    else {
  rb_scan_args(argc, argv, "1", &condition_value);
  if (rb_block_given_p()) {
      rb_warn("given block not used");
  }
        func = find_index_i;
    }

    memo = MEMO_NEW(Qnil, condition_value, 0);
    rb_block_call(obj, id_each, 0, 0, func, (VALUE)memo);
    return memo->v1;
}

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

%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
[].first(10)              #=> []

Overloads:



1049
1050
1051
1052
1053
1054
1055
1056
1057
1058
1059
1060
1061
1062
 
# File 'enum.c', line 1049

static VALUE
enum_first(int argc, VALUE *argv, VALUE obj)
{
    struct MEMO *memo;
    rb_check_arity(argc, 0, 1);
    if (argc > 0) {
  return enum_take(obj, argv[0]);
    }
    else {
  memo = MEMO_NEW(Qnil, 0, 0);
  rb_block_call(obj, id_each, 0, 0, first_i, (VALUE)memo);
  return memo->v1;
    }
}

#flat_map {|obj| ... } ⇒ Array #collect_concat {|obj| ... } ⇒ Array #flat_map ⇒ Object #collect_concat ⇒ Object

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 { |e| [e, -e] } #=> [1, -1, 2, -2, 3, -3, 4, -4]
[[1, 2], [3, 4]].flat_map { |e| e + [100] } #=> [1, 2, 100, 3, 4, 100]

Overloads:

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

    Yields:

    • (obj)

    Returns:

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

    Yields:

    • (obj)

    Returns:



620
621
622
623
624
625
626
627
628
629
630
631
 
# File 'enum.c', line 620

static VALUE
enum_flat_map(VALUE obj)
{
    VALUE ary;

    RETURN_SIZED_ENUMERATOR(obj, 0, 0, enum_size);

    ary = rb_ary_new();
    rb_block_call(obj, id_each, 0, 0, flat_map_i, ary);

    return ary;
}

#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_SET, :SEEK_CUR, :SEEK_END]
res = c.grep(/SEEK/) { |v| IO.const_get(v) }
res                    #=> [0, 1, 2]

Overloads:

  • #grep(pattern) ⇒ Array

    Returns:

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

    Yields:

    • (obj)

    Returns:



108
109
110
111
112
113
114
115
116
117
 
# File 'enum.c', line 108

static VALUE
enum_grep(VALUE obj, VALUE pat)
{
    VALUE ary = rb_ary_new();
    struct MEMO *memo = MEMO_NEW(pat, ary, Qtrue);

    rb_block_call(obj, id_each, 0, 0, rb_block_given_p() ? grep_iter_i : grep_i, (VALUE)memo);

    return ary;
}

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

Inverted version of Enumerable#grep. Returns an array of every element in enum for which not Pattern === element.

(1..10).grep_v 2..5   #=> [1, 6, 7, 8, 9, 10]
res =(1..10).grep_v(2..5) { |v| v * 2 }
res                    #=> [2, 12, 14, 16, 18, 20]

Overloads:

  • #grep_v(pattern) ⇒ Array

    Returns:

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

    Yields:

    • (obj)

    Returns:



134
135
136
137
138
139
140
141
142
143
 
# File 'enum.c', line 134

static VALUE
enum_grep_v(VALUE obj, VALUE pat)
{
    VALUE ary = rb_ary_new();
    struct MEMO *memo = MEMO_NEW(pat, ary, Qfalse);

    rb_block_call(obj, id_each, 0, 0, rb_block_given_p() ? grep_iter_i : grep_i, (VALUE)memo);

    return ary;
}

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

Groups the collection by result of the block. Returns a hash where the keys are the evaluated result from the block and the values are arrays of elements in the collection that correspond to the key.

If no block is given an enumerator is returned.

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

Overloads:

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

    Yields:

    • (obj)

    Returns:



969
970
971
972
973
974
975
 
# File 'enum.c', line 969

static VALUE
enum_group_by(VALUE obj)
{
    RETURN_SIZED_ENUMERATOR(obj, 0, 0, enum_size);

    return enum_hashify(obj, 0, 0, group_by_i);
}

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

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

(1..10).include? 5  #=> true
(1..10).include? 15 #=> false
(1..10).member? 5   #=> true
(1..10).member? 15  #=> false

Overloads:

  • #include?(obj) ⇒ Boolean

    Returns:

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

    Returns:

    • (Boolean) 


2349
2350
2351
2352
2353
2354
2355
2356
 
# File 'enum.c', line 2349

static VALUE
enum_member(VALUE obj, VALUE val)
{
    struct MEMO *memo = MEMO_NEW(val, Qfalse, 0);

    rb_block_call(obj, id_each, 0, 0, member_i, (VALUE)memo);
    return memo->v2;
}

#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| ... } ⇒ Object

Combines all elements of enum by applying a binary operation, specified by a block or a symbol that names a method or operator.

The inject and reduce methods are aliases. There is no performance benefit to either.

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 the first element of collection is used as the initial value of memo.

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

  • #reduce(initial, sym) ⇒ Object

    Returns:

  • #reduce(sym) ⇒ Object

    Returns:

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

    Yields:

    • (memo, obj)

    Returns:

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

    Yields:

    • (memo, obj)

    Returns:



845
846
847
848
849
850
851
852
853
854
855
856
857
858
859
860
861
862
863
864
865
866
867
868
869
870
871
872
873
874
875
876
877
878
879
880
881
882
883
884
885
886
887
 
# File 'enum.c', line 845

static VALUE
enum_inject(int argc, VALUE *argv, VALUE obj)
{
    struct MEMO *memo;
    VALUE init, op;
    rb_block_call_func *iter = inject_i;
    ID id;

    switch (rb_scan_args(argc, argv, "02", &init, &op)) {
      case 0:
  init = Qundef;
  break;
      case 1:
  if (rb_block_given_p()) {
      break;
  }
  id = rb_check_id(&init);
  op = id ? ID2SYM(id) : init;
  init = Qundef;
  iter = inject_op_i;
  break;
      case 2:
  if (rb_block_given_p()) {
      rb_warning("given block not used");
  }
  id = rb_check_id(&op);
  if (id) op = ID2SYM(id);
  iter = inject_op_i;
  break;
    }

    if (iter == inject_op_i &&
        SYMBOL_P(op) &&
        RB_TYPE_P(obj, T_ARRAY) &&
        rb_method_basic_definition_p(CLASS_OF(obj), id_each)) {
        return ary_inject_op(obj, init, op);
    }

    memo = MEMO_NEW(init, Qnil, op);
    rb_block_call(obj, id_each, 0, 0, iter, (VALUE)memo);
    if (memo->v1 == Qundef) return Qnil;
    return memo->v1;
}

#lazy ⇒ Object

Returns an Enumerator::Lazy, which redefines most Enumerable methods to postpone enumeration and enumerate values only on an as-needed basis.

Example

The following program finds pythagorean triples:

def pythagorean_triples
  (1..Float::INFINITY).lazy.flat_map {|z|
    (1..z).flat_map {|x|
      (x..z).select {|y|
        x**2 + y**2 == z**2
      }.map {|y|
        [x, y, z]
      }
    }
  }
end
# show first ten pythagorean triples
p pythagorean_triples.take(10).force # take is lazy, so force is needed
p pythagorean_triples.first(10)      # first is eager
# show pythagorean triples less than 100
p pythagorean_triples.take_while { |*, z| z < 100 }.force



1884
1885
1886
1887
1888
1889
1890
1891
 
# File 'enumerator.c', line 1884

static VALUE
enumerable_lazy(VALUE obj)
{
    VALUE result = lazy_to_enum_i(obj, sym_each, 0, 0, lazyenum_size, PASS_KW_SPLAT);
    /* Qfalse indicates that the Enumerator::Lazy has no method name */
    rb_ivar_set(result, id_method, Qfalse);
    return result;
}

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

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).map { |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:



571
572
573
574
575
576
577
578
579
580
581
582
583
584
 
# File 'enum.c', line 571

static VALUE
enum_collect(VALUE obj)
{
    VALUE ary;
    int min_argc, max_argc;

    RETURN_SIZED_ENUMERATOR(obj, 0, 0, enum_size);

    ary = rb_ary_new();
    min_argc = rb_block_min_max_arity(&max_argc);
    rb_lambda_call(obj, id_each, 0, 0, collect_i, min_argc, max_argc, ary);

    return ary;
}

#max ⇒ Object #max {|a, b| ... } ⇒ Object #max(n) ⇒ Array #max(n) {|a, b| ... } ⇒ Array

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"

If the n argument is given, maximum n elements are returned as an array, sorted in descending order.

a = %w[albatross dog horse]
a.max(2)                                  #=> ["horse", "dog"]
a.max(2) {|a, b| a.length <=> b.length }  #=> ["albatross", "horse"]
[5, 1, 3, 4, 2].max(3)                    #=> [5, 4, 3]

Overloads:



1867
1868
1869
1870
1871
1872
1873
1874
1875
1876
1877
1878
1879
1880
1881
1882
1883
1884
1885
1886
1887
1888
1889
1890
 
# File 'enum.c', line 1867

static VALUE
enum_max(int argc, VALUE *argv, VALUE obj)
{
    VALUE memo;
    struct max_t *m = NEW_CMP_OPT_MEMO(struct max_t, memo);
    VALUE result;
    VALUE num;

    if (rb_check_arity(argc, 0, 1) && !NIL_P(num = argv[0]))
       return rb_nmin_run(obj, num, 0, 1, 0);

    m->max = Qundef;
    m->cmp_opt.opt_methods = 0;
    m->cmp_opt.opt_inited = 0;
    if (rb_block_given_p()) {
  rb_block_call(obj, id_each, 0, 0, max_ii, (VALUE)memo);
    }
    else {
  rb_block_call(obj, id_each, 0, 0, max_i, (VALUE)memo);
    }
    result = m->max;
    if (result == Qundef) return Qnil;
    return result;
}

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

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"

If the n argument is given, maximum n elements are returned as an array. These n elements are sorted by the value from the given block, in descending order.

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

enum.max_by(n) can be used to implement weighted random sampling. Following example implements and use Enumerable#wsample.

module Enumerable
  # weighted random sampling.
  #
  # Pavlos S. Efraimidis, Paul G. Spirakis
  # Weighted random sampling with a reservoir
  # Information Processing Letters
  # Volume 97, Issue 5 (16 March 2006)
  def wsample(n)
    self.max_by(n) {|v| rand ** (1.0/yield(v)) }
  end
end
e = (-20..20).to_a*10000
a = e.wsample(20000) {|x|
  Math.exp(-(x/5.0)**2) # normal distribution
}
# a is 20000 samples from e.
p a.length #=> 20000
h = a.group_by {|x| x }
-10.upto(10) {|x| puts "*" * (h[x].length/30.0).to_i if h[x] }
#=> *
#   ***
#   ******
#   ***********
#   ******************
#   *****************************
#   *****************************************
#   ****************************************************
#   ***************************************************************
#   ********************************************************************
#   ***********************************************************************
#   ***********************************************************************
#   **************************************************************
#   ****************************************************
#   ***************************************
#   ***************************
#   ******************
#   ***********
#   *******
#   ***
#   *

Overloads:

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

    Yields:

    • (obj)

    Returns:

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

    Yields:

    • (obj)

    Returns:



2195
2196
2197
2198
2199
2200
2201
2202
2203
2204
2205
2206
2207
2208
2209
2210
2211
 
# File 'enum.c', line 2195

static VALUE
enum_max_by(int argc, VALUE *argv, VALUE obj)
{
    struct MEMO *memo;
    VALUE num;

    rb_check_arity(argc, 0, 1);

    RETURN_SIZED_ENUMERATOR(obj, argc, argv, enum_size);

    if (argc && !NIL_P(num = argv[0]))
        return rb_nmin_run(obj, num, 1, 1, 0);

    memo = MEMO_NEW(Qundef, Qnil, 0);
    rb_block_call(obj, id_each, 0, 0, max_by_i, (VALUE)memo);
    return memo->v2;
}

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

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

(1..10).include? 5  #=> true
(1..10).include? 15 #=> false
(1..10).member? 5   #=> true
(1..10).member? 15  #=> false

Overloads:

  • #include?(obj) ⇒ Boolean

    Returns:

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

    Returns:

    • (Boolean) 


2349
2350
2351
2352
2353
2354
2355
2356
 
# File 'enum.c', line 2349

static VALUE
enum_member(VALUE obj, VALUE val)
{
    struct MEMO *memo = MEMO_NEW(val, Qfalse, 0);

    rb_block_call(obj, id_each, 0, 0, member_i, (VALUE)memo);
    return memo->v2;
}

#min ⇒ Object #min {|a, b| ... } ⇒ Object #min(n) ⇒ Array #min(n) {|a, b| ... } ⇒ Array

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"

If the n argument is given, minimum n elements are returned as a sorted array.

a = %w[albatross dog horse]
a.min(2)                                  #=> ["albatross", "dog"]
a.min(2) {|a, b| a.length <=> b.length }  #=> ["dog", "horse"]
[5, 1, 3, 4, 2].min(3)                    #=> [1, 2, 3]

Overloads:



1775
1776
1777
1778
1779
1780
1781
1782
1783
1784
1785
1786
1787
1788
1789
1790
1791
1792
1793
1794
1795
1796
1797
1798
 
# File 'enum.c', line 1775

static VALUE
enum_min(int argc, VALUE *argv, VALUE obj)
{
    VALUE memo;
    struct min_t *m = NEW_CMP_OPT_MEMO(struct min_t, memo);
    VALUE result;
    VALUE num;

    if (rb_check_arity(argc, 0, 1) && !NIL_P(num = argv[0]))
       return rb_nmin_run(obj, num, 0, 0, 0);

    m->min = Qundef;
    m->cmp_opt.opt_methods = 0;
    m->cmp_opt.opt_inited = 0;
    if (rb_block_given_p()) {
  rb_block_call(obj, id_each, 0, 0, min_ii, memo);
    }
    else {
  rb_block_call(obj, id_each, 0, 0, min_i, memo);
    }
    result = m->min;
    if (result == Qundef) return Qnil;
    return result;
}

#min_by {|obj| ... } ⇒ Object #min_by ⇒ Object #min_by(n) {|obj| ... } ⇒ Array #min_by(n) ⇒ Object

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"

If the n argument is given, minimum n elements are returned as an array. These n elements are sorted by the value from the given block.

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

Overloads:

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

    Yields:

    • (obj)

    Returns:

  • #min_by(n) {|obj| ... } ⇒ Array

    Yields:

    • (obj)

    Returns:



2088
2089
2090
2091
2092
2093
2094
2095
2096
2097
2098
2099
2100
2101
2102
2103
2104
 
# File 'enum.c', line 2088

static VALUE
enum_min_by(int argc, VALUE *argv, VALUE obj)
{
    struct MEMO *memo;
    VALUE num;

    rb_check_arity(argc, 0, 1);

    RETURN_SIZED_ENUMERATOR(obj, argc, argv, enum_size);

    if (argc && !NIL_P(num = argv[0]))
        return rb_nmin_run(obj, num, 1, 0, 0);

    memo = MEMO_NEW(Qundef, Qnil, 0);
    rb_block_call(obj, id_each, 0, 0, min_by_i, (VALUE)memo);
    return memo->v2;
}

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

Returns a two element 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:



2018
2019
2020
2021
2022
2023
2024
2025
2026
2027
2028
2029
2030
2031
2032
2033
2034
2035
2036
2037
2038
2039
2040
2041
2042
 
# File 'enum.c', line 2018

static VALUE
enum_minmax(VALUE obj)
{
    VALUE memo;
    struct minmax_t *m = NEW_CMP_OPT_MEMO(struct minmax_t, memo);

    m->min = Qundef;
    m->last = Qundef;
    m->cmp_opt.opt_methods = 0;
    m->cmp_opt.opt_inited = 0;
    if (rb_block_given_p()) {
  rb_block_call(obj, id_each, 0, 0, minmax_ii, memo);
  if (m->last != Qundef)
      minmax_ii_update(m->last, m->last, m);
    }
    else {
  rb_block_call(obj, id_each, 0, 0, minmax_i, memo);
  if (m->last != Qundef)
      minmax_i_update(m->last, m->last, m);
    }
    if (m->min != Qundef) {
  return rb_assoc_new(m->min, m->max);
    }
    return rb_assoc_new(Qnil, Qnil);
}

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

Returns a two element array containing the objects in enum that correspond to 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"]

Overloads:

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

    Yields:

    • (obj)

    Returns:



2301
2302
2303
2304
2305
2306
2307
2308
2309
2310
2311
2312
2313
2314
2315
2316
2317
2318
2319
2320
 
# File 'enum.c', line 2301

static VALUE
enum_minmax_by(VALUE obj)
{
    VALUE memo;
    struct minmax_by_t *m = NEW_MEMO_FOR(struct minmax_by_t, memo);

    RETURN_SIZED_ENUMERATOR(obj, 0, 0, enum_size);

    m->min_bv = Qundef;
    m->max_bv = Qundef;
    m->min = Qnil;
    m->max = Qnil;
    m->last_bv = Qundef;
    m->last = Qundef;
    rb_block_call(obj, id_each, 0, 0, minmax_by_i, memo);
    if (m->last_bv != Qundef)
        minmax_by_i_update(m->last_bv, m->last_bv, m->last, m->last, m);
    m = MEMO_FOR(struct minmax_by_t, memo);
    return rb_assoc_new(m->min, m->max);
}

#none? {|obj| ... } ⇒ Boolean #none?(pattern) ⇒ 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.

If instead a pattern is supplied, the method returns whether pattern === element for none of the collection members.

%w{ant bear cat}.none? { |word| word.length == 5 } #=> true
%w{ant bear cat}.none? { |word| word.length >= 4 } #=> false
%w{ant bear cat}.none?(/d/)                        #=> true
[1, 3.14, 42].none?(Float)                         #=> false
[].none?                                           #=> true
[nil].none?                                        #=> true
[nil, false].none?                                 #=> true
[nil, false, true].none?                           #=> false

Overloads:

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

    Yields:

    • (obj)

    Returns:

    • (Boolean)
  • #none?(pattern) ⇒ Boolean

    Returns:

    • (Boolean) 


1697
1698
1699
1700
1701
1702
1703
1704
1705
 
# File 'enum.c', line 1697

static VALUE
enum_none(int argc, VALUE *argv, VALUE obj)
{
    struct MEMO *memo = MEMO_ENUM_NEW(Qtrue);

    WARN_UNUSED_BLOCK(argc);
    rb_block_call(obj, id_each, 0, 0, ENUMFUNC(none), (VALUE)memo);
    return memo->v1;
}

#one? {|obj| ... } ⇒ Boolean #one?(pattern) ⇒ 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.

If instead a pattern is supplied, the method returns whether pattern === element for exactly one collection member.

%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
%w{ant bear cat}.one?(/t/)                         #=> false
[ nil, true, 99 ].one?                             #=> false
[ nil, true, false ].one?                          #=> true
[ nil, true, 99 ].one?(Integer)                    #=> true
[].one?                                            #=> false

Overloads:

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

    Yields:

    • (obj)

    Returns:

    • (Boolean)
  • #one?(pattern) ⇒ Boolean

    Returns:

    • (Boolean) 


1653
1654
1655
1656
1657
1658
1659
1660
1661
1662
1663
1664
 
# File 'enum.c', line 1653

static VALUE
enum_one(int argc, VALUE *argv, VALUE obj)
{
    struct MEMO *memo = MEMO_ENUM_NEW(Qundef);
    VALUE result;

    WARN_UNUSED_BLOCK(argc);
    rb_block_call(obj, id_each, 0, 0, ENUMFUNC(one), (VALUE)memo);
    result = memo->v1;
    if (result == Qundef) return Qfalse;
    return result;
}

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

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

Overloads:

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

    Yields:

    • (obj)

    Returns:



921
922
923
924
925
926
927
928
929
930
931
932
 
# File 'enum.c', line 921

static VALUE
enum_partition(VALUE obj)
{
    struct MEMO *memo;

    RETURN_SIZED_ENUMERATOR(obj, 0, 0, enum_size);

    memo = MEMO_NEW(rb_ary_new(), rb_ary_new(), 0);
    rb_block_call(obj, id_each, 0, 0, partition_i, (VALUE)memo);

    return rb_assoc_new(memo->v1, memo->v2);
}

#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| ... } ⇒ Object

Combines all elements of enum by applying a binary operation, specified by a block or a symbol that names a method or operator.

The inject and reduce methods are aliases. There is no performance benefit to either.

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 the first element of collection is used as the initial value of memo.

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

  • #reduce(initial, sym) ⇒ Object

    Returns:

  • #reduce(sym) ⇒ Object

    Returns:

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

    Yields:

    • (memo, obj)

    Returns:

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

    Yields:

    • (memo, obj)

    Returns:



845
846
847
848
849
850
851
852
853
854
855
856
857
858
859
860
861
862
863
864
865
866
867
868
869
870
871
872
873
874
875
876
877
878
879
880
881
882
883
884
885
886
887
 
# File 'enum.c', line 845

static VALUE
enum_inject(int argc, VALUE *argv, VALUE obj)
{
    struct MEMO *memo;
    VALUE init, op;
    rb_block_call_func *iter = inject_i;
    ID id;

    switch (rb_scan_args(argc, argv, "02", &init, &op)) {
      case 0:
  init = Qundef;
  break;
      case 1:
  if (rb_block_given_p()) {
      break;
  }
  id = rb_check_id(&init);
  op = id ? ID2SYM(id) : init;
  init = Qundef;
  iter = inject_op_i;
  break;
      case 2:
  if (rb_block_given_p()) {
      rb_warning("given block not used");
  }
  id = rb_check_id(&op);
  if (id) op = ID2SYM(id);
  iter = inject_op_i;
  break;
    }

    if (iter == inject_op_i &&
        SYMBOL_P(op) &&
        RB_TYPE_P(obj, T_ARRAY) &&
        rb_method_basic_definition_p(CLASS_OF(obj), id_each)) {
        return ary_inject_op(obj, init, op);
    }

    memo = MEMO_NEW(init, Qnil, op);
    rb_block_call(obj, id_each, 0, 0, iter, (VALUE)memo);
    if (memo->v1 == Qundef) return Qnil;
    return memo->v1;
}

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

Returns an array for all elements of enum for which the given block returns false.

If no block is given, an Enumerator is returned instead.

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

[1, 2, 3, 4, 5].reject { |num| num.even? } #=> [1, 3, 5]

See also Enumerable#find_all.

Overloads:

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

    Yields:

    • (obj)

    Returns:



525
526
527
528
529
530
531
532
533
534
535
536
 
# File 'enum.c', line 525

static VALUE
enum_reject(VALUE obj)
{
    VALUE ary;

    RETURN_SIZED_ENUMERATOR(obj, 0, 0, enum_size);

    ary = rb_ary_new();
    rb_block_call(obj, id_each, 0, 0, reject_i, ary);

    return ary;
}

#reverse_each(*args) {|item| ... } ⇒ Enumerator #reverse_each(*args) ⇒ Object

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

Overloads:



2418
2419
2420
2421
2422
2423
2424
2425
2426
2427
2428
2429
2430
2431
2432
2433
2434
2435
2436
2437
2438
2439
 
# File 'enum.c', line 2418

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

    RETURN_SIZED_ENUMERATOR(obj, argc, argv, enum_size);

    ary = enum_to_a(argc, argv, obj);

    len = RARRAY_LEN(ary);
    while (len--) {
        long nlen;
        rb_yield(RARRAY_AREF(ary, len));
        nlen = RARRAY_LEN(ary);
        if (nlen < len) {
            len = nlen;
        }
    }

    return obj;
}

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

Returns an array containing all elements of enum for which the given block returns a true value.

The find_all and select methods are aliases. There is no performance benefit to either.

If no block is given, an Enumerator is returned instead.

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

[1,2,3,4,5].select { |num|  num.even?  }   #=> [2, 4]

[:foo, :bar].filter { |x| x == :foo }   #=> [:foo]

See also Enumerable#reject, Enumerable#grep.

Overloads:

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

    Yields:

    • (obj)

    Returns:

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

    Yields:

    • (obj)

    Returns:

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

    Yields:

    • (obj)

    Returns:



444
445
446
447
448
449
450
451
452
453
454
455
 
# File 'enum.c', line 444

static VALUE
enum_find_all(VALUE obj)
{
    VALUE ary;

    RETURN_SIZED_ENUMERATOR(obj, 0, 0, enum_size);

    ary = rb_ary_new();
    rb_block_call(obj, id_each, 0, 0, find_all_i, ary);

    return ary;
}

#slice_after(pattern) ⇒ Object #slice_after {|elt| ... } ⇒ Object

Creates an enumerator for each chunked elements. The ends of chunks are defined by pattern and the block.

If pattern === elt returns true or the block returns true for the element, the element is end of a chunk.

The === and block is called from the first element to the last element of enum.

The result enumerator yields the chunked elements as an array. So each method can be called as follows:

enum.slice_after(pattern).each { |ary| ... }
enum.slice_after { |elt| bool }.each { |ary| ... }

Other methods of the Enumerator class and Enumerable module, such as map, etc., are also usable.

For example, continuation lines (lines end with backslash) can be concatenated as follows:

lines = ["foo\n", "bar\\\n", "baz\n", "\n", "qux\n"]
e = lines.slice_after(/(?<!\\)\n\z/)
p e.to_a
#=> [["foo\n"], ["bar\\\n", "baz\n"], ["\n"], ["qux\n"]]
p e.map {|ll| ll[0...-1].map {|l| l.sub(/\\\n\z/, "") }.join + ll.last }
#=>["foo\n", "barbaz\n", "\n", "qux\n"]

Overloads:

  • #slice_after {|elt| ... } ⇒ Object

    Yields:

    • (elt) 


3595
3596
3597
3598
3599
3600
3601
3602
3603
3604
3605
3606
3607
3608
3609
3610
3611
3612
3613
3614
3615
3616
3617
 
# File 'enum.c', line 3595

static VALUE
enum_slice_after(int argc, VALUE *argv, VALUE enumerable)
{
    VALUE enumerator;
    VALUE pat = Qnil, pred = Qnil;

    if (rb_block_given_p()) {
        if (0 < argc)
            rb_raise(rb_eArgError, "both pattern and block are given");
        pred = rb_block_proc();
    }
    else {
        rb_scan_args(argc, argv, "1", &pat);
    }

    enumerator = rb_obj_alloc(rb_cEnumerator);
    rb_ivar_set(enumerator, rb_intern("sliceafter_enum"), enumerable);
    rb_ivar_set(enumerator, rb_intern("sliceafter_pat"), pat);
    rb_ivar_set(enumerator, rb_intern("sliceafter_pred"), pred);

    rb_block_call(enumerator, idInitialize, 0, 0, sliceafter_i, enumerator);
    return enumerator;
}

#slice_before(pattern) ⇒ Object #slice_before {|elt| ... } ⇒ Object

Creates an enumerator for each chunked elements. The beginnings of chunks are defined by pattern and the block.

If pattern === elt returns true or the block returns true for the element, the element is beginning of a chunk.

The === and block is called from the first element to the last element of enum. The result for the first element is ignored.

The result enumerator yields the chunked elements as an array. So each method can be called as follows:

enum.slice_before(pattern).each { |ary| ... }
enum.slice_before { |elt| bool }.each { |ary| ... }

Other methods of the Enumerator class and Enumerable module, such as to_a, map, etc., are also usable.

For example, iteration over ChangeLog entries can be implemented as follows:

# iterate over ChangeLog entries.
open("ChangeLog") { |f|
  f.slice_before(/\A\S/).each { |e| pp e }
}

# same as above.  block is used instead of pattern argument.
open("ChangeLog") { |f|
  f.slice_before { |line| /\A\S/ === line }.each { |e| pp e }
}

“svn proplist -R” produces multiline output for each file. They can be chunked as follows:

IO.popen([{"LC_ALL"=>"C"}, "svn", "proplist", "-R"]) { |f|
  f.lines.slice_before(/\AProp/).each { |lines| p lines }
}
#=> ["Properties on '.':\n", "  svn:ignore\n", "  svk:merge\n"]
#   ["Properties on 'goruby.c':\n", "  svn:eol-style\n"]
#   ["Properties on 'complex.c':\n", "  svn:mime-type\n", "  svn:eol-style\n"]
#   ["Properties on 'regparse.c':\n", "  svn:eol-style\n"]
#   ...

If the block needs to maintain state over multiple elements, local variables can be used. For example, three or more consecutive increasing numbers can be squashed as follows (see chunk_while for a better way):

a = [0, 2, 3, 4, 6, 7, 9]
prev = a[0]
p a.slice_before { |e|
  prev, prev2 = e, prev
  prev2 + 1 != e
}.map { |es|
  es.length <= 2 ? es.join(",") : "#{es.first}-#{es.last}"
}.join(",")
#=> "0,2-4,6,7,9"

However local variables should be used carefully if the result enumerator is enumerated twice or more. The local variables should be initialized for each enumeration. Enumerator.new can be used to do it.

# Word wrapping.  This assumes all characters have same width.
def wordwrap(words, maxwidth)
  Enumerator.new {|y|
    # cols is initialized in Enumerator.new.
    cols = 0
    words.slice_before { |w|
      cols += 1 if cols != 0
      cols += w.length
      if maxwidth < cols
        cols = w.length
        true
      else
        false
      end
    }.each {|ws| y.yield ws }
  }
end
text = (1..20).to_a.join(" ")
enum = wordwrap(text.split(/\s+/), 10)
puts "-"*10
enum.each { |ws| puts ws.join(" ") } # first enumeration.
puts "-"*10
enum.each { |ws| puts ws.join(" ") } # second enumeration generates same result as the first.
puts "-"*10
#=> ----------
#   1 2 3 4 5
#   6 7 8 9 10
#   11 12 13
#   14 15 16
#   17 18 19
#   20
#   ----------
#   1 2 3 4 5
#   6 7 8 9 10
#   11 12 13
#   14 15 16
#   17 18 19
#   20
#   ----------

mbox contains series of mails which start with Unix From line. So each mail can be extracted by slice before Unix From line.

# parse mbox
open("mbox") { |f|
  f.slice_before { |line|
    line.start_with? "From "
  }.each { |mail|
    unix_from = mail.shift
    i = mail.index("\n")
    header = mail[0...i]
    body = mail[(i+1)..-1]
    body.pop if body.last == "\n"
    fields = header.slice_before { |line| !" \t".include?(line[0]) }.to_a
    p unix_from
    pp fields
    pp body
  }
}

# split mails in mbox (slice before Unix From line after an empty line)
open("mbox") { |f|
  emp = true
  f.slice_before { |line|
    prevemp = emp
    emp = line == "\n"
    prevemp && line.start_with?("From ")
  }.each { |mail|
    mail.pop if mail.last == "\n"
    pp mail
  }
}

Overloads:

  • #slice_before {|elt| ... } ⇒ Object

    Yields:

    • (elt) 


3473
3474
3475
3476
3477
3478
3479
3480
3481
3482
3483
3484
3485
3486
3487
3488
3489
3490
3491
3492
3493
 
# File 'enum.c', line 3473

static VALUE
enum_slice_before(int argc, VALUE *argv, VALUE enumerable)
{
    VALUE enumerator;

    if (rb_block_given_p()) {
        if (argc != 0)
            rb_error_arity(argc, 0, 0);
        enumerator = rb_obj_alloc(rb_cEnumerator);
        rb_ivar_set(enumerator, rb_intern("slicebefore_sep_pred"), rb_block_proc());
    }
    else {
        VALUE sep_pat;
        rb_scan_args(argc, argv, "1", &sep_pat);
        enumerator = rb_obj_alloc(rb_cEnumerator);
        rb_ivar_set(enumerator, rb_intern("slicebefore_sep_pat"), sep_pat);
    }
    rb_ivar_set(enumerator, rb_intern("slicebefore_enumerable"), enumerable);
    rb_block_call(enumerator, idInitialize, 0, 0, slicebefore_i, enumerator);
    return enumerator;
}

#slice_when {|elt_before, elt_after| ... } ⇒ Object

Creates an enumerator for each chunked elements. The beginnings of chunks are defined by the block.

This method split each chunk using adjacent elements, elt_before and elt_after, in the receiver enumerator. This method split chunks between elt_before and elt_after where the block returns true.

The block is called the length of the receiver enumerator minus one.

The result enumerator yields the chunked elements as an array. So each method can be called as follows:

enum.slice_when { |elt_before, elt_after| bool }.each { |ary| ... }

Other methods of the Enumerator class and Enumerable module, such as to_a, map, etc., are also usable.

For example, one-by-one increasing subsequence can be chunked as follows:

a = [1,2,4,9,10,11,12,15,16,19,20,21]
b = a.slice_when {|i, j| i+1 != j }
p b.to_a #=> [[1, 2], [4], [9, 10, 11, 12], [15, 16], [19, 20, 21]]
c = b.map {|a| a.length < 3 ? a : "#{a.first}-#{a.last}" }
p c #=> [[1, 2], [4], "9-12", [15, 16], "19-21"]
d = c.join(",")
p d #=> "1,2,4,9-12,15,16,19-21"

Near elements (threshold: 6) in sorted array can be chunked as follows:

a = [3, 11, 14, 25, 28, 29, 29, 41, 55, 57]
p a.slice_when {|i, j| 6 < j - i }.to_a
#=> [[3], [11, 14], [25, 28, 29, 29], [41], [55, 57]]

Increasing (non-decreasing) subsequence can be chunked as follows:

a = [0, 9, 2, 2, 3, 2, 7, 5, 9, 5]
p a.slice_when {|i, j| i > j }.to_a
#=> [[0, 9], [2, 2, 3], [2, 7], [5, 9], [5]]

Adjacent evens and odds can be chunked as follows: (Enumerable#chunk is another way to do it.)

a = [7, 5, 9, 2, 0, 7, 9, 4, 2, 0]
p a.slice_when {|i, j| i.even? != j.even? }.to_a
#=> [[7, 5, 9], [2, 0], [7, 9], [4, 2, 0]]

Paragraphs (non-empty lines with trailing empty lines) can be chunked as follows: (See Enumerable#chunk to ignore empty lines.)

lines = ["foo\n", "bar\n", "\n", "baz\n", "qux\n"]
p lines.slice_when {|l1, l2| /\A\s*\z/ =~ l1 && /\S/ =~ l2 }.to_a
#=> [["foo\n", "bar\n", "\n"], ["baz\n", "qux\n"]]

Enumerable#chunk_while does the same, except splitting when the block returns false instead of true.

Yields:

  • (elt_before, elt_after) 


3752
3753
3754
3755
3756
3757
3758
3759
3760
3761
3762
3763
3764
3765
3766
3767
 
# File 'enum.c', line 3752

static VALUE
enum_slice_when(VALUE enumerable)
{
    VALUE enumerator;
    VALUE pred;

    pred = rb_block_proc();

    enumerator = rb_obj_alloc(rb_cEnumerator);
    rb_ivar_set(enumerator, rb_intern("slicewhen_enum"), enumerable);
    rb_ivar_set(enumerator, rb_intern("slicewhen_pred"), pred);
    rb_ivar_set(enumerator, rb_intern("slicewhen_inverted"), Qfalse);

    rb_block_call(enumerator, idInitialize, 0, 0, slicewhen_i, enumerator);
    return enumerator;
}

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

Returns an array containing the items in enum sorted.

Comparisons for the sort will be done using the items’ own <=> operator or using an optional code block.

The block must implement a comparison between a and b and return an integer less than 0 when b follows a, 0 when a and b are equivalent, or an integer greater than 0 when a follows b.

The result is not guaranteed to be stable. When the comparison of two elements returns 0, the order of the elements is unpredictable.

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

See also Enumerable#sort_by. It implements a Schwartzian transform which is useful when key computation or comparison is expensive.

Overloads:



1089
1090
1091
1092
1093
 
# File 'enum.c', line 1089

static VALUE
enum_sort(VALUE obj)
{
    return rb_ary_sort_bang(enum_to_a(0, 0, obj));
}

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

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

The result is not guaranteed to be stable. When two keys are equal, the order of the corresponding elements is unpredictable.

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

To produce the reverse of a specific order, the following can be used:

ary.sort_by { ... }.reverse!

Overloads:

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

    Yields:

    • (obj)

    Returns:



1226
1227
1228
1229
1230
1231
1232
1233
1234
1235
1236
1237
1238
1239
1240
1241
1242
1243
1244
1245
1246
1247
1248
1249
1250
1251
1252
1253
1254
1255
1256
1257
1258
1259
1260
1261
1262
1263
1264
1265
1266
1267
1268
1269
1270
1271
1272
 
# File 'enum.c', line 1226

static VALUE
enum_sort_by(VALUE obj)
{
    VALUE ary, buf;
    struct MEMO *memo;
    long i;
    struct sort_by_data *data;

    RETURN_SIZED_ENUMERATOR(obj, 0, 0, enum_size);

    if (RB_TYPE_P(obj, T_ARRAY) && RARRAY_LEN(obj) <= LONG_MAX/2) {
  ary = rb_ary_new2(RARRAY_LEN(obj)*2);
    }
    else {
  ary = rb_ary_new();
    }
    RBASIC_CLEAR_CLASS(ary);
    buf = rb_ary_tmp_new(SORT_BY_BUFSIZE*2);
    rb_ary_store(buf, SORT_BY_BUFSIZE*2-1, Qnil);
    memo = MEMO_NEW(0, 0, 0);
    data = (struct sort_by_data *)&memo->v1;
    RB_OBJ_WRITE(memo, &data->ary, ary);
    RB_OBJ_WRITE(memo, &data->buf, buf);
    data->n = 0;
    rb_block_call(obj, id_each, 0, 0, sort_by_i, (VALUE)memo);
    ary = data->ary;
    buf = data->buf;
    if (data->n) {
  rb_ary_resize(buf, data->n*2);
  rb_ary_concat(ary, buf);
    }
    if (RARRAY_LEN(ary) > 2) {
        RARRAY_PTR_USE(ary, ptr,
                       ruby_qsort(ptr, RARRAY_LEN(ary)/2, 2*sizeof(VALUE),
                                  sort_by_cmp, (void *)ary));
    }
    if (RBASIC(ary)->klass) {
  rb_raise(rb_eRuntimeError, "sort_by reentered");
    }
    for (i=1; i<RARRAY_LEN(ary); i+=2) {
  RARRAY_ASET(ary, i/2, RARRAY_AREF(ary, i));
    }
    rb_ary_resize(ary, RARRAY_LEN(ary)/2);
    RBASIC_SET_CLASS_RAW(ary, rb_cArray);

    return ary;
}

#sum(init = 0) ⇒ Numeric #sum(init = 0) {|e| ... } ⇒ Numeric

Returns the sum of elements in an Enumerable.

If a block is given, the block is applied to each element before addition.

If enum is empty, it returns init.

For example:

{ 1 => 10, 2 => 20 }.sum {|k, v| k * v }  #=> 50
(1..10).sum                               #=> 55
(1..10).sum {|v| v * 2 }                  #=> 110
('a'..'z').sum                            #=> TypeError

This method can be used for non-numeric objects by explicit init argument.

{ 1 => 10, 2 => 20 }.sum([])                   #=> [1, 10, 2, 20]
"a\nb\nc".each_line.lazy.map(&:chomp).sum("")  #=> "abc"

If the method is applied to an Integer range without a block, the sum is not done by iteration, but instead using Gauss’s summation formula.

Enumerable#sum method may not respect method redefinition of “+” methods such as Integer#+, or “each” methods such as Range#each.

Overloads:



4039
4040
4041
4042
4043
4044
4045
4046
4047
4048
4049
4050
4051
4052
4053
4054
4055
4056
4057
4058
4059
4060
4061
4062
4063
4064
4065
4066
4067
4068
4069
4070
4071
4072
4073
4074
4075
4076
4077
4078
4079
4080
4081
4082
4083
4084
4085
4086
4087
4088
4089
4090
4091
 
# File 'enum.c', line 4039

static VALUE
enum_sum(int argc, VALUE* argv, VALUE obj)
{
    struct enum_sum_memo memo;
    VALUE beg, end;
    int excl;

    memo.v = (rb_check_arity(argc, 0, 1) == 0) ? LONG2FIX(0) : argv[0];
    memo.block_given = rb_block_given_p();
    memo.n = 0;
    memo.r = Qundef;

    if ((memo.float_value = RB_FLOAT_TYPE_P(memo.v))) {
        memo.f = RFLOAT_VALUE(memo.v);
        memo.c = 0.0;
    }
    else {
        memo.f = 0.0;
        memo.c = 0.0;
    }

    if (RTEST(rb_range_values(obj, &beg, &end, &excl))) {
        if (!memo.block_given && !memo.float_value &&
                (FIXNUM_P(beg) || RB_TYPE_P(beg, T_BIGNUM)) &&
                (FIXNUM_P(end) || RB_TYPE_P(end, T_BIGNUM))) {
            return int_range_sum(beg, end, excl, memo.v);
        }
    }

    if (RB_TYPE_P(obj, T_HASH) &&
            rb_method_basic_definition_p(CLASS_OF(obj), id_each))
        hash_sum(obj, &memo);
    else
        rb_block_call(obj, id_each, 0, 0, enum_sum_i, (VALUE)&memo);

    if (memo.float_value) {
        return DBL2NUM(memo.f + memo.c);
    }
    else {
        if (memo.n != 0)
            memo.v = rb_fix_plus(LONG2FIX(memo.n), memo.v);
        if (memo.r != Qundef) {
            /* r can be an Integer when mathn is loaded */
            if (FIXNUM_P(memo.r))
                memo.v = rb_fix_plus(memo.r, memo.v);
            else if (RB_TYPE_P(memo.r, T_BIGNUM))
                memo.v = rb_big_plus(memo.r, memo.v);
            else
                memo.v = rb_rational_plus(memo.r, memo.v);
        }
        return memo.v;
    }
}

#take(n) ⇒ Array

Returns first n elements from enum.

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

Returns:



2870
2871
2872
2873
2874
2875
2876
2877
2878
2879
2880
2881
2882
2883
2884
2885
2886
 
# File 'enum.c', line 2870

static VALUE
enum_take(VALUE obj, VALUE n)
{
    struct MEMO *memo;
    VALUE result;
    long len = NUM2LONG(n);

    if (len < 0) {
  rb_raise(rb_eArgError, "attempt to take negative size");
    }

    if (len == 0) return rb_ary_new2(0);
    result = rb_ary_new2(len);
    memo = MEMO_NEW(result, 0, len);
    rb_block_call(obj, id_each, 0, 0, take_i, (VALUE)memo);
    return result;
}

#take_while {|obj| ... } ⇒ Array #take_while ⇒ Object

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]

Overloads:

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

    Yields:

    • (obj)

    Returns:



2912
2913
2914
2915
2916
2917
2918
2919
2920
2921
 
# File 'enum.c', line 2912

static VALUE
enum_take_while(VALUE obj)
{
    VALUE ary;

    RETURN_ENUMERATOR(obj, 0, 0);
    ary = rb_ary_new();
    rb_block_call(obj, id_each, 0, 0, take_while_i, ary);
    return ary;
}

#tally ⇒ Hash

Tallies the collection, i.e., counts the occurrences of each element. Returns a hash with the elements of the collection as keys and the corresponding counts as values.

["a", "b", "c", "b"].tally  #=> {"a"=>1, "b"=>2, "c"=>1}

Returns:



1012
1013
1014
1015
1016
 
# File 'enum.c', line 1012

static VALUE
enum_tally(VALUE obj)
{
    return enum_hashify(obj, 0, 0, tally_i);
}

#to_a(*args) ⇒ Array #entries(*args) ⇒ 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]]

require 'prime'
Prime.entries 10                  #=> [2, 3, 5, 7]

Overloads:



646
647
648
649
650
651
652
653
654
 
# File 'enum.c', line 646

static VALUE
enum_to_a(int argc, VALUE *argv, VALUE obj)
{
    VALUE ary = rb_ary_new();

    rb_block_call(obj, id_each, argc, argv, collect_all, ary);

    return ary;
}

#to_h(*args) ⇒ Hash #to_h(*args) { ... } ⇒ Hash

Returns the result of interpreting enum as a list of [key, value] pairs.

i[hello world].each_with_index.to_h
  # => {:hello => 0, :world => 1}

If a block is given, the results of the block on each element of the enum will be used as pairs.

(1..5).to_h {|x| [x, x ** 2]}
  #=> {1=>1, 2=>4, 3=>9, 4=>16, 5=>25}

Overloads:

  • #to_h(*args) ⇒ Hash

    Returns:

  • #to_h(*args) { ... } ⇒ Hash

    Yields:

    Returns:



695
696
697
698
699
700
 
# File 'enum.c', line 695

static VALUE
enum_to_h(int argc, VALUE *argv, VALUE obj)
{
    rb_block_call_func *iter = rb_block_given_p() ? enum_to_h_ii : enum_to_h_i;
    return enum_hashify(obj, argc, argv, iter);
}

#uniq ⇒ Array #uniq {|item| ... } ⇒ Array

Returns a new array by removing duplicate values in self.

See also Array#uniq.

Overloads:



4119
4120
4121
4122
4123
4124
4125
4126
4127
4128
4129
4130
4131
 
# File 'enum.c', line 4119

static VALUE
enum_uniq(VALUE obj)
{
    VALUE hash, ret;
    rb_block_call_func *const func =
  rb_block_given_p() ? uniq_iter : uniq_func;

    hash = rb_obj_hide(rb_hash_new());
    rb_block_call(obj, id_each, 0, 0, func, hash);
    ret = rb_hash_values(hash);
    rb_hash_clear(hash);
    return ret;
}

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

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 ]

a.zip(b)                 #=> [[4, 7], [5, 8], [6, 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]]

c = []
a.zip(b) { |x, y| c << x + y }  #=> nil
c                               #=> [11, 13, 15]

Overloads:

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

    Yields:

    • (arr)

    Returns:

    • (nil) 


2808
2809
2810
2811
2812
2813
2814
2815
2816
2817
2818
2819
2820
2821
2822
2823
2824
2825
2826
2827
2828
2829
2830
2831
2832
2833
2834
2835
2836
2837
2838
2839
2840
2841
2842
2843
2844
2845
2846
2847
 
# File 'enum.c', line 2808

static VALUE
enum_zip(int argc, VALUE *argv, VALUE obj)
{
    int i;
    ID conv;
    struct MEMO *memo;
    VALUE result = Qnil;
    VALUE args = rb_ary_new4(argc, argv);
    int allary = TRUE;

    argv = RARRAY_PTR(args);
    for (i=0; i<argc; i++) {
  VALUE ary = rb_check_array_type(argv[i]);
  if (NIL_P(ary)) {
      allary = FALSE;
      break;
  }
  argv[i] = ary;
    }
    if (!allary) {
  static const VALUE sym_each = STATIC_ID2SYM(id_each);
  CONST_ID(conv, "to_enum");
  for (i=0; i<argc; i++) {
      if (!rb_respond_to(argv[i], id_each)) {
    rb_raise(rb_eTypeError, "wrong argument type %"PRIsVALUE" (must respond to :each)",
       rb_obj_class(argv[i]));
            }
      argv[i] = rb_funcallv(argv[i], conv, 1, &sym_each);
  }
    }
    if (!rb_block_given_p()) {
  result = rb_ary_new();
    }

    /* TODO: use NODE_DOT2 as memo(v, v, -) */
    memo = MEMO_NEW(result, args, 0);
    rb_block_call(obj, id_each, 0, 0, allary ? zip_ary : zip_i, (VALUE)memo);

    return result;
}