rbs 3.7.0 → 3.8.0.pre.1

data/core/enumerable.rbs

@@ -11,14 +11,13 @@
 # *   [Iterating](rdoc-ref:Enumerable@Methods+for+Iterating)
 # *   [And more....](rdoc-ref:Enumerable@Other+Methods)
 #
-#
 # ### Methods for Querying
 #
 # These methods return information about the Enumerable other than the elements
 # themselves:
 #
-# *   #include?, #member?: Returns `true` if `self == object`, `false`
-#     otherwise.
+# *   #member? (aliased as #include?): Returns `true` if `self == object`,
+#     `false` otherwise.
 # *   #all?: Returns `true` if all elements meet a specified criterion; `false`
 #     otherwise.
 # *   #any?: Returns `true` if any element meets a specified criterion; `false`
@@ -32,27 +31,25 @@
 # *   #tally: Returns a new Hash containing the counts of occurrences of each
 #     element.
 #
-#
 # ### Methods for Fetching
 #
 # These methods return entries from the Enumerable, without modifying it:
 #
 # *Leading, trailing, or all elements*:
 #
-# *   #entries, #to_a: Returns all elements.
+# *   #to_a (aliased as #entries): Returns all elements.
 # *   #first: Returns the first element or leading elements.
 # *   #take: Returns a specified number of leading elements.
 # *   #drop: Returns a specified number of trailing elements.
 # *   #take_while: Returns leading elements as specified by the given block.
 # *   #drop_while: Returns trailing elements as specified by the given block.
 #
-#
 # *Minimum and maximum value elements*:
 #
 # *   #min: Returns the elements whose values are smallest among the elements,
-#     as determined by `<=>` or a given block.
+#     as determined by `#<=>` or a given block.
 # *   #max: Returns the elements whose values are largest among the elements, as
-#     determined by `<=>` or a given block.
+#     determined by `#<=>` or a given block.
 # *   #minmax: Returns a 2-element Array containing the smallest and largest
 #     elements.
 # *   #min_by: Returns the smallest element, as determined by the given block.
@@ -60,7 +57,6 @@
 # *   #minmax_by: Returns the smallest and largest elements, as determined by
 #     the given block.
 #
-#
 # *Groups, slices, and partitions*:
 #
 # *   #group_by: Returns a Hash that partitions the elements into groups.
@@ -77,27 +73,25 @@
 # *   #chunk_while: Returns elements organized into chunks as specified by the
 #     given block.
 #
-#
 # ### Methods for Searching and Filtering
 #
 # These methods return elements that meet a specified criterion:
 #
-# *   #find, #detect: Returns an element selected by the block.
-# *   #find_all, #filter, #select: Returns elements selected by the block.
+# *   #find (aliased as #detect): Returns an element selected by the block.
+# *   #find_all (aliased as #filter, #select): Returns elements selected by the
+#     block.
 # *   #find_index: Returns the index of an element selected by a given object or
 #     block.
 # *   #reject: Returns elements not rejected by the block.
 # *   #uniq: Returns elements that are not duplicates.
 #
-#
 # ### Methods for Sorting
 #
 # These methods return elements in sorted order:
 #
-# *   #sort: Returns the elements, sorted by `<=>` or the given block.
+# *   #sort: Returns the elements, sorted by `#<=>` or the given block.
 # *   #sort_by: Returns the elements, sorted by the given block.
 #
-#
 # ### Methods for Iterating
 #
 # *   #each_entry: Calls the block with each successive element (slightly
@@ -112,24 +106,23 @@
 # *   #reverse_each: Calls the block with each successive element, in reverse
 #     order.
 #
-#
 # ### Other Methods
 #
-# *   #map, #collect: Returns objects returned by the block.
+# *   #collect (aliased as #map): Returns objects returned by the block.
 # *   #filter_map: Returns truthy objects returned by the block.
-# *   #flat_map, #collect_concat: Returns flattened objects returned by the
-#     block.
+# *   #flat_map (aliased as #collect_concat): Returns flattened objects returned
+#     by the block.
 # *   #grep: Returns elements selected by a given object or objects returned by
 #     a given block.
 # *   #grep_v: Returns elements selected by a given object or objects returned
 #     by a given block.
