Enumerable
module Enumerable(T)
Overview
The Enumerable
mixin provides collection classes with several traversal, searching, filtering and querying methods-
Including types must provide an #each
method, which yields successive members of the collection.
For example:
class Three include Enumerable(Int32) def each yield 1 yield 2 yield 3 end end three = Three.new three.to_a # => [1, 2, 3] three.select &.odd? # => [1, 3] three.all? { |x| x < 10 } # => true
Note that most search and filter methods traverse an Enumerable eagerly, producing an Array
as the result- For a lazy alternative refer to the Iterator
and Iterable
modules.
Direct including types
- Char::Reader
- Dir
- Hash(K, V)
- HTTP::Cookies
- HTTP::Headers
- HTTP::Params
- Indexable(T)
- Iterator(T)
- JSON::Any
- Range(B, E)
- Set(T)
- XML::Attributes
- XML::NodeSet
- YAML::Any
Defined in:
enumerable.crset.cr
Instance Method Summary
- #all?(&block)
Returns
true
if the passed block returns a value other thanfalse
ornil
for all elements of the collection. - #all?
Returns
true
if none of the elements of the collection isfalse
ornil
. - #any?(&block)
Returns
true
if the passed block returns a value other thanfalse
ornil
for at least one element of the collection. - #any?
Returns
true
if at least one of the collection members is notfalse
ornil
. - #chunks(&block : T -> U) forall U
Enumerates over the items, chunking them together based on the return value of the block.
- #compact_map(&block)
Returns an
Array
with the results of running the block against each element of the collection, removingnil
values- - #count(&block)
Returns the number of elements in the collection for which the passed block returns
true
. - #count(item)
Returns the number of times that the passed item is present in the collection.
- #cycle(n, &block)
Calls the given block for each element in this enumerable n times.
- #cycle(&block)
Calls the given block for each element in this enumerable forever.
- #each(&block : T -> _)
Must yield this collection's elements to the block.
- #each_cons(count : Int, reuse = false, &block)
Iterates over the collection yielding chunks of size count, but advancing one by one.
- #each_slice(count : Int, reuse = false, &block)
Iterates over the collection in slices of size count, and runs the block for each of those.
- #each_with_index(offset = 0, &block)
Iterates over the collection, yielding both the elements and their index.
- #each_with_object(obj, &block)
Iterates over the collection, passing each element and the initial object obj.
- #find(if_none = nil, &block)
Returns the first element in the collection for which the passed block is
true
. - #first(count : Int)
Returns an
Array
with the first count elements in the collection- - #first
Returns the first element in the collection.
- #first?
Returns the first element in the collection.
- #flat_map(&block : T -> Array(U) | Iterator(U) | U) forall U
Returns a new array with the concatenated results of running the block (which is expected to return arrays) once for every element in the collection.
- #grep(pattern)
Returns an
Array
with all the elements in the collection that match theRegExp
pattern- - #group_by(&block : T -> U) forall U
- #in_groups_of(size : Int, filled_up_with : U = nil) forall U
Returns an
Array
with chunks in the given size, eventually filled up with given value ornil
- - #in_groups_of(size : Int, filled_up_with : U = nil, reuse = false, &block) forall U
Yields a block with the chunks in the given size.
- #includes?(obj)
Returns
true
if the collection contains obj,false
otherwise. - #index(&block)
Returns the index of the first element for which the passed block returns
true
. - #index(obj)
Returns the index of the object obj in the collection.
- #index_by(&block : T -> U) forall U
Converts an
Enumerable
to aHash
by using the value returned by the block as the hash key. - #join(separator, io)
Prints to io all the elements in the collection, separated by separator.
- #join(separator = "")
Returns a
String
created by concatenating the elements in the collection, separated by separator (defaults to none). - #join(separator, io, &block)
Prints to io the concatenation of the elements, with the possibility of controlling how the printing is done via a block.
- #join(separator = "", &block)
Returns a
String
created by concatenating the results of passing the elements in the collection to the passed block, separated by separator (defaults to none). - #map(&block : T -> U) forall U
Returns an
Array
with the results of running the block against each element of the collection- - #map_with_index(&block : T, Int32 -> U) forall U
Like
#map
, but the block gets passed both the element and its index. - #max
Returns the element with the maximum value in the collection.
- #max?
Like
#max
but returnsnil
if the collection is empty. - #max_by(&block : T -> U) forall U
Returns the element for which the passed block returns with the maximum value.
- #max_by?(&block : T -> U) forall U
Like
#max_by
but returnsnil
if the collection is empty. - #max_of(&block : T -> U) forall U
Like
#max_by
but instead of the element, returns the value returned by the block. - #max_of?(&block : T -> U) forall U
Like
#max_of
but returnsnil
if the collection is empty. - #min
Returns the element with the minimum value in the collection.
- #min?
Like
#min
but returnsnil
if the collection is empty. - #min_by(&block : T -> U) forall U
Returns the element for which the passed block returns with the minimum value.
- #min_by?(&block : T -> U) forall U
Like
#min_by
but returnsnil
if the collection is empty. - #min_of(&block : T -> U) forall U
Like
#min_by
but instead of the element, returns the value returned by the block. - #min_of?(&block : T -> U) forall U
Like
#min_of
but returnsnil
if the collection is empty. - #minmax
Returns a
Tuple
with both the minimum and maximum value. - #minmax?
Like
#minmax
but returns{nil, nil}
if the collection is empty. - #minmax_by(&block : T -> U) forall U
Returns a
Tuple
with both the minimum and maximum values according to the passed block. - #minmax_by?(&block : T -> U) forall U
Like
#minmax_by
but returns{nil, nil}
if the collection is empty. - #minmax_of(&block : T -> U) forall U
Returns a
Tuple
with both the minimum and maximum value the block returns when passed the elements in the collection. - #minmax_of?(&block : T -> U) forall U
Like
#minmax_of
but returns{nil, nil}
if the collection is empty. - #none?(&block)
Returns
true
if the passed block returnstrue
for none of the elements of the collection. - #none?
Returns
true
if all of the elements of the collection arefalse
ornil
. - #one?(&block)
Returns
true
if the passed block returnstrue
for exactly one of the elements of the collection. - #partition(&block)
Returns a
Tuple
with two arrays. - #product(&block)
Multiplies all results of the passed block for each element in the collection.
- #product(initial : Number, &block)
Multiplies initial and all results of the passed block for each element in the collection.
- #product
Multiplies all the elements in the collection together.
- #product(initial : Number)
Multiplies initial and all the elements in the collection together.
- #reduce(&block)
Combines all elements in the collection by applying a binary operation, specified by a block, so as to reduce them to a single value.
- #reduce(memo, &block)
Just like the other variant, but you can set the initial value of the accumulator.
- #reject(&block : T -> )
Returns an
Array
with all the elements in the collection for which the passed block returnsfalse
- - #select(&block : T -> )
Returns an
Array
with all the elements in the collection for which the passed block returnstrue
- - #size
Returns the number of elements in the collection.
- #skip(count : Int)
Returns an
Array
with the first count elements removed from the original collection- - #skip_while(&block)
Skips elements up to, but not including, the first element for which the block returns
nil
orfalse
and returns anArray
containing the remaining elements- - #sum(initial)
Adds initial and all the elements in the collection together.
- #sum
Adds all the elements in the collection together.
- #sum(initial, &block)
Adds initial and all results of the passed block for each element in the collection.
- #sum(&block)
Adds all results of the passed block for each element in the collection.
- #take_while(&block)
Passes elements to the block until the block returns
nil
orfalse
, then stops iterating and returns anArray
of all prior elements- - #to_a
Returns an
Array
with all the elements in the collection- - #to_h
- #to_set
Returns a new
Set
with each unique element in the enumerable.
Instance Method Detail
def all?(&block)Source
Returns true
if the passed block returns a value other than false
or nil
for all elements of the collection.
["ant", "bear", "cat"].all? { |word| word.size >= 3 } # => true ["ant", "bear", "cat"].all? { |word| word.size >= 4 } # => false
def all?Source
Returns true
if none of the elements of the collection is false
or nil
.
[nil, true, 99].all? # => false [15].all? # => true
def any?(&block)Source
Returns true
if the passed block returns a value other than false
or nil
for at least one element of the collection.
["ant", "bear", "cat"].any? { |word| word.size >= 4 } # => true ["ant", "bear", "cat"].any? { |word| word.size > 4 } # => false
def any?Source
Returns true
if at least one of the collection members is not false
or nil
.
[nil, true, 99].any? # => true [nil, false].any? # => false
def chunks(&block : T -> U) forall USource
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.
ary = [3, 1, 4, 1, 5, 9, 2, 6, 5, 3, 5].chunks { |n| n.even? } ary # => [{false, [3, 1]}, {true, [4]}, {false, [1, 5, 9]}, {true, [2, 6]}, {false, [5, 3, 5]}]
The following key values have special meaning:
-
Enumerable::Chunk::Drop
specifies that the elements should be dropped -
Enumerable::Chunk::Alone
specifies that the element should be chunked by itself
See also: Iterator#chunk
.
def compact_map(&block)Source
Returns an Array
with the results of running the block against each element of the collection, removing nil
values-
["Alice", "Bob"].map { |name| name.match(/^A./) } # => [#<Regex::MatchData "Al">, nil] ["Alice", "Bob"].compact_map { |name| name.match(/^A./) } # => [#<Regex::MatchData "Al">]
def count(&block)Source
Returns the number of elements in the collection for which the passed block returns true
.
[1, 2, 3, 4].count { |i| i % 2 == 0 } # => 2
def count(item)Source
Returns the number of times that the passed item is present in the collection.
[1, 2, 3, 4].count(3) # => 1
def cycle(n, &block)Source
Calls the given block for each element in this enumerable n times.
def cycle(&block)Source
Calls the given block for each element in this enumerable forever.
abstract def each(&block : T -> _)Source
Must yield this collection's elements to the block.
def each_cons(count : Int, reuse = false, &block)Source
Iterates over the collection yielding chunks of size count, but advancing one by one.
[1, 2, 3, 4, 5].each_cons(2) do |cons| puts cons end
Prints:
[1, 2] [2, 3] [3, 4] [4, 5]
By default, a new array is created and yielded for each consecutive slice of elements.
- If reuse is given, the array can be reused
- If reuse is an
Array
, this array will be reused - If reuse is truthy, the method will create a new array and reuse it-
This can be used to prevent many memory allocations when each slice of interest is to be used in a read-only fashion-
def each_slice(count : Int, reuse = false, &block)Source
Iterates over the collection in slices of size count, and runs the block for each of those.
[1, 2, 3, 4, 5].each_slice(2) do |slice| puts slice end
Prints:
[1, 2] [3, 4] [5]
Note that the last one can be smaller.
By default, a new array is created and yielded for each slice.
- If reuse is given, the array can be reused
- If reuse is an
Array
, this array will be reused - If reuse is truthy, the method will create a new array and reuse it-
This can be used to prevent many memory allocations when each slice of interest is to be used in a read-only fashion-
def each_with_index(offset = 0, &block)Source
Iterates over the collection, yielding both the elements and their index.
["Alice", "Bob"].each_with_index do |user, i| puts "User ##{i}: #{user}" end
Prints:
User # 0: Alice User # 1: Bob
Accepts an optional offset parameter, which tells it to start counting from there. So, a more human friendly version of the previous snippet would be:
["Alice", "Bob"].each_with_index(1) do |user, i| puts "User ##{i}: #{user}" end
Which would print:
User # 1: Alice User # 2: Bob
def each_with_object(obj, &block)Source
Iterates over the collection, passing each element and the initial object obj. Returns that object.
hash = ["Alice", "Bob"].each_with_object({} of String => Int32) do |user, sizes| sizes[user] = user.size end hash # => {"Alice" => 5, "Bob" => 3}
def find(if_none = nil, &block)Source
Returns the first element in the collection for which the passed block is true
.
Accepts an optional parameter if_none, to set what gets returned if no element is found (defaults to nil
).
[1, 2, 3, 4].find { |i| i > 2 } # => 3 [1, 2, 3, 4].find { |i| i > 8 } # => nil [1, 2, 3, 4].find(-1) { |i| i > 8 } # => -1
def first(count : Int)Source
Returns an Array
with the first count elements in the collection-
If count is bigger than the number of elements in the collection, returns as many as possible- This include the case of calling it over an empty collection, in which case it returns an empty array-
def firstSource
Returns the first element in the collection. Raises Enumerable::EmptyError
if the collection is empty.
def first?Source
Returns the first element in the collection. When the collection is empty, returns nil
.
def flat_map(&block : T -> Array(U) | Iterator(U) | U) forall USource
Returns a new array with the concatenated results of running the block (which is expected to return arrays) once for every element in the collection.
array = ["Alice", "Bob"].flat_map do |user| user.chars end array # => ['A', 'l', 'i', 'c', 'e', 'B', 'o', 'b']
def grep(pattern)Source
Returns an Array
with all the elements in the collection that match the RegExp
pattern-
["Alice", "Bob"].grep(/^A/) # => ["Alice"]
def group_by(&block : T -> U) forall USource
Returns a Hash
whose keys are each different value that the passed block returned when run for each element in the collection, and which values are an Array
of the elements for which the block returned that value-
["Alice", "Bob", "Ary"].group_by { |name| name.size } # => {5 => ["Alice"], 3 => ["Bob", "Ary"]}
def in_groups_of(size : Int, filled_up_with : U = nil) forall USource
Returns an Array
with chunks in the given size, eventually filled up with given value or nil
-
[1, 2, 3].in_groups_of(2, 0) # => [[1, 2], [3, 0]] [1, 2, 3].in_groups_of(2) # => [[1, 2], [3, nil]]
def in_groups_of(size : Int, filled_up_with : U = nil, reuse = false, &block) forall USource
Yields a block with the chunks in the given size.
[1, 2, 4].in_groups_of(2, 0) { |e| p e.sum } # => 3 # => 4
By default, a new array is created and yielded for each group.
- If reuse is given, the array can be reused
- If reuse is an
Array
, this array will be reused - If reuse is truthy, the method will create a new array and reuse it-
This can be used to prevent many memory allocations when each slice of interest is to be used in a read-only fashion-
def includes?(obj)Source
Returns true
if the collection contains obj, false
otherwise.
[1, 2, 3].includes?(2) # => true [1, 2, 3].includes?(5) # => false
def index(&block)Source
Returns the index of the first element for which the passed block returns true
.
["Alice", "Bob"].index { |name| name.size < 4 } # => 1 (Bob's index)
Returns nil
if the block didn't return true
for any element.
def index(obj)Source
Returns the index of the object obj in the collection.
["Alice", "Bob"].index("Alice") # => 0
Returns nil
if obj is not in the collection.
def index_by(&block : T -> U) forall USource
Converts an Enumerable
to a Hash
by using the value returned by the block as the hash key. Be aware, if two elements return the same value as a key one will override the other. If you want to keep all values, then you should probably use #group_by
instead.
["Anna", "Ary", "Alice"].index_by { |e| e.size } # => {4 => "Anna", 3 => "Ary", 5 => "Alice"} ["Anna", "Ary", "Alice", "Bob"].index_by { |e| e.size } # => {4 => "Anna", 3 => "Bob", 5 => "Alice"}
def join(separator, io)Source
Prints to io all the elements in the collection, separated by separator.
[1, 2, 3, 4, 5].join(", ", STDOUT)
Prints:
1, 2, 3, 4, 5
def join(separator = "")Source
Returns a String
created by concatenating the elements in the collection, separated by separator (defaults to none).
[1, 2, 3, 4, 5].join(", ") # => "1, 2, 3, 4, 5"
def join(separator, io, &block)Source
Prints to io the concatenation of the elements, with the possibility of controlling how the printing is done via a block.
[1, 2, 3, 4, 5].join(", ", STDOUT) { |i, io| io << "(#{i})" }
Prints:
(1), (2), (3), (4), (5)
def join(separator = "", &block)Source
Returns a String
created by concatenating the results of passing the elements in the collection to the passed block, separated by separator (defaults to none).
[1, 2, 3, 4, 5].join(", ") { |i| -i } # => "-1, -2, -3, -4, -5"
def map(&block : T -> U) forall USource
Returns an Array
with the results of running the block against each element of the collection-
[1, 2, 3].map { |i| i * 10 } # => [10, 20, 30]
def map_with_index(&block : T, Int32 -> U) forall USource
Like #map
, but the block gets passed both the element and its index.
["Alice", "Bob"].map_with_index { |name, i| "User ##{i}: #{name}" } # => ["User #0: Alice", "User #1: Bob"]
def maxSource
Returns the element with the maximum value in the collection.
It compares using >
so it will work for any type that supports that method.
[1, 2, 3].max # => 3 ["Alice", "Bob"].max # => "Bob"
Raises Enumerable::EmptyError
if the collection is empty.
def max_by(&block : T -> U) forall USource
Returns the element for which the passed block returns with the maximum value.
It compares using >
so the block must return a type that supports that method
["Alice", "Bob"].max_by { |name| name.size } # => "Alice"
Raises Enumerable::EmptyError
if the collection is empty.
def max_by?(&block : T -> U) forall USource
Like #max_by
but returns nil
if the collection is empty.
def max_of(&block : T -> U) forall USource
Like #max_by
but instead of the element, returns the value returned by the block.
["Alice", "Bob"].max_of { |name| name.size } # => 5 (Alice's size)
def max_of?(&block : T -> U) forall USource
Like #max_of
but returns nil
if the collection is empty.
def minSource
Returns the element with the minimum value in the collection.
It compares using <
so it will work for any type that supports that method.
[1, 2, 3].min # => 1 ["Alice", "Bob"].min # => "Alice"
Raises Enumerable::EmptyError
if the collection is empty.
def min_by(&block : T -> U) forall USource
Returns the element for which the passed block returns with the minimum value.
It compares using <
so the block must return a type that supports that method
["Alice", "Bob"].min_by { |name| name.size } # => "Bob"
Raises Enumerable::EmptyError
if the collection is empty.
def min_by?(&block : T -> U) forall USource
Like #min_by
but returns nil
if the collection is empty.
def min_of(&block : T -> U) forall USource
Like #min_by
but instead of the element, returns the value returned by the block.
["Alice", "Bob"].min_of { |name| name.size } # => 3 (Bob's size)
def min_of?(&block : T -> U) forall USource
Like #min_of
but returns nil
if the collection is empty.
def minmaxSource
Returns a Tuple
with both the minimum and maximum value.
[1, 2, 3].minmax # => {1, 3}
Raises Enumerable::EmptyError
if the collection is empty.
def minmax_by(&block : T -> U) forall USource
Returns a Tuple
with both the minimum and maximum values according to the passed block.
["Alice", "Bob", "Carl"].minmax_by { |name| name.size } # => {"Bob", "Alice"}
Raises Enumerable::EmptyError
if the collection is empty.
def minmax_by?(&block : T -> U) forall USource
Like #minmax_by
but returns {nil, nil}
if the collection is empty.
def minmax_of(&block : T -> U) forall USource
Returns a Tuple
with both the minimum and maximum value the block returns when passed the elements in the collection.
["Alice", "Bob", "Carl"].minmax_of { |name| name.size } # => {3, 5}
Raises Enumerable::EmptyError
if the collection is empty.
def minmax_of?(&block : T -> U) forall USource
Like #minmax_of
but returns {nil, nil}
if the collection is empty.
def none?(&block)Source
Returns true
if the passed block returns true
for none of the elements of the collection.
[1, 2, 3].none? { |i| i > 5 } # => true
It's the opposite of #all?
.
def none?Source
Returns true
if all of the elements of the collection are false
or nil
.
[nil, false].none? # => true [nil, false, true].none? # => false
It's the opposite of #all?
.
def one?(&block)Source
Returns true
if the passed block returns true
for exactly one of the elements of the collection.
[1, 2, 3].one? { |i| i > 2 } # => true [1, 2, 3].one? { |i| i > 1 } # => false
def partition(&block)Source
Returns a Tuple
with two arrays. The first one contains the elements in the collection for which the passed block returned true
, and the second one those for which it returned false
.
[1, 2, 3, 4, 5, 6].partition { |i| i % 2 == 0 } # => {[2, 4, 6], [1, 3, 5]}
def product(&block)Source
Multiplies all results of the passed block for each element in the collection.
["Alice", "Bob"].product { |name| name.size } # => 15 (5 * 3)
If the collection is empty, returns 1
.
([] of Int32).product { |x| x + 1 } # => 1
def product(initial : Number, &block)Source
Multiplies initial and all results of the passed block for each element in the collection.
["Alice", "Bob"].product(2) { |name| name.size } # => 30 (2 * 5 * 3)
If the collection is empty, returns 1
.
([] of String).product(1) { |name| name.size } # => 1
def productSource
Multiplies all the elements in the collection together.
Only collections of numbers (objects that can be multiplied via a *
method) are supported.
[1, 2, 3, 4, 5, 6].product # => 720
If the collection is empty, returns 1
.
([] of Int32).product # => 1
def product(initial : Number)Source
Multiplies initial and all the elements in the collection together. The type of initial will be the type of the product, so use this if (for instance) you need to specify a large enough type to avoid overflow.
Only collections of numbers (objects that can be multiplied via a *
method) are supported.
[1, 2, 3, 4, 5, 6].product(7) # => 5040
If the collection is empty, returns initial.
([] of Int32).product(7) # => 7
def reduce(&block)Source
Combines all elements in the collection by applying a binary operation, specified by a block, so as to reduce them to a single value.
For each element in the collection the block is passed an accumulator value (memo) and the element. 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. The initial value for the accumulator is the first element in the collection.
[1, 2, 3, 4, 5].reduce { |acc, i| acc + i } # => 15
def reduce(memo, &block)Source
Just like the other variant, but you can set the initial value of the accumulator.
[1, 2, 3, 4, 5].reduce(10) { |acc, i| acc + i } # => 25
def reject(&block : T -> )Source
Returns an Array
with all the elements in the collection for which the passed block returns false
-
[1, 2, 3, 4, 5, 6].reject { |i| i % 2 == 0 } # => [1, 3, 5]
def select(&block : T -> )Source
Returns an Array
with all the elements in the collection for which the passed block returns true
-
[1, 2, 3, 4, 5, 6].select { |i| i % 2 == 0 } # => [2, 4, 6]
def sizeSource
Returns the number of elements in the collection.
[1, 2, 3, 4].size # => 4
def skip(count : Int)Source
Returns an Array
with the first count elements removed from the original collection-
If count is bigger than the number of elements in the collection, returns an empty array-
[1, 2, 3, 4, 5, 6].skip(3) # => [4, 5, 6]
def skip_while(&block)Source
Skips 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-
[1, 2, 3, 4, 5, 0].skip_while { |i| i < 3 } # => [3, 4, 5, 0]
def sum(initial)Source
Adds initial and all the elements in the collection together. The type of initial will be the type of the sum, so use this if (for instance) you need to specify a large enough type to avoid overflow.
Only collections of numbers (objects that can be added via an +
method) are supported.
[1, 2, 3, 4, 5, 6].sum(7) # => 28
If the collection is empty, returns initial.
([] of Int32).sum(7) # => 7
def sumSource
Adds all the elements in the collection together.
Only collections of numbers (objects that can be added via an +
method) are supported.
[1, 2, 3, 4, 5, 6].sum # => 21
If the collection is empty, returns 0
.
([] of Int32).sum # => 0
def sum(initial, &block)Source
Adds initial and all results of the passed block for each element in the collection.
["Alice", "Bob"].sum(1) { |name| name.size } # => 9 (1 + 5 + 3)
If the collection is empty, returns 0
.
([] of String).sum(1) { |name| name.size } # => 1
def sum(&block)Source
Adds all results of the passed block for each element in the collection.
["Alice", "Bob"].sum { |name| name.size } # => 8 (5 + 3)
If the collection is empty, returns 0
.
([] of Int32).sum { |x| x + 1 } # => 0
def take_while(&block)Source
Passes elements to the block until the block returns nil
or false
, then stops iterating and returns an Array
of all prior elements-
[1, 2, 3, 4, 5, 0].take_while { |i| i < 3 } # => [1, 2]
def to_aSource
Returns an Array
with all the elements in the collection-
(1..5).to_a # => [1, 2, 3, 4, 5]
def to_hSource
© 2012–2017 Manas Technology Solutions.
Licensed under the Apache License, Version 2.0.
https://crystal-lang.org/api/0.22.0/Enumerable.html