Passes each element of the collection to the given block. The methodreturnstrue if the block never returnsfalse ornil. If the block is not given, Ruby adds an implicit block of{ |obj| obj } which will causeall? to returntruewhen none of the collection members arefalse ornil.

If instead a pattern is supplied, the method returns whetherpattern=== 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

                static VALUEenum_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;}

Passes each element of the collection to the given block. The methodreturnstrue if the block ever returns a value other thanfalse ornil. If the block is not given, Rubyadds an implicit block of{ |obj| obj } that will causeany? to returntrueif at least one of the collection members is notfalse ornil.

If instead a pattern is supplied, the method returns whetherpattern=== 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

                static VALUEenum_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;}

Returns an enumerator object generated from this enumerator and givenenumerables.

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

                static VALUEenum_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);}

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

Consecutive elements which return the same block value are chunkedtogether.

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

[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. Thefollowing example counts words for each initial letter.

open("/usr/share/dict/words","r:iso-8859-1") {|f|f.chunk {|line|line.upcase.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 elementsshould be dropped.

• :_alone specifies that the element should be chunked byitself.

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

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

sep ="-"*72+"\n"IO.popen("svn log README") {|f|f.chunk {|line|line!=sep||nil  }.each {|_,lines|pplines  }}#=> ["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|pplines}

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

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

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

                static VALUEenum_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;}

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

This method splits each chunk using adjacent elements,elt_beforeandelt_after, in the receiver enumerator. This method splitchunks betweenelt_before andelt_after where the blockreturnsfalse.

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

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

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

Other methods of theEnumerator class andEnumerable module, such asto_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 }pb.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}" }pc#=> [[1, 2], [4], "9-12", [15, 16], "19-21"]d =c.join(",")pd#=> "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]pa.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 isanother way to do it.)

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

#slice_when does thesame, except splitting when the block returnstrue instead offalse.

                static VALUEenum_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;}

Returns a new array with the results of runningblock once forevery element inenum.

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

                static VALUEenum_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;}

Returns a new array with the concatenated results of runningblockonce for every element inenum.

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]

                static VALUEenum_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;}

Returns the number of items inenum through enumeration. If anargument is given, the number of items inenum that are equaltoitem are counted. If a block is given, it counts thenumber of elements yielding a true value.

ary = [1,2,4,2]ary.count#=> 4ary.count(2)#=> 2ary.count{|x|x%2==0 }#=> 3

                static VALUEenum_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);}

Callsblock for each element ofenum repeatedlyn times or forever if none ornil is given. If anon-positive number is given or the collection is empty, does nothing. Returnsnil if the loop has finished without gettinginterrupted.

#cycle saves elements in aninternal array so changes toenum after the first pass have noeffect.

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

a = ["a","b","c"]a.cycle {|x|putsx }# print, a, b, c, a, b, c,.. forever.a.cycle(2) {|x|putsx }# print, a, b, c, a, b, c.

                static VALUEenum_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;}

Passes each entry inenum toblock. Returns the first forwhichblock is not false. If no object matches, callsifnone and returns its result when it is specified, or returnsnil 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

                static VALUEenum_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;}

Drops first n elements fromenum, and returns rest elements in anarray.

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

                static VALUEenum_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;}

Drops elements up to, but not including, the first element for which theblock returnsnil orfalse and returns an arraycontaining 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]

                static VALUEenum_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;}

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|pa }# 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]

                static VALUEenum_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;}

Callsblock once for each element inself, passingthat element as a parameter, converting multiple values from yield to anarray.

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

classFooincludeEnumerabledefeachyield1yield1,2yieldendendFoo.new.each_entry{|o|po }

produces:

1[1,2]nil

                static VALUEenum_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;}

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

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

                static VALUEenum_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;}

Callsblock with two arguments, the item and its index, for eachitem inenum. 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}

                static VALUEenum_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;}

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]

                static VALUEenum_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;}

Returns an array containing the items inenum.

(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.entries10#=> [2, 3, 5, 7]

                static VALUEenum_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;}

Returns an array containing all elements ofenum for which thegivenblock returns a true value.

Thefind_all andselect methods are aliases. There is noperformance benefit to either.

If no block is given, anEnumerator isreturned 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#reject,#grep.

                static VALUEenum_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;}