-# *   #reduce, #inject: Returns the object formed by combining all elements.
+# *   #inject (aliased as #reduce): Returns the object formed by combining all
+#     elements.
 # *   #sum: Returns the sum of the elements, using method `+`.
 # *   #zip: Combines each element with elements from other enumerables; returns
 #     the n-tuples or calls the block with each.
 # *   #cycle: Calls the block with each element, cycling repeatedly.
 #
-#
 # ## Usage
 #
 # To use module Enumerable in a collection class:
@@ -141,7 +134,6 @@
 # *   Implement method `#each` which must yield successive elements of the
 #     collection. The method will be called by almost any Enumerable method.
 #
-#
 # Example:
 #
 #     class Foo
@@ -174,7 +166,6 @@
 # *   Range
 # *   Struct
 #
-#
 # These Ruby standard library classes include Enumerable:
 #
 # *   CSV
@@ -182,7 +173,6 @@
 # *   CSV::Row
 # *   Set
 #
-#
 # Virtually all methods in Enumerable call method `#each` in the including
 # class:
 #
@@ -191,7 +181,6 @@
 # *   For the other classes above, `#each` yields the next object from the
 #     collection.
 #
-#
 # ## About the Examples
 #
 # The example code snippets for the Enumerable methods:
@@ -479,8 +468,8 @@ module Enumerable[unchecked out Elem] : _Each[Elem]
   #   - each_with_index(*args) {|element, i| ..... } -> self
   #   - each_with_index(*args)                       -> enumerator
   # -->
-  # With a block given, calls the block with each element and its index; returns
-  # `self`:
+  # Invoke `self.each` with `*args`. With a block given, the block receives each
+  # element and its index; returns `self`:
   #
   #     h = {}
   #     (1..4).each_with_index {|element, i| h[element] = i } # => 1..4
@@ -704,7 +693,6 @@ module Enumerable[unchecked out Elem] : _Each[Elem]
   # *   Each value is an array of those elements for which the block returned that
   #     key.
   #
-  #
   # Examples:
   #
   #     g = (1..6).group_by {|i| i%3 }
@@ -734,152 +722,155 @@ module Enumerable[unchecked out Elem] : _Each[Elem]
 
   # <!--
   #   rdoc-file=enum.c
-  #   - inject(symbol) -> object
-  #   - inject(initial_operand, symbol) -> object
-  #   - inject {|memo, operand| ... } -> object
-  #   - inject(initial_operand) {|memo, operand| ... } -> object
+  #   - inject(symbol)                -> object
+  #   - inject(initial_value, symbol) -> object
+  #   - inject {|memo, value| ... }   -> object
+  #   - inject(initial_value) {|memo, value| ... } -> object
   # -->
-  # Returns an object formed from operands via either:
-  #
-  # *   A method named by `symbol`.
-  # *   A block to which each operand is passed.
-  #
-  #
-  # With method-name argument `symbol`, combines operands using the method:
-  #
-  #     # Sum, without initial_operand.
-  #     (1..4).inject(:+)     # => 10
-  #     # Sum, with initial_operand.
-  #     (1..4).inject(10, :+) # => 20
+  # Returns the result of applying a reducer to an initial value and the first
+  # element of the Enumerable. It then takes the result and applies the function
+  # to it and the second element of the collection, and so on. The return value is
+  # the result returned by the final call to the function.
   #
-  # With a block, passes each operand to the block:
+  # You can think of
   #
-  #     # Sum of squares, without initial_operand.
-  #     (1..4).inject {|sum, n| sum + n*n }    # => 30
-  #     # Sum of squares, with initial_operand.
-  #     (1..4).inject(2) {|sum, n| sum + n*n } # => 32
+  #     [ a, b, c, d ].inject(i) { |r, v| fn(r, v) }
   #
-  # **Operands**
+  # as being
   #
-  # If argument `initial_operand` is not given, the operands for `inject` are
-  # simply the elements of `self`. Example calls and their operands:
+  #     fn(fn(fn(fn(i, a), b), c), d)
   #
-  #     `(1..4).inject(:+)`
-  # :       `[1, 2, 3, 4]`.
+  # In a way the `inject` function *injects* the function between the elements of
+  # the enumerable.
   #
-  #     `(1...4).inject(:+)`
-  # :       `[1, 2, 3]`.
+  # `inject` is aliased as `reduce`. You use it when you want to *reduce* a
+  # collection to a single value.
   #
-  #     `('a'..'d').inject(:+)`
-  # :       `['a', 'b', 'c', 'd']`.
-  #
-  #     `('a'...'d').inject(:+)`
-  # :       `['a', 'b', 'c']`.
+  # **The Calling Sequences**
   #
