Module: Enumerable (Ruby 2.0.0) (original) (raw)

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.

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

Passes each element of the collection to the given block. The method returns true if the block never returns false ornil. If the block is not given, Ruby adds an implicit block of{ |obj| obj } which will cause all? to return truewhen none of the collection members are false ornil.

%w[ant bear cat].all? { |word| word.length >= 3 } %w[ant bear cat].all? { |word| word.length >= 4 } [nil, true, 99].all?

           static VALUE

enum_all(VALUE obj) { NODE *memo = NEW_MEMO(Qtrue, 0, 0); rb_block_call(obj, id_each, 0, 0, ENUMFUNC(all), (VALUE)memo); return memo->u1.value; }

any? [{ |obj| block }] → true or false click to toggle source

Passes each element of the collection to the given block. The method returns true if the block ever returns a value other thanfalse or nil. If the block is not given, Ruby adds an implicit block of { |obj| obj } that will cause any? to return trueif at least one of the collection members is not false ornil.

%w[ant bear cat].any? { |word| word.length >= 3 } %w[ant bear cat].any? { |word| word.length >= 4 } [nil, true, 99].any?

           static VALUE

enum_any(VALUE obj) { NODE *memo = NEW_MEMO(Qfalse, 0, 0); rb_block_call(obj, id_each, 0, 0, ENUMFUNC(any), (VALUE)memo); return memo->u1.value; }

chunk { |elt| ... } → an_enumerator click to toggle source

chunk(initial_state) { |elt, state| ... } → an_enumerator

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

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

open("/usr/share/dict/words", "r:iso-8859-1") { |f| f.chunk { |line| line.ord }.each { |ch, lines| p [ch.chr, lines.length] } }

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 }

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

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 the block needs to maintain state over multiple elements, aninitial_state argument can be used. If a non-nil value is given, a reference to it is passed as the 2nd argument of the block for thechunk method, so state-changes to it persist across block calls.

           static VALUE

enum_chunk(int argc, VALUE *argv, VALUE enumerable) { VALUE initial_state; VALUE enumerator;

if (!rb_block_given_p())
    rb_raise(rb_eArgError, "no block given");
rb_scan_args(argc, argv, "01", &initial_state);

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_ivar_set(enumerator, rb_intern("chunk_initial_state"), initial_state);
rb_block_call(enumerator, idInitialize, 0, 0, chunk_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).collect { |i| i*i }
(1..4).collect { "cat" }

           static VALUE

enum_collect(VALUE obj) { VALUE ary;

RETURN_SIZED_ENUMERATOR(obj, 0, 0, enum_size);

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

return ary;

}

collect_concat { |obj| block } → array click to toggle source

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, 2], [3, 4]].flat_map { |e| e + [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;

}

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
ary.count(2)
ary.count{ |x| x%2==0 }

           static VALUE

enum_count(int argc, VALUE *argv, VALUE obj) { VALUE item = Qnil; NODE *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 = NEW_MEMO(item, 0, 0);
rb_block_call(obj, id_each, 0, 0, func, (VALUE)memo);
return INT2NUM(memo->u3.cnt);

}

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.

#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 }
a.cycle(2) { |x| puts x }

           static VALUE

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

rb_scan_args(argc, argv, "01", &nv);

RETURN_SIZED_ENUMERATOR(obj, argc, argv, enum_cycle_size);
if (NIL_P(nv)) {
    n = -1;
}
else {
    n = NUM2LONG(nv);
    if (n <= 0) return Qnil;
}
ary = rb_ary_new();
RBASIC(ary)->klass = 0;
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++) {
        rb_yield(RARRAY_PTR(ary)[i]);
    }
}
return Qnil;

}

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

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

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

(1..10).detect { |i| i % 5 == 0 and i % 7 == 0 }
(1..100).find { |i| i % 5 == 0 and i % 7 == 0 }

           static VALUE

enum_find(int argc, VALUE *argv, VALUE obj) { NODE *memo; VALUE if_none;

rb_scan_args(argc, argv, "01", &if_none);
RETURN_ENUMERATOR(obj, argc, argv);
memo = NEW_MEMO(Qundef, 0, 0);
rb_block_call(obj, id_each, 0, 0, find_i, (VALUE)memo);
if (memo->u3.cnt) {
    return memo->u1.value;
}
if (!NIL_P(if_none)) {
    return rb_funcall(if_none, id_call, 0, 0);
}
return Qnil;

}

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)

           static VALUE

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

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

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

}

drop_while { |arr| 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 }

           static VALUE