Returns a new array containing the truthy results (everything exceptfalse ornil) of running theblockfor every element inenum.

If no block is given, anEnumerator isreturned instead.

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

                static VALUEenum_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;}

Passes each entry inenum toblock. Returns the first forwhichblock is not false. If no object matches, callsifnone and returns its result when it is specified, or returnsnil 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

                static VALUEenum_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;}

Returns an array containing all elements ofenum for which thegivenblock returns a true value.

Thefind_all andselect methods are aliases. There is noperformance benefit to either.

If no block is given, anEnumerator isreturned 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#reject,#grep.

                static VALUEenum_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;}

Compares each entry inenum withvalue or passes toblock. Returns the index for the first for which the evaluatedvalue is non-false. If no object matches, returnsnil

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

                static VALUEenum_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;}

Returns the first element, or the firstn elements, of theenumerable. If the enumerable is empty, the first form returnsnil, 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)#=> []

                static VALUEenum_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;    }}

Returns a new array with the concatenated results of runningblockonce for every element inenum.

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]

                static VALUEenum_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;}

Returns an array of every element inenum for whichPattern=== element. If the optionalblock is supplied, eachmatching element is passed to it, and the block's result is stored inthe output array.

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

                static VALUEenum_grep(VALUE obj, VALUE pat){    return enum_grep0(obj, pat, Qtrue);}

Inverted version of#grep.Returns an array of every element inenum for which notPattern === element.

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

                static VALUEenum_grep_v(VALUE obj, VALUE pat){    return enum_grep0(obj, pat, Qfalse);}

Groups the collection by result of the block. Returns a hash where thekeys are the evaluated result from the block and the values are arrays ofelements 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]}

                static VALUEenum_group_by(VALUE obj){    RETURN_SIZED_ENUMERATOR(obj, 0, 0, enum_size);    return enum_hashify(obj, 0, 0, group_by_i);}

Returnstrue if any member ofenum equalsobj. Equality is tested using==.

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

                static VALUEenum_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;}

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

Theinject andreduce methods are aliases. There is noperformance benefit to either.

If you specify a block, then for each element inenum the block ispassed an accumulator value (memo) and the element. If you specifya symbol instead, then each element in the collection will be passed to thenamed method ofmemo. In either case, the result becomes the newvalue formemo. At the end of the iteration, the final value ofmemo is the return value for the method.

If you do not explicitly specify aninitial value formemo, then the first element of collection is used as the initialvalue ofmemo.

# 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 wordlongest =%w{ cat sheep bear }.injectdo|memo,word|memo.length>word.length?memo:wordendlongest#=> "sheep"

                static VALUEenum_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;}

Returns anEnumerator::Lazy, whichredefines mostEnumerable methods to postponeenumeration and enumerate values only on an as-needed basis.

Example¶↑

The following program finds pythagorean triples:

defpythagorean_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 triplesppythagorean_triples.take(10).force# take is lazy, so force is neededppythagorean_triples.first(10)# first is eager# show pythagorean triples less than 100ppythagorean_triples.take_while {|*,z|z<100 }.force

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

Returns a new array with the results of runningblock once forevery element inenum.

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

                static VALUEenum_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;}

Returns the object inenum with the maximum value. The first formassumes all objects implement<=>; the second uses theblock to returna <=> b.

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

If then argument is given, maximumn elementsare 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]

                static VALUEenum_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;}

Returns the object inenum that gives the maximum value from thegiven block.

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

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

If then argument is given, maximumn elementsare returned as an array. Thesen elements are sorted by thevalue 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. Followingexample implements and use Enumerable#wsample.

moduleEnumerable# 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)defwsample(n)self.max_by(n) {|v|rand** (1.0/yield(v)) }endende = (-20..20).to_a*10000a =e.wsample(20000) {|x|Math.exp(-(x/5.0)**2)# normal distribution}# a is 20000 samples from e.pa.length#=> 20000h =a.group_by {|x|x }-10.upto(10) {|x|puts"*"* (h[x].length/30.0).to_iifh[x] }#=> *#   ***#   ******#   ***********#   ******************#   *****************************#   *****************************************#   ****************************************************#   ***************************************************************#   ********************************************************************#   ***********************************************************************#   ***********************************************************************#   **************************************************************#   ****************************************************#   ***************************************#   ***************************#   ******************#   ***********#   *******#   ***#   *

                static VALUEenum_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;}