+  # Let's start with the most verbose:
   #
+  #     enum.inject(initial_value) do |result, next_value|
+  #       # do something with +result+ and +next_value+
+  #       # the value returned by the block becomes the
+  #       # value passed in to the next iteration
+  #       # as +result+
+  #     end
   #
-  # Examples with first operand (which is `self.first`) of various types:
+  # For example:
   #
-  #     # Integer.
-  #     (1..4).inject(:+)                # => 10
-  #     # Float.
-  #     [1.0, 2, 3, 4].inject(:+)        # => 10.0
-  #     # Character.
-  #     ('a'..'d').inject(:+)            # => "abcd"
-  #     # Complex.
-  #     [Complex(1, 2), 3, 4].inject(:+) # => (8+2i)
+  #     product = [ 2, 3, 4 ].inject(1) do |result, next_value|
+  #       result * next_value
+  #     end
+  #     product #=> 24
   #
-  # If argument `initial_operand` is given, the operands for `inject` are that
-  # value plus the elements of `self`. Example calls their operands:
+  # When this runs, the block is first called with `1` (the initial value) and `2`
+  # (the first element of the array). The block returns `1*2`, so on the next
+  # iteration the block is called with `2` (the previous result) and `3`. The
+  # block returns `6`, and is called one last time with `6` and `4`. The result of
+  # the block, `24` becomes the value returned by `inject`. This code returns the
+  # product of the elements in the enumerable.
   #
-  #     `(1..4).inject(10, :+)`
-  # :       `[10, 1, 2, 3, 4]`.
+  # **First Shortcut: Default Initial value**
   #
-  #     `(1...4).inject(10, :+)`
-  # :       `[10, 1, 2, 3]`.
+  # In the case of the previous example, the initial value, `1`, wasn't really
+  # necessary: the calculation of the product of a list of numbers is
+  # self-contained.
   #
-  #     `('a'..'d').inject('e', :+)`
-  # :       `['e', 'a', 'b', 'c', 'd']`.
+  # In these circumstances, you can omit the `initial_value` parameter. `inject`
+  # will then initially call the block with the first element of the collection as
+  # the `result` parameter and the second element as the `next_value`.
   #
-  #     `('a'...'d').inject('e', :+)`
-  # :       `['e', 'a', 'b', 'c']`.
+  #     [ 2, 3, 4 ].inject do |result, next_value|
+  #       result * next_value
+  #     end
   #
+  # This shortcut is convenient, but can only be used when the block produces a
+  # result which can be passed back to it as a first parameter.
   #
+  # Here's an example where that's not the case: it returns a hash where the keys
+  # are words and the values are the number of occurrences of that word in the
+  # enumerable.
   #
-  # Examples with `initial_operand` of various types:
+  #     freqs = File.read("README.md")
+  #       .scan(/\w{2,}/)
+  #       .reduce(Hash.new(0)) do |counts, word|
+  #         counts[word] += 1
+  #         counts
+  #       end
+  #     freqs #=> {"Actions"=>4,
+  #                "Status"=>5,
+  #                "MinGW"=>3,
+  #                "https"=>27,
+  #                "github"=>10,
+  #                "com"=>15, ...
   #
-  #     # Integer.
-  #     (1..4).inject(2, :+)               # => 12
-  #     # Float.
-  #     (1..4).inject(2.0, :+)             # => 12.0
-  #     # String.
-  #     ('a'..'d').inject('foo', :+)       # => "fooabcd"
-  #     # Array.
-  #     %w[a b c].inject(['x'], :push)     # => ["x", "a", "b", "c"]
-  #     # Complex.
-  #     (1..4).inject(Complex(2, 2), :+)   # => (12+2i)
+  # Note that the last line of the block is just the word `counts`. This ensures
+  # the return value of the block is the result that's being calculated.
   #
-  # **Combination by Given \Method**
+  # **Second Shortcut: a Reducer function**
   #
-  # If the method-name argument `symbol` is given, the operands are combined by
-  # that method:
+  # A *reducer function* is a function that takes a partial result and the next
+  # value, returning the next partial result. The block that is given to `inject`
+  # is a reducer.
   #
-  # *   The first and second operands are combined.
-  # *   That result is combined with the third operand.
-  # *   That result is combined with the fourth operand.
-  # *   And so on.
+  # You can also write a reducer as a function and pass the name of that function
+  # (as a symbol) to `inject`. However, for this to work, the function
   #
