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
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
.
%w[ant bear cat].all? { |word| word.length >= 3 } #=> true %w[ant bear cat].all? { |word| word.length >= 4 } #=> false [nil, true, 99].all? #=> false
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; }
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
.
%w[ant bear cat].any? { |word| word.length >= 3 } #=> true %w[ant bear cat].any? { |word| word.length >= 4 } #=> true [nil, true, 99].any? #=> true
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; }
Enumerates over the items, chunking them together based on the return value of the block.
Consecutive elements which return the same block value are chunked together.
For example, consecutive even numbers and odd numbers can be chunked as follows.
[3, 1, 4, 1, 5, 9, 2, 6, 5, 3, 5].chunk { |n| n.even? }.each { |even, ary| p [even, ary] } #=> [false, [3, 1]] # [true, [4]] # [false, [1, 5, 9]] # [true, [2, 6]] # [false, [5, 3, 5]]
This method is especially useful for sorted series of elements. The following example counts words for each initial letter.
open("/usr/share/dict/words", "r:iso-8859-1") { |f| f.chunk { |line| line.ord }.each { |ch, lines| p [ch.chr, lines.length] } } #=> ["\n", 1] # ["A", 1327] # ["B", 1372] # ["C", 1507] # ["D", 791] # ...
The following key values have special meaning:
-
nil
and:_separator
specifies that the elements should be dropped. -
:_alone
specifies that the element should be chunked by itself.
Any other symbols that begin with an underscore will raise an error:
items.chunk { |item| :_underscore } #=> RuntimeError: symbols beginning with an underscore are reserved
nil
and :_separator
can be used to ignore some
elements.
For example, the sequence of hyphens in svn log can be eliminated as follows:
sep = "-"*72 + "\n" IO.popen("svn log README") { |f| f.chunk { |line| line != sep || nil }.each { |_, lines| pp lines } } #=> ["r20018 | knu | 2008-10-29 13:20:42 +0900 (Wed, 29 Oct 2008) | 2 lines\n", # "\n", # "* README, README.ja: Update the portability section.\n", # "\n"] # ["r16725 | knu | 2008-05-31 23:34:23 +0900 (Sat, 31 May 2008) | 2 lines\n", # "\n", # "* README, README.ja: Add a note about default C flags.\n", # "\n"] # ...
Paragraphs separated by empty lines can be parsed as follows:
File.foreach("README").chunk { |line| /\A\s*\z/ !~ line || nil }.each { |_, lines| pp lines }
:_alone
can be used to force items into their own chunk. For
example, you can put lines that contain a URL by themselves, and chunk the
rest of the lines together, like this:
pattern = /http/ open(filename) { |f| f.chunk { |line| line =~ pattern ? :_alone : true }.each { |key, lines| pp lines } }
If the block needs to maintain state over multiple elements, an
initial_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 the
chunk
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; }
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; 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; }
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; }
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; 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); }
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 } # 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_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_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++) { rb_yield(RARRAY_AREF(ary, i)); } } return Qnil; }
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..10).detect { |i| i % 5 == 0 and i % 7 == 0 } #=> nil (1..100).find { |i| i % 5 == 0 and i % 7 == 0 } #=> 35
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; }
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; 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; }
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; 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; }
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); 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; }
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; }
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; 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; }
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) { 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; }
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; }
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(obj, id_each, argc, argv, collect_all, ary); OBJ_INFECT(ary, obj); return ary; }
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..10).detect { |i| i % 5 == 0 and i % 7 == 0 } #=> nil (1..100).find { |i| i % 5 == 0 and i % 7 == 0 } #=> 35
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; }
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 } #=> [3, 6, 9] [1,2,3,4,5].select { |num| num.even? } #=> [2, 4]
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; }
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 and i % 7 == 0 } #=> nil (1..100).find_index { |i| i % 5 == 0 and i % 7 == 0 } #=> 34 (1..100).find_index(50) #=> 49
static VALUE enum_find_index(int argc, VALUE *argv, VALUE obj) { NODE *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 = NEW_MEMO(Qnil, condition_value, 0); rb_block_call(obj, id_each, 0, 0, func, (VALUE)memo); return memo->u1.value; }
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
static VALUE enum_first(int argc, VALUE *argv, VALUE obj) { NODE *memo; rb_check_arity(argc, 0, 1); if (argc > 0) { return enum_take(obj, argv[0]); } else { memo = NEW_MEMO(Qnil, 0, 0); rb_block_call(obj, id_each, 0, 0, first_i, (VALUE)memo); return memo->u1.value; } }
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; }
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) { VALUE ary = rb_ary_new(); NODE *memo = NEW_MEMO(pat, ary, 0); rb_block_call(obj, id_each, 0, 0, rb_block_given_p() ? grep_iter_i : grep_i, (VALUE)memo); return ary; }
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) { VALUE hash; RETURN_SIZED_ENUMERATOR(obj, 0, 0, enum_size); hash = rb_hash_new(); rb_block_call(obj, id_each, 0, 0, group_by_i, hash); OBJ_INFECT(hash, obj); return hash; }
Returns true
if any member of enum equals
obj. Equality is tested using ==
.
IO.constants.include? :SEEK_SET #=> true IO.constants.include? :SEEK_NO_FURTHER #=> false
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; }
Combines all elements of enum by applying a binary operation, specified by a block or a symbol that names a method or operator.
If you specify a block, then for each element in enum 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) { NODE *memo; VALUE init, op; rb_block_call_func *iter = inject_i; ID id; switch (rb_scan_args(argc, argv, "02", &init, &op)) { case 0: break; case 1: if (rb_block_given_p()) { break; } id = rb_check_id(&init); op = id ? ID2SYM(id) : init; argc = 0; init = Qnil; 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; } memo = NEW_MEMO(init, argc, op); rb_block_call(obj, id_each, 0, 0, iter, (VALUE)memo); return memo->u1.value; }
Returns a lazy enumerator, whose methods map/collect, flat_map/collect_concat, select/find_all, reject, grep, zip, take, #take_while, drop, and #drop_while enumerate values only on an as-needed basis. However, if a block is given to zip, values are enumerated immediately.
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); /* Qfalse indicates that the Enumerator::Lazy has no method name */ rb_ivar_set(result, id_method, Qfalse); return result; }
Returns a new array with the results of 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; 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; }
Returns the object in enum with the maximum value. The first form
assumes all objects implement Comparable
; the second uses the
block to return a <=> b.
a = %w(albatross dog horse) a.max #=> "horse" a.max { |a, b| a.length <=> b.length } #=> "albatross"
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; }
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"
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; }
Returns true
if any member of enum equals
obj. Equality is tested using ==
.
IO.constants.include? :SEEK_SET #=> true IO.constants.include? :SEEK_NO_FURTHER #=> false
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; }
Returns the object in enum with the minimum value. The first form
assumes all objects implement Comparable
; the second uses the
block to return a <=> b.
a = %w(albatross dog horse) a.min #=> "albatross" a.min { |a, b| a.length <=> b.length } #=> "dog"
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; }
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"
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; }
Returns two elements array which contains the minimum and the maximum value
in the enumerable. The first form assumes all objects implement
Comparable
; the second uses the block to return a
<=> b.
a = %w(albatross dog horse) a.minmax #=> ["albatross", "horse"] a.minmax { |a, b| a.length <=> b.length } #=> ["dog", "albatross"]
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; }
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); }
Passes each element of the collection to the given block. The method
returns true
if the block never returns true
for
all elements. If the block is not given, none?
will return
true
only if none of the collection members is true.
%w{ant bear cat}.none? { |word| word.length == 5 } #=> true %w{ant bear cat}.none? { |word| word.length >= 4 } #=> false [].none? #=> true [nil].none? #=> true [nil, false].none? #=> true
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; }
Passes each element of the collection to the given block. The method
returns true
if the block returns true
exactly
once. If the block is not given, one?
will return
true
only if exactly one of the collection members is true.
%w{ant bear cat}.one? { |word| word.length == 4 } #=> true %w{ant bear cat}.one? { |word| word.length > 4 } #=> false %w{ant bear cat}.one? { |word| word.length < 4 } #=> false [ nil, true, 99 ].one? #=> false [ nil, true, false ].one? #=> true
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; }
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) { 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); }
Combines all elements of enum by applying a binary operation, specified by a block or a symbol that names a method or operator.
If you specify a block, then for each element in enum 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) { NODE *memo; VALUE init, op; rb_block_call_func *iter = inject_i; ID id; switch (rb_scan_args(argc, argv, "02", &init, &op)) { case 0: break; case 1: if (rb_block_given_p()) { break; } id = rb_check_id(&init); op = id ? ID2SYM(id) : init; argc = 0; init = Qnil; 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; } memo = NEW_MEMO(init, argc, op); rb_block_call(obj, id_each, 0, 0, iter, (VALUE)memo); return memo->u1.value; }
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 #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; }
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 i; RETURN_SIZED_ENUMERATOR(obj, argc, argv, enum_size); ary = enum_to_a(argc, argv, obj); for (i = RARRAY_LEN(ary); --i >= 0; ) { rb_yield(RARRAY_AREF(ary, i)); } return obj; }
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 } #=> [3, 6, 9] [1,2,3,4,5].select { |num| num.even? } #=> [2, 4]
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; }
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| ... } 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:
# 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:
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 are not appropriate to maintain state if the result
enumerator is used twice or more. In such a case, the last state of the 1st
each
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 each
each
method invocation of the enumerator. The duplicated
object is passed to 2nd argument of the block for slice_before
method.
# Word wrapping. This assumes all characters have same width. def wordwrap(words, maxwidth) # if cols is a local variable, 2nd "each" may start with non-zero cols. 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 #=> ---------- # 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| 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; }
Returns an array containing the items in enum sorted, either
according to their own <=>
method, or by using the
results of the supplied block. The block should return -1, 0, or +1
depending on the comparison between a and b. As of Ruby
1.8, the method Enumerable#sort_by
implements a built-in
Schwartzian Transform, useful when key computation or comparison is
expensive.
%w(rhea kea flea).sort #=> ["flea", "kea", "rhea"] (1..10).sort { |a, b| b <=> a } #=> [10, 9, 8, 7, 6, 5, 4, 3, 2, 1]
static VALUE enum_sort(VALUE obj) { return rb_ary_sort(enum_to_a(0, 0, obj)); }
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} #=> ["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"]
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_CLEAR_CLASS(ary); 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) { 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); OBJ_INFECT(ary, memo); return ary; }
Returns first n elements from enum.
a = [1, 2, 3, 4, 5, 0] a.take(3) #=> [1, 2, 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; }
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; }
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(obj, id_each, argc, argv, collect_all, ary); OBJ_INFECT(ary, obj); return ary; }
Returns the result of interpreting enum as a list of [key,
value]
pairs.
%[hello world].each_with_index.to_h # => {:hello => 0, :world => 1}
static VALUE enum_to_h(int argc, VALUE *argv, VALUE obj) { VALUE hash = rb_hash_new(); rb_block_call(obj, id_each, argc, argv, enum_to_h_i, hash); OBJ_INFECT(hash, obj); return hash; }
Makes a set from the enumerable object with given arguments. Needs to +require “set”+ to use this method.
# File lib/set.rb, line 670 def to_set(klass = Set, *args, &block) klass.new(self, *args, &block) end
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 ] [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]]
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; }