enum_drop_while(VALUE obj) { VALUE result; NODE *memo;

RETURN_ENUMERATOR(obj, 0, 0);
result = rb_ary_new();
memo = NEW_MEMO(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 elements. If no block is given, returns an enumerator.

e.g.:

(1..10).each_cons(3) { |a| p a }

[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); NODE *memo;

if (size <= 0) rb_raise(rb_eArgError, "invalid size");
RETURN_SIZED_ENUMERATOR(obj, 1, &n, enum_each_cons_size);
memo = NEW_MEMO(rb_ary_new2(size), 0, 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 elements. If no block is given, returns an enumerator.

(1..10).each_slice(3) { |a| p a }

[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; NODE *memo;

if (size <= 0) rb_raise(rb_eArgError, "invalid slice size");
RETURN_SIZED_ENUMERATOR(obj, 1, &n, enum_each_slice_size);
ary = rb_ary_new2(size);
memo = NEW_MEMO(ary, 0, size);
rb_block_call(obj, id_each, 0, 0, each_slice_i, (VALUE)memo);
ary = memo->u1.value;
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

           static VALUE

enum_each_with_index(int argc, VALUE *argv, VALUE obj) { NODE *memo;

RETURN_SIZED_ENUMERATOR(obj, argc, argv, enum_size);

memo = NEW_MEMO(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 }

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

Returns an array containing the items in enum.

(1..7).to_a
{ 'a'=>1, 'b'=>2, 'c'=>3 }.to_a

           static VALUE

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

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

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

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

(1..10).detect { |i| i % 5 == 0 and i % 7 == 0 }
(1..100).find { |i| i % 5 == 0 and i % 7 == 0 }

           static VALUE

enum_find(int argc, VALUE *argv, VALUE obj) { NODE *memo; VALUE if_none;

rb_scan_args(argc, argv, "01", &if_none);
RETURN_ENUMERATOR(obj, argc, argv);
memo = NEW_MEMO(Qundef, 0, 0);
rb_block_call(obj, id_each, 0, 0, find_i, (VALUE)memo);
if (memo->u3.cnt) {
    return memo->u1.value;
}
if (!NIL_P(if_none)) {
    return rb_funcall(if_none, id_call, 0, 0);
}
return Qnil;

}

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.

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

(1..10).find_all { |i| i % 3 == 0 }

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

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| x2 + y2 == z**2 }.map {|y| [x, y, z] } } } end

p pythagorean_triples.take(10).force p pythagorean_triples.first(10)

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, enum_size); /* Qfalse indicates that the Enumerator::Lazy has no method name */ rb_ivar_set(result, id_method, Qfalse); return result; }

map { |obj| block } → array click to toggle source

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).collect { |i| i*i }
(1..4).collect { "cat" }

           static VALUE

enum_collect(VALUE obj) { VALUE ary;

RETURN_SIZED_ENUMERATOR(obj, 0, 0, enum_size);

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

return ary;

}

max → obj click to toggle source

max { |a, b| block } → obj

Returns the object in enum with the maximum value. The first form assumes all objects implement Comparable; the second uses the block to return a <=> b.

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

           static VALUE

enum_max(VALUE obj) { NODE *memo = NEW_MEMO(Qundef, 0, 0); VALUE result;

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 = memo->u1.value;
if (result == Qundef) return Qnil;
return result;

}

max_by { |obj| block } → obj click to toggle source

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

           static VALUE

enum_max_by(VALUE obj) { NODE *memo;

RETURN_SIZED_ENUMERATOR(obj, 0, 0, enum_size);

memo = NEW_MEMO(Qundef, Qnil, 0);
rb_block_call(obj, id_each, 0, 0, max_by_i, (VALUE)memo);
return memo->u2.value;

}

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

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

IO.constants.include? :SEEK_SET
IO.constants.include? :SEEK_NO_FURTHER

           static VALUE

enum_member(VALUE obj, VALUE val) { NODE *memo = NEW_MEMO(val, Qfalse, 0);

rb_block_call(obj, id_each, 0, 0, member_i, (VALUE)memo);
return memo->u2.value;

}

min → obj click to toggle source

min { |a, b| block } → obj

Returns the object in enum with the minimum value. The first form assumes all objects implement Comparable; the second uses the block to return a <=> b.

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

           static VALUE

enum_min(VALUE obj) { NODE *memo = NEW_MEMO(Qundef, 0, 0); VALUE result;

if (rb_block_given_p()) {
    rb_block_call(obj, id_each, 0, 0, min_ii, (VALUE)memo);
}
else {
    rb_block_call(obj, id_each, 0, 0, min_i, (VALUE)memo);
}
result = memo->u1.value;
if (result == Qundef) return Qnil;
return result;

}