+  # 1.  Must be defined on the type of the result value
+  # 2.  Must accept a single parameter, the next value in the collection, and
+  # 3.  Must return an updated result which will also implement the function.
   #
-  # The return value from `inject` is the result of the last combination.
+  # Here's an example that adds elements to a string. The two calls invoke the
+  # functions String#concat and String#+ on the result so far, passing it the next
+  # value.
   #
-  # This call to `inject` computes the sum of the operands:
+  #     s = [ "cat", " ", "dog" ].inject("", :concat)
+  #     s #=> "cat dog"
+  #     s = [ "cat", " ", "dog" ].inject("The result is:", :+)
+  #     s #=> "The result is: cat dog"
   #
-  #     (1..4).inject(:+) # => 10
+  # Here's a more complex example when the result object maintains state of a
+  # different type to the enumerable elements.
   #
-  # Examples with various methods:
+  #     class Turtle
   #
-  #     # Integer addition.
-  #     (1..4).inject(:+)                # => 10
-  #     # Integer multiplication.
-  #     (1..4).inject(:*)                # => 24
-  #     # Character range concatenation.
-  #     ('a'..'d').inject('', :+)        # => "abcd"
-  #     # String array concatenation.
-  #     %w[foo bar baz].inject('', :+)   # => "foobarbaz"
-  #     # Hash update.
-  #     h = [{foo: 0, bar: 1}, {baz: 2}, {bat: 3}].inject(:update)
-  #     h # => {:foo=>0, :bar=>1, :baz=>2, :bat=>3}
-  #     # Hash conversion to nested arrays.
-  #     h = {foo: 0, bar: 1}.inject([], :push)
-  #     h # => [[:foo, 0], [:bar, 1]]
+  #       def initialize
+  #         @x = @y = 0
+  #       end
   #
-  # **Combination by Given Block**
+  #       def move(dir)
+  #         case dir
+  #         when "n" then @y += 1
+  #         when "s" then @y -= 1
+  #         when "e" then @x += 1
+  #         when "w" then @x -= 1
+  #         end
+  #         self
+  #       end
+  #     end
   #
-  # If a block is given, the operands are passed to the block:
+  #     position = "nnneesw".chars.reduce(Turtle.new, :move)
+  #     position  #=>> #<Turtle:0x00000001052f4698 @y=2, @x=1>
   #
-  # *   The first call passes the first and second operands.
-  # *   The second call passes the result of the first call, along with the third
-  #     operand.
-  # *   The third call passes the result of the second call, along with the fourth
-  #     operand.
-  # *   And so on.
+  # **Third Shortcut: Reducer With no Initial Value**
   #
+  # If your reducer returns a value that it can accept as a parameter, then you
+  # don't have to pass in an initial value. Here `:*` is the name of the *times*
+  # function:
   #
-  # The return value from `inject` is the return value from the last block call.
+  #     product = [ 2, 3, 4 ].inject(:*)
+  #     product # => 24
   #
-  # This call to `inject` gives a block that writes the memo and element, and also
-  # sums the elements:
+  # String concatenation again:
   #
-  #     (1..4).inject do |memo, element|
-  #       p "Memo: #{memo}; element: #{element}"
-  #       memo + element
-  #     end # => 10
+  #     s = [ "cat", " ", "dog" ].inject(:+)
+  #     s #=> "cat dog"
   #
-  # Output:
+  # And an example that converts a hash to an array of two-element subarrays.
   #
-  #     "Memo: 1; element: 2"
-  #     "Memo: 3; element: 3"
-  #     "Memo: 6; element: 4"
+  #     nested = {foo: 0, bar: 1}.inject([], :push)
+  #     nested # => [[:foo, 0], [:bar, 1]]
   #
   def inject: (untyped init, Symbol method) -> untyped
             | (Symbol method) -> untyped
@@ -897,7 +888,7 @@ module Enumerable[unchecked out Elem] : _Each[Elem]
   # The ordering of equal elements is indeterminate and may be unstable.
   #
   # With no argument and no block, returns the maximum element, using the
-  # elements' own method `<=>` for comparison:
+  # elements' own method `#<=>` for comparison:
   #
   #     (1..4).max                   # => 4
   #     (-4..-1).max                 # => -1
