From f835b86d106499d6f4ce475483c26b3ff8be23bc Mon Sep 17 00:00:00 2001
From: "Yukihiro \"Matz\" Matsumoto" <matz@ruby.or.jp>
Date: Sat, 7 Jun 2025 11:53:04 +0900
Subject: [PATCH] mruby-enum-ext: add README.md

The document is written by Google Jules.
---
 mrbgems/mruby-enum-ext/README.md | 487 +++++++++++++++++++++++++++++++
 1 file changed, 487 insertions(+)
 create mode 100644 mrbgems/mruby-enum-ext/README.md

diff --git a/mrbgems/mruby-enum-ext/README.md b/mrbgems/mruby-enum-ext/README.md
new file mode 100644
index 000000000..a49b3bc86
--- /dev/null
+++ b/mrbgems/mruby-enum-ext/README.md
@@ -0,0 +1,487 @@
+# mruby-enum-ext
+
+This mrbgem extends the `Enumerable` module in mruby with additional useful methods.
+
+## Added Methods
+
+Below is a list of methods added to the `Enumerable` module, along with a brief description and example for each.
+
+---
+
+### `drop(n)`
+
+Drops the first `n` elements from an enumerable and returns the rest of the elements in an array.
+
+_Example:_
+
+```ruby
+a = [1, 2, 3, 4, 5, 0]
+a.drop(3)             #=> [4, 5, 0]
+```
+
+---
+
+### `drop_while { |obj| block }`
+
+Drops elements up to, but not including, the first element for which the block returns `nil` or `false`. Returns an array containing the remaining elements. If no block is given, an enumerator is returned.
+
+_Example:_
+
+```ruby
+a = [1, 2, 3, 4, 5, 0]
+a.drop_while {|i| i < 3 }   #=> [3, 4, 5, 0]
+```
+
+---
+
+### `take(n)`
+
+Returns the first `n` elements from an enumerable as an array.
+
+_Example:_
+
+```ruby
+a = [1, 2, 3, 4, 5, 0]
+a.take(3)             #=> [1, 2, 3]
+```
+
+---
+
+### `take_while { |obj| block }`
+
+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.
+
+_Example:_
+
+```ruby
+a = [1, 2, 3, 4, 5, 0]
+a.take_while {|i| i < 3 }   #=> [1, 2]
+```
+
+---
+
+### `each_cons(n) { |a| block }`
+
+Iterates the given block for each array of consecutive `n` elements. If no block is given, an enumerator is returned.
+
+_Example:_
+
+```ruby
+(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]
+```
+
+---
+
+### `each_slice(n) { |a| block }`
+
+Iterates the given block for each slice of `n` elements. If no block is given, an enumerator is returned.
+
+_Example:_
+
+```ruby
+(1..10).each_slice(3) {|a| p a}
+# outputs below
+# [1, 2, 3]
+# [4, 5, 6]
+# [7, 8, 9]
+# [10]
+```
+
+---
+
+### `group_by { |obj| block }`
+
+Groups the collection by the result of the block. Returns a hash where keys are the evaluated result from the block and values are arrays of elements corresponding to the key. If no block is given, an enumerator is returned.
+
+_Example:_
+
+```ruby
+(1..6).group_by {|i| i%3}   #=> {0=>[3, 6], 1=>[1, 4], 2=>[2, 5]}
+```
+
+---
+
+### `sort_by { |obj| block }`
+
+Sorts the enumerable using a set of keys generated by mapping the values in the enumerable through the given block. Returns an array. If no block is given, an enumerator is returned. (Note: `Array#sort_by` and `Array#sort_by!` are also implemented for optimized in-place sorting for arrays).
+
+_Example:_
+
+```ruby
+%w(apple pear fig).sort_by { |word| word.length }
+#=> ["fig", "pear", "apple"]
+```
+
+_(Example adapted, original was for `Array#sort_by`)_
+
+---
+
+### `first` / `first(n)`
+
+Returns the first element, or the first `n` elements, of the enumerable. If the enumerable is empty, `first` returns `nil`, and `first(n)` returns an empty array.
+
+_Examples:_
+
+```ruby
+a = [1, 2, 3, 4, 5]
+a.first         #=> 1
+a.first(3)      #=> [1, 2, 3]
+[].first        #=> nil
+[].first(3)     #=> []
+```
+
+---
+
+### `count` / `count(item)` / `count { |obj| block }`
+
+Returns the number of items in the enumerable.
+
+- If an argument `item` is given, counts items equal to `item`.
+- If a block is given, counts elements yielding a true value.
+- If no argument or block is given, counts all items.
+
+_Examples:_
+
+```ruby
+[1, 2, 3, 2].count           #=> 4
+[1, 2, 3, 2].count(2)        #=> 2
+[1, 2, 3, 4].count { |x| x%2 == 0 } #=> 2
+```
+
+---
+
+### `flat_map { |obj| block }` (alias: `collect_concat`)
+
+Returns a new array with the concatenated results of running the block once for every element. If no block is given, an enumerator is returned.
+
+_Example:_
+
+```ruby
+[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]
+```
+
+---
+
+### `max_by { |obj| block }`
+
+Returns the object in the enumerable that gives the maximum value from the given block. If no block is given, an enumerator is returned.
+
+_Example:_
+
+```ruby
+%w[albatross dog horse].max_by {|x| x.length }   #=> "albatross"
+```
+
+---
+
+### `min_by { |obj| block }`
+
+Returns the object in the enumerable that gives the minimum value from the given block. If no block is given, an enumerator is returned.
+
+_Example:_
+
+```ruby
+%w[albatross dog horse].min_by {|x| x.length }   #=> "dog"
+```
+
+---
+
+### `minmax` / `minmax { |a, b| block }`
+
+Returns a two-element array containing the minimum and maximum values. The first form assumes objects implement `Comparable`; the second uses the block to return `a <=> b`.
+
+_Examples:_
+
+```ruby
+a = %w(albatross dog horse)
+a.minmax                                  #=> ["albatross", "horse"]
+a.minmax { |a, b| a.length <=> b.length } #=> ["dog", "albatross"]
+```
+
+---
+
+### `minmax_by { |obj| block }`
+
+Returns a two-element array containing the objects that correspond to the minimum and maximum values from the given block. If no block is given, an enumerator is returned.
+
+_Example:_
+
+```ruby
+%w(albatross dog horse).minmax_by { |x| x.length }   #=> ["dog", "albatross"]
+```
+
+---
+
+### `none?` / `none? { |obj| block }` / `none?(pattern)`
+
+- With a block: Returns `true` if the block never returns `true` for any element.
+- With a pattern: Returns `true` if `pattern === element` is never true for any element.
+- With no argument or block: Returns `true` if none of the collection members are truthy.
+
+_Examples:_
+
+```ruby
+%w(ant bear cat).none? { |word| word.length == 5 } #=> true
+%w(ant bear cat).none? { |word| word.length >= 4 } #=> false
+%w{ant bear cat}.none?(/d/)                        #=> true
+[1, 3.14, 42].none?(Float)                         #=> false
+[].none?                                           #=> true
+[nil, false].none?                                 #=> true
+```
+
+---
+
+### `one?` / `one? { |obj| block }` / `one?(pattern)`
+
+- With a block: Returns `true` if the block returns `true` exactly once.
+- With a pattern: Returns `true` if `pattern === element` is true for exactly one element.
+- With no argument or block: Returns `true` if exactly one of the collection members is truthy.
+
+_Examples:_
+
+```ruby
+%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?(/t/)                         #=> false # (Note: original example might be specific to mruby version, "ant" and "cat" contain "t")
+[nil, true, false].one?                            #=> true
+[nil, true, 99].one?(Integer)                      #=> true
+```
+
+---
+
+### `all?` / `all? { |obj| block }` / `all?(pattern)`
+
+- With a block: Returns `true` if the block never returns `false` or `nil` for any element.
+- With a pattern: Returns `true` if `pattern === element` is true for every element.
+- With no argument or block: Returns `true` if all collection members are truthy.
+
+_Examples:_
+
+```ruby
+%w[ant bear cat].all? { |word| word.length >= 3 } #=> true
+%w[ant bear cat].all? { |word| word.length >= 4 } #=> false
+[1, 2i, 3.14].all?(Numeric)                       #=> true
+[nil, true, 99].all?                              #=> false
+```
+
+---
+
+### `any?` / `any? { |obj| block }` / `any?(pattern)`
+
+- With a block: Returns `true` if the block ever returns a truthy value for an element.
+- With a pattern: Returns `true` if `pattern === element` is true for any element.
+- With no argument or block: Returns `true` if at least one collection member is truthy.
+
+_Examples:_
+
+```ruby
+%w[ant bear cat].any? { |word| word.length >= 3 } #=> true
+%w[ant bear cat].any?(/d/)                        #=> false
+[nil, true, 99].any?(Integer)                     #=> true
+[nil, true, 99].any?                              #=> true
+[].any?                                           #=> false
+```
+
+---
+
+### `each_with_object(obj) { |(*args), memo_obj| ... }`
+
+Iterates the given block for each element with an arbitrary object `obj` given, and returns the initially given `obj`. If no block is given, an enumerator is returned.
+
+_Example:_
+
+```ruby
+(1..10).each_with_object([]) { |i, a| a << i*2 }
+#=> [2, 4, 6, 8, 10, 12, 14, 16, 18, 20]
+```
+
+---
+
+### `reverse_each { |item| block }`
+
+Builds a temporary array and traverses that array in reverse order, executing the block for each item. If no block is given, an enumerator is returned.
+
+_Example:_
+
+```ruby
+(1..3).reverse_each { |v| p v }
+# produces:
+# 3
+# 2
+# 1
+```
+
+---
+
+### `cycle(n=nil) { |obj| block }`
+
+Calls the block for each element repeatedly `n` times, or forever if `n` is `nil`. If `n` is non-positive or the collection is empty, does nothing. Returns `nil` if the loop finishes. If no block is given, an enumerator is returned.
+
+_Examples:_
+
+```ruby
+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.
+```
+
+---
+
+### `find_index(value)` / `find_index { |obj| block }`
+
+Compares each entry with `value` or passes to `block`. Returns the index for the first non-false evaluation. If no object matches, returns `nil`. If no argument or block is given, an enumerator is returned.
+
+_Examples:_
+
+```ruby
+(1..100).find_index { |i| i % 5 == 0 and i % 7 == 0 }  #=> 34
+(1..100).find_index(50)                                #=> 49
+```
+
+---
+
+### `zip(arg, ...) { |arr| block }`
+
+Takes one element from the enumerable and merges corresponding elements from each `arg`. Generates a sequence of n-element arrays. The length will be `enum#size`. If any argument is shorter, `nil` values are supplied. If a block is given, it's invoked for each output array; otherwise, an array of arrays is returned.
+
+_Examples:_
+
+```ruby
+a = [ 4, 5, 6 ]
+b = [ 7, 8, 9 ]
+a.zip(b)                 #=> [[4, 7], [5, 8], [6, 9]]
+[1, 2].zip(a, b)         #=> [[1, 4, 7], [2, 5, 8]]
+c = []
+a.zip(b) { |x, y| c << x + y }  #=> nil
+c                               #=> [11, 13, 15]
+```
+
+---
+
+### `to_h { |element| block }`
+
+Returns a hash by interpreting the enumerable as a list of `[key, value]` pairs. If a block is given, it's used to transform elements before they are converted into pairs.
+
+_Example:_
+
+```ruby
+%i[hello world].each_with_index.to_h
+  # => {:hello => 0, :world => 1}
+
+# With a block (example assumes a suitable block)
+# (0..3).to_h {|x| [x, x*x] } # => {0=>0, 1=>1, 2=>4, 3=>9} (Conceptual example)
+```
+
+_(The `to_h` method in the source is a bit complex with its block handling; the example is simplified.)_
+
+---
+
+### `uniq { |item| block }`
+
+Returns a new array by removing duplicate values. If a block is given, it will use the return value of the block for uniqueness comparison.
+
+_Examples:_
+
+```ruby
+[1, 2, 2, 3, 1].uniq             #=> [1, 2, 3]
+["a", "B", "c", "b"].uniq { |s| s.downcase } #=> ["a", "B", "c"]
+```
+
+---
+
+### `filter_map { |obj| block }`
+
+Returns a new array containing the truthy results of running the block for every element. If no block is given, an enumerator is returned.
+
+_Example:_
+
+```ruby
+[-2, -1, 0, 1, 2].filter_map { |x| x*2 if x > 0 } #=> [2, 4]
+```
+
+---
+
+### `grep_v(pattern) { |obj| block }`
+
+Returns an array of elements that do NOT match the `pattern`. If a block is given, the elements of the result are passed to the block and the block's results are returned.
+
+_Example:_
+
+```ruby
+a = ["apple", "banana", "orange", "grape"]
+a.grep_v(/an/)                   #=> ["apple", "orange", "grape"]
+a.grep_v(/an/) { |s| s.upcase } #=> ["APPLE", "ORANGE", "GRAPE"]
+```
+
+---
+
+### `tally`
+
+Tallies the collection. Returns a hash where keys are elements and values are their counts.
+
+_Example:_
+
+```ruby
+["a", "b", "c", "b"].tally #=> {"a"=>1, "b"=>2, "c"=>1}
+```
+
+---
+
+### `sum(initial=0) { |obj| block }`
+
+Returns the sum of elements. If a block is given, each element is processed by the block before addition. `initial` is the starting value for the sum.
+
+_Examples:_
+
+```ruby
+[1, 2, 3].sum                #=> 6
+[1, 2, 3].sum(10)            #=> 16
+[1, 2, 3].sum { |x| x * 2 }  #=> 12
+({a:1, b:2, c:3}).sum {|k,v| v} #=> 6 (Example from Ruby docs, assuming similar behavior)
+```
+
+---
+
+### `each_entry(*args) { |obj| block }`
+
+Calls block once for each element, passing that element as a parameter (converting multiple values from yield to an array). If no block is given, an enumerator is returned.
+
+_Example:_
+
+```ruby
+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
+```
+
+---
+
+**Note on `Array#sort_by` and `Array#sort_by!`**
+
+The gem also provides optimized `sort_by` and `sort_by!` methods directly on the `Array` class. `sort_by!` sorts the array in place.
+
+```ruby
+arr = ["apple", "pear", "fig"]
+arr.sort_by! { |word| word.length }
+p arr #=> ["fig", "pear", "apple"]
+```