min_by { |obj| block } → obj click to toggle source

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

           static VALUE

enum_min_by(VALUE obj) { NODE *memo;

RETURN_SIZED_ENUMERATOR(obj, 0, 0, enum_size);

memo = NEW_MEMO(Qundef, Qnil, 0);
rb_block_call(obj, id_each, 0, 0, min_by_i, (VALUE)memo);
return memo->u2.value;

}

minmax → [min, max] click to toggle source

minmax { |a, b| block } → [min, max]

Returns two elements array which contains the minimum and the maximum value in the enumerable. The first form assumes all objects implementComparable; the second uses the block to return a <=> b.

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

           static VALUE

enum_minmax(VALUE obj) { NODE *memo = NEW_MEMO(Qundef, Qundef, Qundef); struct minmax_t *m = (struct minmax_t *)&memo->u1.value; VALUE ary = rb_ary_new3(2, Qnil, Qnil);

m->min = Qundef;
m->last = Qundef;
if (rb_block_given_p()) {
    rb_block_call(obj, id_each, 0, 0, minmax_ii, (VALUE)memo);
    if (m->last != Qundef)
        minmax_ii_update(m->last, m->last, m);
}
else {
    rb_block_call(obj, id_each, 0, 0, minmax_i, (VALUE)memo);
    if (m->last != Qundef)
        minmax_i_update(m->last, m->last, m);
}
if (m->min != Qundef) {
    rb_ary_store(ary, 0, m->min);
    rb_ary_store(ary, 1, m->max);
}
return ary;

}

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 }

           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

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 returntrue only if none of the collection members is true.

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

           static VALUE

enum_none(VALUE obj) { NODE *memo = NEW_MEMO(Qtrue, 0, 0); rb_block_call(obj, id_each, 0, 0, ENUMFUNC(none), (VALUE)memo); return memo->u1.value; }

one? [{ |obj| block }] → true or false click to toggle source

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 returntrue only if exactly one of the collection members is true.

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

           static VALUE

enum_one(VALUE obj) { NODE *memo = NEW_MEMO(Qundef, 0, 0); VALUE result;

rb_block_call(obj, id_each, 0, 0, ENUMFUNC(one), (VALUE)memo);
result = memo->u1.value;
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? }

           static VALUE

enum_partition(VALUE obj) { NODE *memo;

RETURN_SIZED_ENUMERATOR(obj, 0, 0, enum_size);

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

return rb_assoc_new(memo->u1.value, memo->u2.value);

}

reduce(initial, sym) → obj click to toggle source

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.

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.

(5..10).reduce(:+)

(5..10).inject { |sum, n| sum + n }

(5..10).reduce(1, :*)

(5..10).inject(1) { |product, n| product * n }

longest = %w{ cat sheep bear }.inject do |memo, word| memo.length > word.length ? memo : word end longest

           static VALUE

enum_inject(int argc, VALUE *argv, VALUE obj) { NODE *memo; VALUE init, op; VALUE (iter)(VALUE, VALUE, int, VALUE) = inject_i;

switch (rb_scan_args(argc, argv, "02", &init, &op)) {
  case 0:
    break;
  case 1:
    if (rb_block_given_p()) {
        break;
    }
    op = (VALUE)rb_to_id(init);
    argc = 0;
    init = Qnil;
    iter = inject_op_i;
    break;
  case 2:
    if (rb_block_given_p()) {
        rb_warning("given block not used");
    }
    op = (VALUE)rb_to_id(op);
    iter = inject_op_i;
    break;
}
memo = NEW_MEMO(init, argc, op);
rb_block_call(obj, id_each, 0, 0, iter, (VALUE)memo);
return memo->u1.value;

}

reject { |obj| block } → array click to toggle source

reject → an_enumerator

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

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

(1..10).reject { |i| i % 3 == 0 }

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

See also #reject.

           static VALUE

enum_find_all(VALUE obj) { VALUE ary;

RETURN_SIZED_ENUMERATOR(obj, 0, 0, enum_size);

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

return ary;

}

slice_before(pattern) → an_enumerator click to toggle source

slice_before { |elt| bool } → an_enumerator