@@ -921,7 +912,6 @@ module Enumerable[unchecked out Elem] : _Each[Elem]
   # *   Zero if `a == b`.
   # *   A positive integer if `a > b`.
   #
-  #
   # With a block given and no argument, returns the maximum element as determined
   # by the block:
   #
@@ -996,7 +986,7 @@ module Enumerable[unchecked out Elem] : _Each[Elem]
   # The ordering of equal elements is indeterminate and may be unstable.
   #
   # With no argument and no block, returns the minimum element, using the
-  # elements' own method `<=>` for comparison:
+  # elements' own method `#<=>` for comparison:
   #
   #     (1..4).min                   # => 1
   #     (-4..-1).min                 # => -4
@@ -1020,7 +1010,6 @@ module Enumerable[unchecked out Elem] : _Each[Elem]
   # *   Zero if `a == b`.
   # *   A positive integer if `a > b`.
   #
-  #
   # With a block given and no argument, returns the minimum element as determined
   # by the block:
   #
@@ -1094,7 +1083,7 @@ module Enumerable[unchecked out Elem] : _Each[Elem]
   # indeterminate and may be unstable.
   #
   # With no argument and no block, returns the minimum and maximum elements, using
-  # the elements' own method `<=>` for comparison:
+  # the elements' own method `#<=>` for comparison:
   #
   #     (1..4).minmax                   # => [1, 4]
   #     (-4..-1).minmax                 # => [-4, -1]
@@ -1234,7 +1223,6 @@ module Enumerable[unchecked out Elem] : _Each[Elem]
   #     value.
   # *   The other having all other elements.
   #
-  #
   # Examples:
   #
   #     p = (1..4).partition {|i| i.even? }
@@ -1309,7 +1297,7 @@ module Enumerable[unchecked out Elem] : _Each[Elem]
   # Returns an array containing the sorted elements of `self`. The ordering of
   # equal elements is indeterminate and may be unstable.
   #
-  # With no block given, the sort compares using the elements' own method `<=>`:
+  # With no block given, the sort compares using the elements' own method `#<=>`:
   #
   #     %w[b c a d].sort              # => ["a", "b", "c", "d"]
   #     {foo: 0, bar: 1, baz: 2}.sort # => [[:bar, 1], [:baz, 2], [:foo, 0]]
@@ -1321,7 +1309,6 @@ module Enumerable[unchecked out Elem] : _Each[Elem]
   # *   Zero if `a == b`.
   # *   A positive integer if `a > b`.
   #
-  #
   # Examples:
   #
   #     a = %w[b c a d]
@@ -1578,147 +1565,150 @@ module Enumerable[unchecked out Elem] : _Each[Elem]
   def member?: (Elem arg0) -> bool
 
   # <!-- rdoc-file=enum.c -->
-  # Returns an object formed from operands via either:
-  #
-  # *   A method named by `symbol`.
-  # *   A block to which each operand is passed.
-  #
+  # Returns the result of applying a reducer to an initial value and the first
+  # element of the Enumerable. It then takes the result and applies the function
+  # to it and the second element of the collection, and so on. The return value is
+  # the result returned by the final call to the function.
   #
-  # With method-name argument `symbol`, combines operands using the method:
+  # You can think of
   #
-  #     # Sum, without initial_operand.
-  #     (1..4).inject(:+)     # => 10
-  #     # Sum, with initial_operand.
-  #     (1..4).inject(10, :+) # => 20
+  #     [ a, b, c, d ].inject(i) { |r, v| fn(r, v) }
   #
-  # With a block, passes each operand to the block:
+  # as being
   #
-  #     # Sum of squares, without initial_operand.
-  #     (1..4).inject {|sum, n| sum + n*n }    # => 30
-  #     # Sum of squares, with initial_operand.
-  #     (1..4).inject(2) {|sum, n| sum + n*n } # => 32
+  #     fn(fn(fn(fn(i, a), b), c), d)
   #
-  # **Operands**
+  # In a way the `inject` function *injects* the function between the elements of
+  # the enumerable.
   #
-  # If argument `initial_operand` is not given, the operands for `inject` are
-  # simply the elements of `self`. Example calls and their operands:
+  # `inject` is aliased as `reduce`. You use it when you want to *reduce* a
+  # collection to a single value.
   #
