From c7ffb0cc55ff131fd49468ea449b9c8d9cc765ce Mon Sep 17 00:00:00 2001 From: "Yukihiro \"Matz\" Matsumoto" Date: Sat, 7 Jun 2025 11:46:11 +0900 Subject: [PATCH] mruby-array-ext: add README.md The document is written by Google Jules. --- mrbgems/mruby-array-ext/README.md | 87 +++++++++++++++++++++++++++++++ 1 file changed, 87 insertions(+) create mode 100644 mrbgems/mruby-array-ext/README.md diff --git a/mrbgems/mruby-array-ext/README.md b/mrbgems/mruby-array-ext/README.md new file mode 100644 index 000000000..d56501810 --- /dev/null +++ b/mrbgems/mruby-array-ext/README.md @@ -0,0 +1,87 @@ +# mruby-array-ext + +This mrbgem extends the `Array` class in mruby, providing a rich set of additional methods for array manipulation. These extensions enhance mruby's built-in array capabilities, offering functionalities commonly found in standard Ruby. + +## Functionality + +The `mruby-array-ext` gem adds the following methods to the `Array` class: + +### Set Operations + +- `uniq`: Returns a new array by removing duplicate values. +- `uniq!`: Removes duplicate elements from self. Returns `nil` if no changes are made. +- `-` (difference): Returns a new array that is a copy of the original array, removing any items that also appear in another array. +- `|` (union): Returns a new array by joining this array with another array, removing duplicates. +- `&` (intersection): Returns a new array containing elements common to two arrays, with no duplicates. +- `difference`: Returns a new array that is a copy of the original array, removing all occurrences of any item that also appear in the specified other arrays. +- `union`: Returns a new array by joining this array with other arrays, removing duplicates. +- `intersection`: Returns a new array containing elements common to this array and specified other arrays, removing duplicates. +- `intersect?`: Returns `true` if the array and another array have at least one element in common. + +### Element Manipulation and Access + +- `flatten`: Returns a new array that is a one-dimensional flattening of self. +- `flatten!`: Flattens self in place. Returns `nil` if no modifications were made. +- `fetch`: Tries to return the element at a given position. Throws an `IndexError` if the index is out of bounds, unless a default value or block is provided. +- `fill`: Sets selected elements of self to a given object or the result of a block. +- `compact`: Returns a copy of self with all `nil` elements removed. +- `compact!`: Removes `nil` elements from self. Returns `nil` if no changes were made. +- `rotate(count=1)`: Returns a new array by rotating self so that the element at `count` is the first element. +- `rotate!(count=1)`: Rotates self in place. +- `insert(index, obj...)`: Inserts the given values before the element with the given index. +- `slice!(index)` / `slice!(start, length)` / `slice!(range)`: Deletes element(s) given by an index or range and returns the deleted object(s). +- `at(index)`: Returns the element at `index`. Returns `nil` if the index is out of range. +- `dig(idx, ...)`: Extracts a nested value specified by a sequence of indices. +- `fetch_values(idx, ...)`: Returns an array containing the values associated with the given indexes. Raises `IndexError` if an index is not found, unless a block is provided. +- `values_at(selector, ...)`: Returns an array containing the elements corresponding to the given selector(s). + +### Searching and Comparison + +- `assoc(obj)`: Searches through an array of arrays, comparing `obj` with the first element of each contained array. Returns the first matching contained array or `nil`. +- `rassoc(obj)`: Searches through an array of arrays, comparing `obj` with the second element of each contained array. Returns the first matching contained array or `nil`. +- `bsearch { |x| block }`: Finds a value from the array which meets the given condition using binary search. +- `bsearch_index { |x| block }`: Finds the index of a value from the array which meets the given condition using binary search. + +### Iterators and Combinatorics + +- `reverse_each`: Calls the given block for each element in reverse order. +- `permutation(n=self.size)`: Yields all permutations of length `n` of the elements of the array. +- `combination(n)`: Yields all combinations of length `n` of elements from the array. +- `product(*arys)`: Returns an array of all combinations of elements from self and the given arrays. +- `repeated_combination(n)`: Yields all repeated combinations of length `n`. +- `repeated_permutation(n)`: Yields all repeated permutations of length `n`. + +### Conversions and Other Utilities + +- `to_h`: Returns the result of interpreting the array as an array of `[key, value]` pairs. +- `transpose`: Assumes that self is an array of arrays and transposes the rows and columns. + +### Filtering + +- `delete_if { |item| block }`: Deletes every element of self for which the block evaluates to `true`. +- `reject! { |item| block }`: Equivalent to `delete_if`, but returns `nil` if no changes were made. +- `keep_if { |item| block }`: Deletes every element of self for which the given block evaluates to `false`. +- `select! { |item| block }`: Deletes elements for which the block returns a `false` value. Returns `self` if changes were made, otherwise `nil`. + +### Aliases + +- `append` (alias for `push`) +- `prepend` (alias for `unshift`) +- `filter!` (alias for `select!`) + +## Usage + +To use this gem, add it to your `build_config.rb` or `mrbgem.rake` file. For detailed examples of each method, please refer to the comments in the source code (`mrblib/array.rb` and `src/array.c`). + +Example: + +```ruby +a = [1, 2, 2, 3, nil, 4] +p a.compact #=> [1, 2, 2, 3, 4] +p a.uniq #=> [1, 2, 3, nil, 4] + +b = ["a", "b", "c"] +p b.rotate #=> ["b", "c", "a"] +``` + +This gem is part of the mruby project.