Returnstrue if any member ofenum equalsobj. Equality is tested using==.

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

                static VALUEenum_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;}

Returns the object inenum with the minimum value. The first formassumes all objects implement<=>; the second uses theblock to returna <=> b.

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

If then argument is given, minimumn elementsare 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]

                static VALUEenum_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;}

Returns the object inenum that gives the minimum value from thegiven block.

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

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

If then argument is given, minimumn elementsare returned as an array. Thesen elements are sorted by thevalue from the given block.

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

                static VALUEenum_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;}

Returns a two element array which contains the minimum and the maximumvalue in the enumerable. The first form assumes all objects implement<=>; the second uses the block to returna <=>b.

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

                static VALUEenum_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);}

Returns a two element array containing the objects inenum thatcorrespond to the minimum and maximum values respectively from the givenblock.

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

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

                static VALUEenum_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);}

Passes each element of the collection to the given block. The methodreturnstrue if the block never returnstrue forall elements. If the block is not given,none? will returntrue only if none of the collection members is true.

If instead a pattern is supplied, the method returns whetherpattern=== 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

                static VALUEenum_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;}

Passes each element of the collection to the given block. The methodreturnstrue if the block returnstrue exactlyonce. If the block is not given,one? will returntrue only if exactly one of the collection members is true.

If instead a pattern is supplied, the method returns whetherpattern=== 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

                static VALUEenum_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;}

Returns two arrays, the first containing the elements ofenum forwhich 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]]

                static VALUEenum_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);}

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

Theinject andreduce methods are aliases. There is noperformance benefit to either.

If you specify a block, then for each element inenum the block ispassed an accumulator value (memo) and the element. If you specifya symbol instead, then each element in the collection will be passed to thenamed method ofmemo. In either case, the result becomes the newvalue formemo. At the end of the iteration, the final value ofmemo is the return value for the method.

If you do not explicitly specify aninitial value formemo, then the first element of collection is used as the initialvalue ofmemo.

# 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 wordlongest =%w{ cat sheep bear }.injectdo|memo,word|memo.length>word.length?memo:wordendlongest#=> "sheep"

                static VALUEenum_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;}

Returns an array for all elements ofenum for which the givenblock returnsfalse.

If no block is given, anEnumerator isreturned 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#find_all.

                static VALUEenum_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;}

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|pv }

produces:

321

                static VALUEenum_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;}

Returns an array containing all elements ofenum for which thegivenblock returns a true value.

Thefind_all andselect methods are aliases. There is noperformance benefit to either.

If no block is given, anEnumerator isreturned 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#reject,#grep.

                static VALUEenum_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;}

Creates an enumerator for each chunked elements. The ends of chunks aredefined bypattern and the block.

Ifpattern ===elt returnstrueor the block returnstrue for the element, the element is endof a chunk.

The=== andblock is called from the first element tothe last element ofenum.

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

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

Other methods of theEnumerator class andEnumerable module, such asmap,etc., are also usable.

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

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

                static VALUEenum_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;}

Creates an enumerator for each chunked elements. The beginnings of chunksare defined bypattern and the block.

Ifpattern ===elt returnstrueor the block returnstrue for the element, the element isbeginning of a chunk.

The=== andblock is called from the first element tothe last element ofenum. The result for the first element isignored.

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

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

Other methods of theEnumerator class andEnumerable module, such asto_a,map, etc., are also usable.

For example, iteration over ChangeLog entries can be implemented asfollows:

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

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

IO.popen([{"LC_ALL"=>"C"},"svn","proplist","-R"]) {|f|f.lines.slice_before(/\AProp/).each {|lines|plines }}#=> ["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, localvariables can be used. For example, three or more consecutive increasingnumbers can be squashed as follows (seechunk_while for abetter way):