-  #     `(1..4).inject(:+)`
-  # :       `[1, 2, 3, 4]`.
-  #
-  #     `(1...4).inject(:+)`
-  # :       `[1, 2, 3]`.
-  #
-  #     `('a'..'d').inject(:+)`
-  # :       `['a', 'b', 'c', 'd']`.
-  #
-  #     `('a'...'d').inject(:+)`
-  # :       `['a', 'b', 'c']`.
+  # **The Calling Sequences**
   #
+  # Let's start with the most verbose:
   #
+  #     enum.inject(initial_value) do |result, next_value|
+  #       # do something with +result+ and +next_value+
+  #       # the value returned by the block becomes the
+  #       # value passed in to the next iteration
+  #       # as +result+
+  #     end
   #
-  # Examples with first operand (which is `self.first`) of various types:
+  # For example:
   #
-  #     # Integer.
-  #     (1..4).inject(:+)                # => 10
-  #     # Float.
-  #     [1.0, 2, 3, 4].inject(:+)        # => 10.0
-  #     # Character.
-  #     ('a'..'d').inject(:+)            # => "abcd"
-  #     # Complex.
-  #     [Complex(1, 2), 3, 4].inject(:+) # => (8+2i)
+  #     product = [ 2, 3, 4 ].inject(1) do |result, next_value|
+  #       result * next_value
+  #     end
+  #     product #=> 24
   #
-  # If argument `initial_operand` is given, the operands for `inject` are that
-  # value plus the elements of `self`. Example calls their operands:
+  # When this runs, the block is first called with `1` (the initial value) and `2`
+  # (the first element of the array). The block returns `1*2`, so on the next
+  # iteration the block is called with `2` (the previous result) and `3`. The
+  # block returns `6`, and is called one last time with `6` and `4`. The result of
+  # the block, `24` becomes the value returned by `inject`. This code returns the
+  # product of the elements in the enumerable.
   #
-  #     `(1..4).inject(10, :+)`
-  # :       `[10, 1, 2, 3, 4]`.
+  # **First Shortcut: Default Initial value**
   #
-  #     `(1...4).inject(10, :+)`
-  # :       `[10, 1, 2, 3]`.
+  # In the case of the previous example, the initial value, `1`, wasn't really
+  # necessary: the calculation of the product of a list of numbers is
+  # self-contained.
   #
-  #     `('a'..'d').inject('e', :+)`
-  # :       `['e', 'a', 'b', 'c', 'd']`.
+  # In these circumstances, you can omit the `initial_value` parameter. `inject`
+  # will then initially call the block with the first element of the collection as
+  # the `result` parameter and the second element as the `next_value`.
   #
-  #     `('a'...'d').inject('e', :+)`
-  # :       `['e', 'a', 'b', 'c']`.
+  #     [ 2, 3, 4 ].inject do |result, next_value|
+  #       result * next_value
+  #     end
   #
+  # This shortcut is convenient, but can only be used when the block produces a
+  # result which can be passed back to it as a first parameter.
   #
+  # Here's an example where that's not the case: it returns a hash where the keys
+  # are words and the values are the number of occurrences of that word in the
+  # enumerable.
   #
-  # Examples with `initial_operand` of various types:
+  #     freqs = File.read("README.md")
+  #       .scan(/\w{2,}/)
+  #       .reduce(Hash.new(0)) do |counts, word|
+  #         counts[word] += 1
+  #         counts
+  #       end
+  #     freqs #=> {"Actions"=>4,
+  #                "Status"=>5,
+  #                "MinGW"=>3,
+  #                "https"=>27,
+  #                "github"=>10,
+  #                "com"=>15, ...
   #
-  #     # Integer.
-  #     (1..4).inject(2, :+)               # => 12
-  #     # Float.
-  #     (1..4).inject(2.0, :+)             # => 12.0
-  #     # String.
-  #     ('a'..'d').inject('foo', :+)       # => "fooabcd"
-  #     # Array.
-  #     %w[a b c].inject(['x'], :push)     # => ["x", "a", "b", "c"]
-  #     # Complex.
-  #     (1..4).inject(Complex(2, 2), :+)   # => (12+2i)
+  # Note that the last line of the block is just the word `counts`. This ensures
+  # the return value of the block is the result that's being calculated.
   #
-  # **Combination by Given \Method**
+  # **Second Shortcut: a Reducer function**
   #
-  # If the method-name argument `symbol` is given, the operands are combined by
-  # that method:
+  # A *reducer function* is a function that takes a partial result and the next
+  # value, returning the next partial result. The block that is given to `inject`
+  # is a reducer.
   #