slice_before(initial_state) { |elt, state| 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 trueor 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. Soeach method can be called as follows:

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

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

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

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

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

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:

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(",")

However local variables are not appropriate to maintain state if the result enumerator is used twice or more. In such a case, the last state of the 1steach is used in the 2nd each. The_initial_state_ argument can be used to avoid this problem. If non-nil value is given as initial_state, it is duplicated for eacheach method invocation of the enumerator. The duplicated object is passed to 2nd argument of the block for slice_beforemethod.

def wordwrap(words, maxwidth)

words.slice_before(cols: 0) { |w, h| h[:cols] += 1 if h[:cols] != 0 h[:cols] += w.length if maxwidth < h[:cols] h[:cols] = w.length true else false end } end text = (1..20).to_a.join(" ") enum = wordwrap(text.split(/\s+/), 10) puts "-"*10 enum.each { |ws| puts ws.join(" ") } puts "-"*10

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

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

open("mbox") { |f| f.slice_before(emp: true) { |line, h| prevemp = h[:emp] h[: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()) {
    VALUE initial_state;
    rb_scan_args(argc, argv, "01", &initial_state);
    enumerator = rb_obj_alloc(rb_cEnumerator);
    rb_ivar_set(enumerator, rb_intern("slicebefore_sep_pred"), rb_block_proc());
    rb_ivar_set(enumerator, rb_intern("slicebefore_initial_state"), initial_state);
}
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;

}

sort → array click to toggle source

sort { |a, b| block } → array

Returns an array containing the items in enum sorted, either according to their own <=> method, or by using the results of the supplied block. The block should return -1, 0, or +1 depending on the comparison between a and b. As of Ruby 1.8, the method Enumerable#sort_by implements a built-in Schwartzian Transform, useful when key computation or comparison is expensive.

%w(rhea kea flea).sort
(1..10).sort { |a, b| b <=> a }

           static VALUE

enum_sort(VALUE obj) { return rb_ary_sort(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.

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

%w{apple pear fig}.sort_by { |word| word.length}

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

This sort is inefficient: it generates two new File objects during every comparison. A slightly better technique is to use theKernel#test method to generate the modification times directly.

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

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

This is exactly what sort_by does internally.

sorted = Dir["*"].sort_by { |f| test(?M, f) } sorted

           static VALUE

enum_sort_by(VALUE obj) { VALUE ary, buf; NODE *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(ary)->klass = 0;
buf = rb_ary_tmp_new(SORT_BY_BUFSIZE*2);
rb_ary_store(buf, SORT_BY_BUFSIZE*2-1, Qnil);
memo = NEW_MEMO(0, 0, 0);
OBJ_INFECT(memo, obj);
data = (struct sort_by_data *)&memo->u1;
data->ary = ary;
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) {
    ruby_qsort(RARRAY_PTR(ary), 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_PTR(ary)[i/2] = RARRAY_PTR(ary)[i];
}
rb_ary_resize(ary, RARRAY_LEN(ary)/2);
RBASIC(ary)->klass = rb_cArray;
OBJ_INFECT(ary, memo);

return ary;

}

take(n) → array click to toggle source

Returns first n elements from enum.

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

           static VALUE

enum_take(VALUE obj, VALUE n) { NODE *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 = NEW_MEMO(result, 0, len);
rb_block_call(obj, id_each, 0, 0, take_i, (VALUE)memo);
return result;

}

take_while { |arr| block } → array click to toggle source

take_while → an_enumerator

Passes elements to the block until the block returns nil orfalse, 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 }

           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;

}

to_a → array click to toggle source

Returns an array containing the items in enum.

(1..7).to_a
{ 'a'=>1, 'b'=>2, 'c'=>3 }.to_a

           static VALUE

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

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

return ary;

}

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, nilvalues are supplied. If a block is given, it is invoked for each output array, otherwise an array of arrays is returned.

a = [ 4, 5, 6 ] b = [ 7, 8, 9 ]

[1, 2, 3].zip(a, b)
[1, 2].zip(a, b)
a.zip([1, 2], [8])

           static VALUE

enum_zip(int argc, VALUE *argv, VALUE obj) { int i; ID conv; NODE *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) {
    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 %s (must respond to :each)",
                rb_obj_classname(argv[i]));
        }
        argv[i] = rb_funcall(argv[i], conv, 1, ID2SYM(id_each));
    }
}
if (!rb_block_given_p()) {
    result = rb_ary_new();
}
/* use NODE_DOT2 as memo(v, v, -) */
memo = rb_node_newnode(NODE_DOT2, result, args, 0);
rb_block_call(obj, id_each, 0, 0, allary ? zip_ary : zip_i, (VALUE)memo);

return result;

}