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:

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.

5 KiB Vendored Raw Blame History