-  # *   The first and second operands are combined.
-  # *   That result is combined with the third operand.
-  # *   That result is combined with the fourth operand.
-  # *   And so on.
+  # You can also write a reducer as a function and pass the name of that function
+  # (as a symbol) to `inject`. However, for this to work, the function
   #
+  # 1.  Must be defined on the type of the result value
+  # 2.  Must accept a single parameter, the next value in the collection, and
+  # 3.  Must return an updated result which will also implement the function.
   #
-  # The return value from `inject` is the result of the last combination.
+  # Here's an example that adds elements to a string. The two calls invoke the
+  # functions String#concat and String#+ on the result so far, passing it the next
+  # value.
   #
-  # This call to `inject` computes the sum of the operands:
+  #     s = [ "cat", " ", "dog" ].inject("", :concat)
+  #     s #=> "cat dog"
+  #     s = [ "cat", " ", "dog" ].inject("The result is:", :+)
+  #     s #=> "The result is: cat dog"
   #
-  #     (1..4).inject(:+) # => 10
+  # Here's a more complex example when the result object maintains state of a
+  # different type to the enumerable elements.
   #
-  # Examples with various methods:
+  #     class Turtle
   #
-  #     # Integer addition.
-  #     (1..4).inject(:+)                # => 10
-  #     # Integer multiplication.
-  #     (1..4).inject(:*)                # => 24
-  #     # Character range concatenation.
-  #     ('a'..'d').inject('', :+)        # => "abcd"
-  #     # String array concatenation.
-  #     %w[foo bar baz].inject('', :+)   # => "foobarbaz"
-  #     # Hash update.
-  #     h = [{foo: 0, bar: 1}, {baz: 2}, {bat: 3}].inject(:update)
-  #     h # => {:foo=>0, :bar=>1, :baz=>2, :bat=>3}
-  #     # Hash conversion to nested arrays.
-  #     h = {foo: 0, bar: 1}.inject([], :push)
-  #     h # => [[:foo, 0], [:bar, 1]]
+  #       def initialize
+  #         @x = @y = 0
+  #       end
   #
-  # **Combination by Given Block**
+  #       def move(dir)
+  #         case dir
+  #         when "n" then @y += 1
+  #         when "s" then @y -= 1
+  #         when "e" then @x += 1
+  #         when "w" then @x -= 1
+  #         end
+  #         self
+  #       end
+  #     end
   #
-  # If a block is given, the operands are passed to the block:
+  #     position = "nnneesw".chars.reduce(Turtle.new, :move)
+  #     position  #=>> #<Turtle:0x00000001052f4698 @y=2, @x=1>
   #
-  # *   The first call passes the first and second operands.
-  # *   The second call passes the result of the first call, along with the third
-  #     operand.
-  # *   The third call passes the result of the second call, along with the fourth
-  #     operand.
-  # *   And so on.
+  # **Third Shortcut: Reducer With no Initial Value**
   #
+  # If your reducer returns a value that it can accept as a parameter, then you
+  # don't have to pass in an initial value. Here `:*` is the name of the *times*
+  # function:
   #
-  # The return value from `inject` is the return value from the last block call.
+  #     product = [ 2, 3, 4 ].inject(:*)
+  #     product # => 24
   #
-  # This call to `inject` gives a block that writes the memo and element, and also
-  # sums the elements:
+  # String concatenation again:
   #
-  #     (1..4).inject do |memo, element|
-  #       p "Memo: #{memo}; element: #{element}"
-  #       memo + element
-  #     end # => 10
+  #     s = [ "cat", " ", "dog" ].inject(:+)
+  #     s #=> "cat dog"
   #
-  # Output:
+  # And an example that converts a hash to an array of two-element subarrays.
   #
-  #     "Memo: 1; element: 2"
-  #     "Memo: 3; element: 3"
-  #     "Memo: 6; element: 4"
+  #     nested = {foo: 0, bar: 1}.inject([], :push)
+  #     nested # => [[:foo, 0], [:bar, 1]]
   #
   alias reduce inject
 
@@ -1850,30 +1840,47 @@ module Enumerable[unchecked out Elem] : _Each[Elem]
 
   # <!--
   #   rdoc-file=enum.c
-  #   - tally -> new_hash
-  #   - tally(hash) -> hash
+  #   - tally(hash = {}) -> hash
   # -->
