module Enumerable[out T]

A module of collection methods built on each. A class that includes Enumerable[T] and defines each gets every other method here: mapping and filtering (#map, #select, #filter_map, #flat_map), folding (#reduce, #sum, #count, #tally), searching (#find, #include?, #any?), slicing (#first, #take_while, #each_slice), grouping (#group_by, #partition, #chunk_while) and ordering (#sort_by, #min_by). #sort, #min, #max, minmax, min(n) and max(n) need either a comparator block or elements that are Comparable, and #sum without a block needs Int, Float or Integer elements.

The methods that collect return an immutable Array, whatever the receiver is. #map, #each_with_index, #each_slice, #each_cons and #to_enum without a block return an Enumerator.

class DocDigits_Enumerable
  include Enumerable[Int]

  def each(&: (Int) -> Void) -> Void
    yield 3
    yield 1
    yield 2
  end
end

d = DocDigits_Enumerable.new
d.map { |x| x * 10 }   # => [30, 10, 20]
d.sort                 # => [1, 2, 3]
d.max                  # => 3
d.sum                  # => 6
d.each_slice(2).to_a   # => [[3, 1], [2]]

<prelude>:2968

Methods

def each(&: (T) -> Void) -> Void

Calls the block with each element in turn. The one method an includer must define.

<prelude>:2971

def map[U](&: (T) -> U) -> Array[U]

The block's results for each element, in order.

(1..3).map { |x| x * x }   # => [1, 4, 9]

<prelude>:2978

def flat_map[U](&: (T) -> Array[U]) -> Array[U]

The concatenation of the arrays the block returns for each element.

[1, 2].flat_map { |x| [x, x * 10] }   # => [1, 10, 2, 20]

<prelude>:2989

def filter_map[U](&: (T) -> U?) -> Array[U]

The block's results that are truthy (neither nil nor false).

[1, 2, 3, 4].filter_map { |x| x * 10 if x.even? }   # => [20, 40]

<prelude>:3000

def select(&: (T) -> Object) -> Array[T]

The elements for which the block is truthy, in order.

<prelude>:3010

def filter(&: (T) -> Object) -> Array[T]

The elements for which the block is truthy: #select.

<prelude>:3017

def reject(&: (T) -> Object) -> Array[T]

The elements for which the block is falsy (nil or false).

<prelude>:3020

def reduce[U](initial: U, &: (U, T) -> U) -> U

Combines the elements with the block, starting from initial: the block receives the accumulated value and the next element. initial on an empty collection.

[1, 2, 3].reduce(10) { |acc, x| acc + x }   # => 16

<prelude>:3033

def inject[U](initial: U, &: (U, T) -> U) -> U

Combines the elements with the block, starting from initial: #reduce.

<prelude>:3040

def each_with_index(&: (T, Int) -> Void) -> Void

Calls the block with each element and its index, from 0.

<prelude>:3043

def each_with_object[U](memo: U, &: (T, U) -> Void) -> U

Calls the block with each element and memo, then returns memo: for filling a builder or another mutable object.

[1, 2].each_with_object(Array::Builder[Int].new) { |x, b| b << x * 3 }.to_a
# => [3, 6]

<prelude>:3058

def find(&: (T) -> Object) -> T?

The first element for which the block is truthy, or nil.

<prelude>:3064

def detect(&: (T) -> Object) -> T?

The first element for which the block is truthy, or nil: #find.

<prelude>:3070

def find_index(&: (T) -> Object) -> Int?

The index of the first element for which the block is truthy, or nil.

<prelude>:3073

def include?(value: Object) -> Bool

Whether an element is == to value.

<prelude>:3083

def count -> Int

The number of elements. Iterates over them all.

<prelude>:3089

def count(&: (T) -> Object) -> Int

The number of elements for which the block is truthy.

<prelude>:3096

def any? -> Bool

Whether some element is truthy (neither nil nor false). False for an empty collection.

<prelude>:3104

def any?(&: (T) -> Object) -> Bool

Whether the block is truthy for some element. False for an empty collection; stops at the first match.

<prelude>:3111

def all? -> Bool

Whether every element is truthy. True for an empty collection.

<prelude>:3117

def all?(&: (T) -> Object) -> Bool

Whether the block is truthy for every element. True for an empty collection; stops at the first miss.

<prelude>:3124

def none?(&: (T) -> Object) -> Bool

Whether the block is truthy for no element. True for an empty collection.

<prelude>:3130

def one?(&: (T) -> Object) -> Bool

Whether the block is truthy for exactly one element.

<prelude>:3133

def first -> T?

The first element, or nil when there is none.

(1..).first                       # => 1
Set[Int].new.first               # => nil

<prelude>:3141

def first(n: Int) -> Array[T]

The first n elements, or all of them when there are fewer. Stops iterating once it has them, so it works on an endless range.

(1..).first(3)   # => [1, 2, 3]

Raises

ArgumentError for a negative n.

<prelude>:3156

def take(n: Int) -> Array[T]

The first n elements: first(n).

<prelude>:3170

def drop(n: Int) -> Array[T]

The elements after the first n; [] when there are no more than n.

Raises

ArgumentError for a negative n.

<prelude>:3177

def take_while(&: (T) -> Object) -> Array[T]

The elements before the first one for which the block is falsy.

[1, 2, 5, 1].take_while { |x| x < 3 }   # => [1, 2]

<prelude>:3193

def drop_while(&: (T) -> Object) -> Array[T]

The elements from the first one for which the block is falsy on.

[1, 2, 5, 1].drop_while { |x| x < 3 }   # => [5, 1]

<prelude>:3207

def to_a -> Array[T]

The elements as an array.

<prelude>:3218

def to_set -> Set[T]

The elements as a Set, without duplicates.

<prelude>:3221

def tally[U >: T] -> Hash[U, Int]

How many times each distinct element occurs, in order of first appearance.

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

<prelude>:3231

def group_by[K](&: (T) -> K) -> Hash[K, Array[T]]

The elements grouped by the block's result: each key maps to the elements that gave it, in order.

%w[ant bee cow dog].group_by { |s| s[0] == "a" || s[0] == "b" }
# => {true => ["ant", "bee"], false => ["cow", "dog"]}

<prelude>:3244

def partition(&: (T) -> Object) -> [Array[T], Array[T]]

The elements for which the block is truthy, and those for which it is falsy.

(1..5).partition { |x| x.odd? }   # => [[1, 3, 5], [2, 4]]

<prelude>:3266

def each_slice(n: Int, &: (Array[T]) -> Void) -> Void

Calls the block with consecutive slices of n elements; the last one may be shorter. Nothing is yielded for an empty collection.

<prelude>:3281

def uniq -> Array[T]

The elements without duplicates (by == and hash), each at its first occurrence.

<prelude>:3296

def zip[U](other: Array[U]) -> Array[[T, U]]

Pairs of each element with the element of other at the same index.

Raises

IndexError when other is shorter than the receiver (Ruby pads with nil, as #zip? does); a longer other's extra elements are ignored.

[1, 2].zip(["a", "b", "c"])   # => [[1, "a"], [2, "b"]]
[1, 2].zip(["a"])             # raises IndexError

<prelude>:3319

def zip?[U](other: Array[U]) -> Array[[T, U?]]

Pairs of each element with the element of other at the same index, or nil past its end, as Ruby's zip; a longer other's extra elements are ignored.

[1, 2].zip?(["a"])            # => [[1, "a"], [2, nil]]

<prelude>:3335

def min_by[U <: Comparable[U]](&: (T) -> U) -> T?

The element for which the block's result is smallest (the first one on a tie), or nil when there is none. Results compare with <=>, as in #min: a NaN result is the largest.

%w[ccc a bb].min_by { |s| s.size }   # => "a"
[Float::NAN, 1.0].min_by { |x| x }   # => 1.0

<prelude>:3353

def max_by[U <: Comparable[U]](&: (T) -> U) -> T?

The element for which the block's result is largest (the first one on a tie), or nil when there is none. Results compare with <=>, as in #max: a NaN result is the largest.

<prelude>:3371

def sort_by[U <: Comparable[U]](&: (T) -> U) -> Array[T]

The elements sorted by the block's result. The sort is stable: elements with equal keys keep their order.

%w[ccc a bb].sort_by { |s| s.size }   # => ["a", "bb", "ccc"]

<prelude>:3392

def lazy -> Array[T]

The elements as an array. Evaluation is not lazy yet: this is #to_a, and a lazy enumerator is planned.

<prelude>:3399

def collect[U](&: (T) -> U) -> Array[U]

The block's results for each element: #map.

<prelude>:3404

def collect_concat[U](&: (T) -> Array[U]) -> Array[U]

The concatenation of the arrays the block returns: #flat_map.

<prelude>:3406

def find_all(&: (T) -> Object) -> Array[T]

The elements for which the block is truthy: #select.

<prelude>:3408

def member?(value: Object) -> Bool

Whether an element is == to value: #include?.

<prelude>:3410

def entries -> Array[T]

The elements as an array: #to_a.

<prelude>:3412

def reduce[U >: T](&: (U, T) -> U) -> U?

Combines the elements with the block, starting from the first element; nil for an empty collection, and the element itself for a single one.

[1, 2, 3].reduce { |acc, x| acc * x }   # => 6
Array[Int].new.reduce { |acc, x| acc + x }   # => nil

<prelude>:3421

def inject[U >: T](&: (U, T) -> U) -> U?

Combines the elements with the block, from the first one: #reduce.

<prelude>:3431

def count(value: Object) -> Int

The number of elements == to value.

<prelude>:3434

def none? -> Bool

Whether no element is truthy. True for an empty collection.

<prelude>:3437

def one? -> Bool

Whether exactly one element is truthy.

<prelude>:3440

def find_index(value: Object) -> Int?

The index of the first element == to value, or nil.

<prelude>:3443

def reverse_each(&: (T) -> Void) -> Void

Calls the block with each element, last first. Collects them first.

<prelude>:3446

def each_cons(n: Int, &: (Array[T]) -> Void) -> Void

Calls the block with each run of n consecutive elements (a sliding window); nothing when there are fewer than n.

Raises

ArgumentError when n is not positive.

(1..4).each_cons(2).to_a   # => [[1, 2], [2, 3], [3, 4]]

<prelude>:3460

def chunk_while(&: (T, T) -> Object) -> Array[Array[T]]

Consecutive elements for which the block holds stay in one chunk.

The result is the list of chunks; [] for an empty collection.

[1, 2, 4, 5, 7].chunk_while { |a, b| b == a + 1 }
# => [[1, 2], [4, 5], [7]]

<prelude>:3478

def slice_when(&: (T, T) -> Object) -> Array[Array[T]]

The chunk is cut where the block holds.

The block receives each pair of neighbours; the result is a list of the chunks.

[1, 2, 4, 5, 7].slice_when { |a, b| b != a + 1 }
# => [[1, 2], [4, 5], [7]]

<prelude>:3506

def uniq[U](&: (T) -> U) -> Array[T]

The elements without duplicates by the block's result, each at the first element that gave its key.

[1, 2, 3, 4].uniq { |x| x % 2 }   # => [1, 2]

<prelude>:3516

def tally_by[K](&: (T) -> K) -> Hash[K, Int]

How many elements give each result of the block, in order of first appearance.

<prelude>:3531

def to_h[K, V](&: (T) -> [K, V]) -> Hash[K, V]

A hash of the [key, value] pairs the block returns; a later pair replaces an earlier one with the same key.

%w[a bb].to_h { |s| [s, s.size] }   # => {"a" => 1, "bb" => 2}

<prelude>:3546

def cycle(n: Int, &: (T) -> Void) -> Void

Calls the block with each element, n times over. Collects the elements first; does nothing when there are none.

<prelude>:3557

def cycle(&: (T) -> Void) -> Void

Calls the block with each element, over and over, until the block breaks or raises. Returns nil at once when there are no elements.

<prelude>:3565

def each_entry(&: (T) -> Void) -> Void

Calls the block with each element: #each.

<prelude>:3574

def sum(&: (T) -> Int) -> Int

The sum of the block's results; 0 for an empty collection.

<prelude>:3577

def sum(&: (T) -> Float) -> Float

The sum of the block's results; 0.0 for an empty collection.

<prelude>:3579

def sort(&: (T, T) -> Int) -> Array[T]

The elements sorted by the comparator block, which returns a negative number, zero or a positive number as <=> does. The sort is stable.

To order by a key, #sort_by is usually simpler.

[1, 3, 2].sort { |a, b| b <=> a }   # => [3, 2, 1]

<prelude>:3589

def min(&: (T, T) -> Int) -> T?

The smallest element by the comparator block (negative, zero or positive, as <=>), or nil when there is none.

<prelude>:3592

def max(&: (T, T) -> Int) -> T?

The largest element by the comparator block, or nil when there is none.

<prelude>:3595

def to_enum -> Enumerator[T]

An enumerator over the elements, for Enumerator's methods (Enumerator#next, Enumerator#with_index).

The iterating methods given no block return one too, as in Ruby: xs.each_with_index.map { |x, i| }, xs.map.with_index { |x, i| }.

[1, 2].to_enum.next    # => 1

<prelude>:3606

def map -> Enumerator[T]

An enumerator over the elements, for Enumerator#with_index: xs.map.with_index { |x, i| }.

<prelude>:3608

def each_with_index -> Enumerator[[T, Int]]

An enumerator of [element, index] pairs: xs.each_with_index.map { |x, i| }.

%w[a b].each_with_index.to_a   # => [["a", 0], ["b", 1]]

<prelude>:3615

def each_slice(n: Int) -> Enumerator[Array[T]]

An enumerator of the slices each_slice(n) { } would yield.

Raises

ArgumentError when n is not positive.

<prelude>:3624

def each_cons(n: Int) -> Enumerator[Array[T]]

An enumerator of the windows each_cons(n) { } would yield.

Raises

ArgumentError when n is not positive.

<prelude>:3630

def sort -> Array[T]

The elements in ascending order (by <=>). The sort is stable.

[3, 1, 2].sort       # => [1, 2, 3]
%w[b c a].sort       # => ["a", "b", "c"]

<prelude>:3640

def min -> T?

The smallest element, or nil when there is none.

[3, 1, 2].min          # => 1
Array[Int].new.min     # => nil

<prelude>:3647

def max -> T?

The largest element, or nil when there is none.

<prelude>:3649

def minmax -> [T?, T?]

The smallest and the largest elements; [nil, nil] when there are none.

[3, 1, 2].minmax   # => [1, 3]

<prelude>:3655

def min(n: Int) -> Array[T]

The n smallest elements, smallest first (all of them when there are fewer); ArgumentError for a negative n.

<prelude>:3658

def max(n: Int) -> Array[T]

The n largest elements, largest first (all of them when there are fewer); ArgumentError for a negative n.

[3, 1, 2].max(2)   # => [3, 2]

<prelude>:3668

def sum -> Int

The sum of the elements; 0 for an empty collection.

<prelude>:3676

def sum -> Float

The sum of the elements; 0.0 for an empty collection.

<prelude>:3681

def sum -> Integer

The sum of the elements; 0 for an empty collection.

<prelude>:3686