a = [0,2,3,4,6,7,9]prev =a[0]pa.slice_before {|e|prev,prev2 =e,prevprev2+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 enumeratoris enumerated twice or more. The local variables should be initialized foreach enumeration.Enumerator.newcan be used to do it.

# Word wrapping.  This assumes all characters have same width.defwordwrap(words,maxwidth)Enumerator.new {|y|# cols is initialized in Enumerator.new.cols =0words.slice_before {|w|cols+=1ifcols!=0cols+=w.lengthifmaxwidth<colscols =w.lengthtrueelsefalseend    }.each {|ws|y.yieldws }  }endtext = (1..20).to_a.join(" ")enum =wordwrap(text.split(/\s+/),10)puts"-"*10enum.each {|ws|putsws.join(" ") }# first enumeration.puts"-"*10enum.each {|ws|putsws.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 mailcan be extracted by slice before Unix From line.

# parse mboxopen("mbox") {|f|f.slice_before {|line|line.start_with?"From "  }.each {|mail|unix_from =mail.shifti =mail.index("\n")header =mail[0...i]body =mail[(i+1)..-1]body.popifbody.last=="\n"fields =header.slice_before {|line|!" \t".include?(line[0]) }.to_apunix_fromppfieldsppbody  }}# split mails in mbox (slice before Unix From line after an empty line)open("mbox") {|f|emp =truef.slice_before {|line|prevemp =empemp =line=="\n"prevemp&&line.start_with?("From ")  }.each {|mail|mail.popifmail.last=="\n"ppmail  }}

                static VALUEenum_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;}

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

This method splits each chunk using adjacent elements,elt_beforeandelt_after, in the receiver enumerator. This method splitchunks betweenelt_before andelt_after where the blockreturnstrue.

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

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

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

Other methods of theEnumerator class andEnumerable module, such asto_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 }pb.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}" }pc#=> [[1, 2], [4], "9-12", [15, 16], "19-21"]d =c.join(",")pd#=> "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]pa.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]pa.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 isanother way to do it.)

a = [7,5,9,2,0,7,9,4,2,0]pa.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 asfollows: (See#chunk to ignoreempty lines.)

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

#chunk_while does thesame, except splitting when the block returnsfalse instead oftrue.

                static VALUEenum_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;}

Returns an array containing the items inenum 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 betweena andb and return an integer less than 0 whenbfollowsa,0 whena andb are equivalent, or an integer greater than 0 whena followsb.

The result is not guaranteed to be stable. When the comparison of twoelements returns0, the order of the elements isunpredictable.

%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#sort_by. Itimplements a Schwartzian transform which is useful when key computation orcomparison is expensive.

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

Sortsenum using a set of keys generated by mapping the values inenum through the given block.

The result is not guaranteed to be stable. When two keys are equal, theorder 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 ofsort_by generates an array oftuples containing the original collection element and the mapped value.This makessort_by fairlyexpensive 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        realSort        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-trivialoperation. The following code sorts some files on modification time usingthe basicsort 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 newFileobjects during every comparison. A slightly better technique is to use theKernel#test method to generate themodification times directly.

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

This still generates many unnecessaryTime objects.A more efficient technique is to cache the sort keys (modification times inthis case) before the sort. Perl users often call this approach aSchwartzian transform, after Randal Schwartz. We construct a temporaryarray, where each element is an array containing our sort key along withthe filename. We sort this array, and then extract the filename from theresult.

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

This is exactly whatsort_bydoes 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!

                static VALUEenum_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;}

Returns the sum of elements in anEnumerable.

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

Ifenum is empty, it returnsinit.

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

{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 anInteger rangewithout a block, the sum is not done by iteration, but instead usingGauss's summation formula.

#sum method may not respectmethod redefinition of “+” methods such as Integer#+, or “each” methodssuch asRange#each.

                static VALUEenum_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) {            memo.v = rb_rational_plus(memo.r, memo.v);        }        return memo.v;    }}

Returns first n elements fromenum.

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

                static VALUEenum_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;}

Passes elements to the block until the block returnsnil orfalse, then stops iterating and returns an array of all priorelements.

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]

                static VALUEenum_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;}

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

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

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

Returns an array containing the items inenum.

(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.entries10#=> [2, 3, 5, 7]

                static VALUEenum_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;}

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

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

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

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

                static VALUEenum_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);}

Returns a new array by removing duplicate values inself.

See alsoArray#uniq.

                static VALUEenum_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;}

Takes one element fromenum and merges corresponding elements fromeachargs. This generates a sequence ofn-elementarrays, wheren is one more than the count of arguments. Thelength of the resulting sequence will beenum#size. If thesize of any argument is less thanenum#size,nilvalues are supplied. If a block is given, it is invoked for each outputarray, 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 }#=> nilc#=> [11, 13, 15]

                static VALUEenum_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;}