-  # Returns a hash containing the counts of equal elements:
+  # When argument `hash` is not given, returns a new hash whose keys are the
+  # distinct elements in `self`; each integer value is the count of occurrences of
+  # each element:
   #
-  # *   Each key is an element of `self`.
-  # *   Each value is the number elements equal to that key.
+  #     %w[a b c b c a c b].tally # => {"a"=>2, "b"=>3, "c"=>3}
   #
+  # When argument `hash` is given, returns `hash`, possibly augmented; for each
+  # element `ele` in `self`:
   #
-  # With no argument:
+  # *   Adds it as a key with a zero value if that key does not already exist:
   #
-  #     %w[a b c b c a c b].tally # => {"a"=>2, "b"=>3, "c"=>3}
+  #         hash[ele] = 0 unless hash.include?(ele)
+  #
+  # *   Increments the value of key `ele`:
+  #
+  #         hash[ele] += 1
   #
-  # With a hash argument, that hash is used for the tally (instead of a new hash),
-  # and is returned; this may be useful for accumulating tallies across multiple
-  # enumerables:
+  # This is useful for accumulating tallies across multiple enumerables:
   #
-  #     hash = {}
-  #     hash = %w[a c d b c a].tally(hash)
-  #     hash # => {"a"=>2, "c"=>2, "d"=>1, "b"=>1}
-  #     hash = %w[b a z].tally(hash)
-  #     hash # => {"a"=>3, "c"=>2, "d"=>1, "b"=>2, "z"=>1}
-  #     hash = %w[b a m].tally(hash)
-  #     hash # => {"a"=>4, "c"=>2, "d"=>1, "b"=>3, "z"=>1, "m"=> 1}
+  #     h = {}                   # => {}
+  #     %w[a c d b c a].tally(h) # => {"a"=>2, "c"=>2, "d"=>1, "b"=>1}
+  #     %w[b a z].tally(h)       # => {"a"=>3, "c"=>2, "d"=>1, "b"=>2, "z"=>1}
+  #     %w[b a m].tally(h)       # => {"a"=>4, "c"=>2, "d"=>1, "b"=>3, "z"=>1, "m"=>1}
+  #
+  # The key to be added or found for an element depends on the class of `self`;
+  # see [Enumerable in Ruby
+  # Classes](rdoc-ref:Enumerable@Enumerable+in+Ruby+Classes).
+  #
+  # Examples:
+  #
+  # *   Array (and certain array-like classes): the key is the element (as above).
+  # *   Hash (and certain hash-like classes): the key is the 2-element array
+  #     formed from the key-value pair:
+  #
+  #         h = {}                        # => {}
+  #         {foo: 'a', bar: 'b'}.tally(h) # => {[:foo, "a"]=>1, [:bar, "b"]=>1}
+  #         {foo: 'c', bar: 'd'}.tally(h) # => {[:foo, "a"]=>1, [:bar, "b"]=>1, [:foo, "c"]=>1, [:bar, "d"]=>1}
+  #         {foo: 'a', bar: 'b'}.tally(h) # => {[:foo, "a"]=>2, [:bar, "b"]=>2, [:foo, "c"]=>1, [:bar, "d"]=>1}
+  #         {foo: 'c', bar: 'd'}.tally(h) # => {[:foo, "a"]=>2, [:bar, "b"]=>2, [:foo, "c"]=>2, [:bar, "d"]=>2}
   #
   def tally: (?Hash[Elem, Integer] hash) -> ::Hash[Elem, Integer]
 
@@ -1928,7 +1935,6 @@ module Enumerable[unchecked out Elem] : _Each[Elem]
   # *   The `n`-th element of self.
   # *   The `n`-th element of each of the `other_enums`.
   #
-  #
   # If all `other_enums` and self are the same size, all elements are included in
   # the result, and there is no `nil`-filling:
   #
@@ -1997,7 +2003,6 @@ module Enumerable[unchecked out Elem] : _Each[Elem]
   #     returned, and all following elements for which the block returned the same
   #     value:
   #
-  #
   # So that:
   #
   # *   Each block return value that is different from its predecessor begins a
@@ -2005,7 +2010,6 @@ module Enumerable[unchecked out Elem] : _Each[Elem]
   # *   Each block return value that is the same as its predecessor continues the
   #     same chunk.
   #
-  #
   # Example:
   #
   #     e = (0..10).chunk {|i| (i / 3).floor } # => #<Enumerator: ...>