module Enumerable - RDoc Documentation

# module Enumerable

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.

### Public Instance Methods

all? [{ |obj| block } ] → true or false click to toggle source
all?(pattern) → true or false

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

    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| block }] → true or false click to toggle source
any?(pattern) → true or false

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

    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) → enumerator click to toggle source

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]

    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| ... } → an_enumerator click to toggle source

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

    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| bool } → an_enumerator click to toggle source

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

This method splits 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`.

    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| block } → array click to toggle source
collect → an_enumerator

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

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

Also aliased as: map
collect_concat { |obj| block } → array
collect_concat → an_enumerator

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]

Alias for: flat_map
count → int click to toggle source
count(item) → int
count { |obj| block } → int

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

    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| block } → nil click to toggle source
cycle(n=nil) → an_enumerator

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.

    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| block } → obj or nil
detect(ifnone = nil) → an_enumerator

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

Alias for: find
drop(n) → array click to toggle source

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]

    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| block } → array click to toggle source
drop_while → an_enumerator

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]

    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 click to toggle source
each_cons(n) → an_enumerator

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]

    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| block } → enum click to toggle source
each_entry → an_enumerator

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

    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 click to toggle source
each_slice(n) → an_enumerator

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]

    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| block } → enum click to toggle source
each_with_index(*args) → an_enumerator

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}

    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| ... } → obj click to toggle source
each_with_object(obj) → an_enumerator

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

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]

Alias for: to_a
filter { |obj| block } → array
filter → an_enumerator

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

Alias for: find_all
filter_map { |obj| block } → array click to toggle source
filter_map → an_enumerator

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]

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

find(ifnone = nil) { |obj| block } → obj or nil click to toggle source
find(ifnone = nil) → an_enumerator

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

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

Also aliased as: detect
find_all { |obj| block } → array click to toggle source
find_all → an_enumerator

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

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

Also aliased as: select, filter
find_index(value) → int or nil click to toggle source
find_index { |obj| block } → int or nil
find_index → an_enumerator

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

    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 → obj or nil click to toggle source
first(n) → an_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)              #=> []

    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| block } → array click to toggle source
flat_map → an_enumerator

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]

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

Also aliased as: collect_concat
grep(pattern) → array click to toggle source
grep(pattern) { |obj| block } → 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]

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

grep_v(pattern) → array click to toggle source
grep_v(pattern) { |obj| block } → 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]

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

group_by { |obj| block } → a_hash click to toggle source
group_by → an_enumerator

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

    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) → true or false

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

Alias for: member?
inject(initial, sym) → obj click to toggle source
inject(sym) → obj
inject(initial) { |memo, obj| block } → obj
inject { |memo, obj| block } → obj

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

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"

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

Also aliased as: reduce
lazy → lazy_enumerator click to toggle source

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

    static VALUE
    enumerable_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;
    }

map { |obj| block } → array
map → an_enumerator

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

Alias for: collect
max → obj click to toggle source
max { |a, b| block } → obj
max(n) → array
max(n) { |a, b| block } → array

Returns the object in enum with the maximum value. The first form assumes all objects implement `<=>`; 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]

    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| block } → obj click to toggle source
max_by → an_enumerator
max_by(n) {|obj| block } → obj
max_by(n) → an_enumerator

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] }
    #=> *
    #   ***
    #   ******
    #   ***********
    #   ******************
    #   *****************************
    #   *****************************************
    #   ****************************************************
    #   ***************************************************************
    #   ********************************************************************
    #   ***********************************************************************
    #   ***********************************************************************
    #   **************************************************************
    #   ****************************************************
    #   ***************************************
    #   ***************************
    #   ******************
    #   ***********
    #   *******
    #   ***
    #   *

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

member?(obj) → true or false click to toggle source

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

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

Also aliased as: include?
min → obj click to toggle source
min { |a, b| block } → obj
min(n) → array
min(n) { |a, b| block } → array

Returns the object in enum with the minimum value. The first form assumes all objects implement `<=>`; 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]

    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| block } → obj click to toggle source
min_by → an_enumerator
min_by(n) {|obj| block } → array
min_by(n) → an_enumerator

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

    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 → [min, max] click to toggle source
minmax { |a, b| block } → [min, max]

Returns a two element array which contains the minimum and the maximum value in the enumerable. The first form assumes all objects implement `<=>`; 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"]

    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| block } → [min, max] click to toggle source
minmax_by → an_enumerator

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

    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| block }] → true or false click to toggle source
none?(pattern) → true or false

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

    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| block }] → true or false click to toggle source
one?(pattern) → true or false

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

    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| block } → [ true_array, false_array ] click to toggle source
partition → an_enumerator

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

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

reduce(initial, sym) → obj
reduce(sym) → obj
reduce(initial) { |memo, obj| block } → obj
reduce { |memo, obj| block } → obj

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

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"

Alias for: inject
reject { |obj| block } → array click to toggle source
reject → an_enumerator

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

    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| block } → enum click to toggle source
reverse_each(*args) → an_enumerator

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

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

select { |obj| block } → array
select → an_enumerator

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

Alias for: find_all
slice_after(pattern) → an_enumerator click to toggle source
slice_after { |elt| bool } → an_enumerator

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

    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) → an_enumerator click to toggle source
slice_before { |elt| bool } → an_enumerator

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

    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| bool } → an_enumerator click to toggle source

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

This method splits 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`.

    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 click to toggle source
sort { |a, b| block } → 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.

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

sort_by { |obj| block } → array click to toggle source
sort_by → an_enumerator

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!

    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) → number click to toggle source
sum(init=0) {|e| expr } → number

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

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

take(n) → array click to toggle source

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]

    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| block } → array click to toggle source
take_while → an_enumerator

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]

    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 → a_hash click to toggle source

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}

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

to_a(*args) → array click to toggle source

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]

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

        rb_block_call_kw(obj, id_each, argc, argv, collect_all, ary, RB_PASS_CALLED_KEYWORDS);

        return ary;
    }

Also aliased as: entries
to_h(*args) → hash click to toggle source
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}

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

to_set(klass = Set, *args, &block) click to toggle source

Makes a set from the enumerable object with given arguments. Needs to `require "set"` to use this method.

    # File lib/set.rb, line 687
    def to_set(klass = Set, *args, &block)
      klass.new(self, *args, &block)
    end

uniq → new_ary click to toggle source
uniq { |item| ... } → new_ary

Returns a new array by removing duplicate values in `self`.

See also `Array#uniq`.

    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, ...) → an_array_of_array click to toggle source
zip(arg, ...) { |arr| block } → 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]

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