Class: Array

Relationships & Source Files
Super Chains via Extension / Inclusion / Inheritance
Instance Chain: self, `::Enumerable`
Inherits:	Object
Defined in:	pack.rb, array.c

Overview

Arrays are ordered, integer-indexed collections of any object.

Array indexing starts at 0, as in C or Java. A negative index is assumed to be relative to the end of the array—that is, an index of -1 indicates the last element of the array, -2 is the next to last element in the array, and so on.

Creating Arrays

A new array can be created by using the literal constructor .[]. Arrays can contain different types of objects. For example, the array below contains an ::Integer, a ::String and a ::Float:

ary = [1, "two", 3.0] #=> [1, "two", 3.0]

An array can also be created by explicitly calling .new with zero, one (the initial size of the Array) or two arguments (the initial size and a default object).

ary = Array.new    #=> []
Array.new(3)       #=> [nil, nil, nil]
Array.new(3, true) #=> [true, true, true]

Note that the second argument populates the array with references to the same object. Therefore, it is only recommended in cases when you need to instantiate arrays with natively immutable objects such as Symbols, numbers, true or false.

To create an array with separate objects a block can be passed instead. This method is safe to use with mutable objects such as hashes, strings or other arrays:

Array.new(4) {Hash.new}    #=> [{}, {}, {}, {}]
Array.new(4) {|i| i.to_s } #=> ["0", "1", "2", "3"]

This is also a quick way to build up multi-dimensional arrays:

empty_table = Array.new(3) {Array.new(3)}
#=> [[nil, nil, nil], [nil, nil, nil], [nil, nil, nil]]

An array can also be created by using the Array() method, provided by ::Kernel, which tries to call #to_ary, then #to_a on its argument.

Array({:a => "a", :b => "b"}) #=> [[:a, "a"], [:b, "b"]]

Example Usage

In addition to the methods it mixes in through the ::Enumerable module, the Array class has proprietary methods for accessing, searching and otherwise manipulating arrays.

Some of the more common ones are illustrated below.

Accessing Elements

Elements in an array can be retrieved using the #[] method. It can take a single integer argument (a numeric index), a pair of arguments (start and length) or a range. Negative indices start counting from the end, with -1 being the last element.

arr = [1, 2, 3, 4, 5, 6]
arr[2]    #=> 3
arr[100]  #=> nil
arr[-3]   #=> 4
arr[2, 3] #=> [3, 4, 5]
arr[1..4] #=> [2, 3, 4, 5]
arr[1..-3] #=> [2, 3, 4]

Another way to access a particular array element is by using the #at method

arr.at(0) #=> 1

The #slice method works in an identical manner to #[].

To raise an error for indices outside of the array bounds or else to provide a default value when that happens, you can use #fetch.

arr = ['a', 'b', 'c', 'd', 'e', 'f']
arr.fetch(100) #=> IndexError: index 100 outside of array bounds: -6...6
arr.fetch(100, "oops") #=> "oops"

The special methods #first and #last will return the first and last elements of an array, respectively.

arr.first #=> 1
arr.last  #=> 6

To return the first n elements of an array, use #take

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

#drop does the opposite of #take, by returning the elements after n elements have been dropped:

arr.drop(3) #=> [4, 5, 6]

Obtaining Information about an Array

Arrays keep track of their own length at all times. To query an array about the number of elements it contains, use #length, #count or #size.

browsers = ['Chrome', 'Firefox', 'Safari', 'Opera', 'IE']
browsers.length #=> 5
browsers.count #=> 5

To check whether an array contains any elements at all

browsers.empty? #=> false

To check whether a particular item is included in the array

browsers.include?('Konqueror') #=> false

Adding Items to Arrays

Items can be added to the end of an array by using either #push or #<<

arr = [1, 2, 3, 4]
arr.push(5) #=> [1, 2, 3, 4, 5]
arr << 6    #=> [1, 2, 3, 4, 5, 6]

#unshift will add a new item to the beginning of an array.

arr.unshift(0) #=> [0, 1, 2, 3, 4, 5, 6]

With #insert you can add a new element to an array at any position.

arr.insert(3, 'apple')  #=> [0, 1, 2, 'apple', 3, 4, 5, 6]

Using the #insert method, you can also insert multiple values at once:

arr.insert(3, 'orange', 'pear', 'grapefruit')
#=> [0, 1, 2, "orange", "pear", "grapefruit", "apple", 3, 4, 5, 6]

Removing Items from an Array

The method #pop removes the last element in an array and returns it:

arr =  [1, 2, 3, 4, 5, 6]
arr.pop #=> 6
arr #=> [1, 2, 3, 4, 5]

To retrieve and at the same time remove the first item, use #shift:

arr.shift #=> 1
arr #=> [2, 3, 4, 5]

To delete an element at a particular index:

arr.delete_at(2) #=> 4
arr #=> [2, 3, 5]

To delete a particular element anywhere in an array, use #delete:

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

A useful method if you need to remove nil values from an array is #compact:

arr = ['foo', 0, nil, 'bar', 7, 'baz', nil]
arr.compact  #=> ['foo', 0, 'bar', 7, 'baz']
arr          #=> ['foo', 0, nil, 'bar', 7, 'baz', nil]
arr.compact! #=> ['foo', 0, 'bar', 7, 'baz']
arr          #=> ['foo', 0, 'bar', 7, 'baz']

Another common need is to remove duplicate elements from an array.

It has the non-destructive #uniq, and destructive method #uniq!

arr = [2, 5, 6, 556, 6, 6, 8, 9, 0, 123, 556]
arr.uniq #=> [2, 5, 6, 556, 8, 9, 0, 123]

Iterating over Arrays

Like all classes that include the ::Enumerable module, Array has an each method, which defines what elements should be iterated over and how. In case of Array’s #each, all elements in the Array instance are yielded to the supplied block in sequence.

Note that this operation leaves the array unchanged.

arr = [1, 2, 3, 4, 5]
arr.each {|a| print a -= 10, " "}
# prints: -9 -8 -7 -6 -5
#=> [1, 2, 3, 4, 5]

Another sometimes useful iterator is #reverse_each which will iterate over the elements in the array in reverse order.

words = %w[first second third fourth fifth sixth]
str = ""
words.reverse_each {|word| str += "#{word} "}
p str #=> "sixth fifth fourth third second first "

The #map method can be used to create a new array based on the original array, but with the values modified by the supplied block:

arr.map {|a| 2*a}     #=> [2, 4, 6, 8, 10]
arr                   #=> [1, 2, 3, 4, 5]
arr.map! {|a| a**2}   #=> [1, 4, 9, 16, 25]
arr                   #=> [1, 4, 9, 16, 25]

Selecting Items from an Array

Elements can be selected from an array according to criteria defined in a block. The selection can happen in a destructive or a non-destructive manner. While the destructive operations will modify the array they were called on, the non-destructive methods usually return a new array with the selected elements, but leave the original array unchanged.

Non-destructive Selection

arr = [1, 2, 3, 4, 5, 6]
arr.select {|a| a > 3}       #=> [4, 5, 6]
arr.reject {|a| a < 3}       #=> [3, 4, 5, 6]
arr.drop_while {|a| a < 4}   #=> [4, 5, 6]
arr                          #=> [1, 2, 3, 4, 5, 6]

Destructive Selection

#select! and #reject! are the corresponding destructive methods to #select and #reject

Similar to #select vs. #reject, #delete_if and #keep_if have the exact opposite result when supplied with the same block:

arr.delete_if {|a| a < 4}   #=> [4, 5, 6]
arr                         #=> [4, 5, 6]

arr = [1, 2, 3, 4, 5, 6]
arr.keep_if {|a| a < 4}   #=> [1, 2, 3]
arr                       #=> [1, 2, 3]

Class Method Summary

.[](*args)

Returns a new array populated with the given objects.
.new(size = 0, default = nil) constructor

Returns a new array.
.try_convert(obj) ⇒ Array^?

Tries to convert obj into an array, using the #to_ary method.

Instance Attribute Summary

#empty? ⇒ Boolean readonly

Returns true if self contains no elements.

Instance Method Summary

#&(other_ary) ⇒ Array

Set Intersection — Returns a new array containing unique elements common to the two arrays.
#*(int) ⇒ Array

Repetition — With a ::String argument, equivalent to ary.join(str).
#+(other_ary) ⇒ Array

Concatenation — Returns a new array built by concatenating the two arrays together to produce a third array.
#-(other_ary) ⇒ Array

Array Difference.
#<<(obj) ⇒ Array

Append—Pushes the given object on to the end of this array.
#<=>(other_ary) ⇒ 1, ...

Comparison — Returns an integer (-1, 0, or +1) if this array is less than, equal to, or greater than other_ary.
#==(other_ary) ⇒ Boolean

Equality — Two arrays are equal if they contain the same number of elements and if each element is equal to (according to Object#==) the corresponding element in other_ary.
#[](index) ⇒ Object^? (also: #slice)

Element Reference — Returns the element at #index, or returns a subarray starting at the start index and continuing for #length elements, or returns a subarray specified by range of indices.
#[]=(index, obj) ⇒ Object

Element Assignment — Sets the element at #index, or replaces a subarray from the start index for #length elements, or replaces a subarray specified by the range of indices.
#all? {|obj| ... } ⇒ Boolean

See also Enumerable#all?
#any? {|obj| ... } ⇒ Boolean

See also Enumerable#any?
#append(obj, ...) ⇒ Array

Alias for #push.
#assoc(obj) ⇒ element_ary^?

Searches through an array whose elements are also arrays comparing obj with the first element of each contained array using obj.==.
#at(index) ⇒ Object^?

Returns the element at #index.
#bsearch {|x| ... } ⇒ elem

By using binary search, finds a value from this array which meets the given condition in O(log n) where n is the size of the array.
#bsearch_index {|x| ... } ⇒ Integer^?

By using binary search, finds an index of a value from this array which meets the given condition in O(log n) where n is the size of the array.
#clear ⇒ Array

Removes all elements from self.
#collect {|item| ... } ⇒ Array

Alias for #map.
#collect! {|item| ... } ⇒ Array

Alias for #map!.
#combination(n) {|c| ... } ⇒ Array

When invoked with a block, yields all combinations of length n of elements from the array and then returns the array itself.
#compact ⇒ Array

Returns a copy of self with all nil elements removed.
#compact! ⇒ Array^?

Removes nil elements from the array.
#concat(other_ary1, other_ary2, ...) ⇒ Array

Appends the elements of other_arys to self.
#count ⇒ Integer

Returns the number of elements.
#cycle(n = nil) {|obj| ... } ⇒ nil

Calls the given block for each element n times or forever if nil is given.
#deconstruct
#delete(obj) ⇒ item^?

Deletes all items from self that are equal to obj.
#delete_at(index) ⇒ Object^?

Deletes the element at the specified #index, returning that element, or nil if the #index is out of range.
#delete_if {|item| ... } ⇒ Array

Deletes every element of self for which block evaluates to true.
#difference(other_ary1, other_ary2, ...) ⇒ Array

Array Difference.
#dig(idx, ...) ⇒ Object

Extracts the nested value specified by the sequence of idx objects by calling dig at each step, returning nil if any intermediate step is nil.
#drop(n) ⇒ Array

Drops first n elements from ary and returns the rest of the elements in an array.
#drop_while {|obj| ... } ⇒ Array

Drops elements up to, but not including, the first element for which the block returns nil or false and returns an array containing the remaining elements.
#each {|item| ... } ⇒ Array

Calls the given block once for each element in self, passing that element as a parameter.
#each_index {|index| ... } ⇒ Array

Same as #each, but passes the #index of the element instead of the element itself.
#eql?(other) ⇒ Boolean

Returns true if self and other are the same object, or are both arrays with the same content (according to Object#eql?).
#fetch(index) ⇒ Object

Tries to return the element at position #index, but throws an ::IndexError exception if the referenced #index lies outside of the array bounds.
#fill(obj) ⇒ Array

The first three forms set the selected elements of self (which may be the entire array) to obj.
#filter {|item| ... } ⇒ Array (also: #select)

Returns a new array containing all elements of ary for which the given block returns a true value.
#filter! {|item| ... } ⇒ Array^? (also: #select!)

Invokes the given block passing in successive elements from self, deleting elements for which the block returns a false value.
#find_index(obj) ⇒ Integer^?

Alias for #index.
#first ⇒ Object^?

Returns the first element, or the first n elements, of the array.
#flatten ⇒ Array

Returns a new array that is a one-dimensional flattening of self (recursively).
#flatten! ⇒ Array^?

Flattens self in place.
#hash ⇒ Integer

Compute a hash-code for this array.
#include?(object) ⇒ Boolean

Returns true if the given object is present in self (that is, if any element #== object), otherwise returns false.
#index(obj) ⇒ Integer^? (also: #find_index)

Returns the index of the first object in ary such that the object is #== to obj.
#initialize_copy(other_ary) ⇒ Array

Alias for #replace.
#insert(index, obj...) ⇒ Array

Inserts the given values before the element with the given #index.
#inspect ⇒ String

Alias for #to_s.
#intersection(other_ary1, other_ary2, ...) ⇒ Array

Set Intersection — Returns a new array containing unique elements common to self and other_arys.
#join(separator = $,) ⇒ String

Returns a string created by converting each element of the array to a string, separated by the given separator.
#keep_if {|item| ... } ⇒ Array

Deletes every element of self for which the given block evaluates to false, and returns self.
#last ⇒ Object^?

Returns the last element(s) of self.
#length ⇒ Integer (also: #size)

Returns the number of elements in self.
#map {|item| ... } ⇒ Array (also: #collect)

Invokes the given block once for each element of self.
#map! {|item| ... } ⇒ Array (also: #collect!)

Invokes the given block once for each element of self, replacing the element with the value returned by the block.
#max ⇒ Object

Returns the object in ary with the maximum value.
#min ⇒ Object

Returns the object in ary with the minimum value.
#minmax ⇒ Array, Object

Returns a two element array which contains the minimum and the maximum value in the array.
#none? {|obj| ... } ⇒ Boolean

See also Enumerable#none?
#one? {|obj| ... } ⇒ Boolean

See also Enumerable#one?
#pack(aTemplateString) ⇒ aBinaryString

Packs the contents of arr into a binary sequence according to the directives in aTemplateString (see the table below) Directives “A,” “a,” and “Z” may be followed by a count, which gives the width of the resulting field.
#permutation {|p| ... } ⇒ Array

When invoked with a block, yield all permutations of length n of the elements of the array, then return the array itself.
#pop ⇒ Object^?

Removes the last element from self and returns it, or nil if the array is empty.
#prepend(obj, ...) ⇒ Array (also: #unshift)

Prepends objects to the front of self, moving other elements upwards.
#product(other_ary, ...) ⇒ Array

Returns an array of all combinations of elements from all arrays.
#push(obj, ...) ⇒ Array (also: #append)

Append — Pushes the given object(s) on to the end of this array.
#rassoc(obj) ⇒ element_ary^?

Searches through the array whose elements are also arrays.
#reject {|item| ... } ⇒ Array

Returns a new array containing the items in self for which the given block is not true.
#reject! {|item| ... } ⇒ Array^?

Deletes every element of self for which the block evaluates to true, if no changes were made returns nil.
#repeated_combination(n) {|c| ... } ⇒ Array

When invoked with a block, yields all repeated combinations of length n of elements from the array and then returns the array itself.
#repeated_permutation(n) {|p| ... } ⇒ Array

When invoked with a block, yield all repeated permutations of length n of the elements of the array, then return the array itself.
#replace(other_ary) ⇒ Array (also: #initialize_copy)

Replaces the contents of self with the contents of other_ary, truncating or expanding if necessary.
#reverse ⇒ Array

Returns a new array containing self‘s elements in reverse order.
#reverse! ⇒ Array

Reverses self in place.
#reverse_each {|item| ... } ⇒ Array

Same as #each, but traverses self in reverse order.
#rindex(obj) ⇒ Integer^?

Returns the index of the last object in self #== to obj.
#rotate(count = 1) ⇒ Array

Returns a new array by rotating self so that the element at #count is the first element of the new array.
#rotate!(count = 1) ⇒ Array

Rotates self in place so that the element at #count comes first, and returns self.
#sample ⇒ Object

Choose a random element or n random elements from the array.
#select {|item| ... } ⇒ Array

Alias for #filter.
#select! {|item| ... } ⇒ Array^?

Alias for #filter!.
#shift ⇒ Object^?

Removes the first element of self and returns it (shifting all other elements down by one).
#shuffle ⇒ Array

Returns a new array with elements of self shuffled.
#shuffle! ⇒ Array

Shuffles elements in self in place.
#size ⇒ Integer

Alias for #length.
#slice(index) ⇒ Object^?

Alias for #[].
#slice!(index) ⇒ Object^?

Deletes the element(s) given by an #index (optionally up to #length elements) or by a range.
#sort ⇒ Array

Returns a new array created by sorting self.
#sort! ⇒ Array

Sorts self in place.
#sort_by! {|obj| ... } ⇒ Array

Sorts self in place using a set of keys generated by mapping the values in self through the given block.
#sum(init = 0) ⇒ Numeric

Returns the sum of elements.
#take(n) ⇒ Array

Returns first n elements from the array.
#take_while {|obj| ... } ⇒ Array

Passes elements to the block until the block returns nil or false, then stops iterating and returns an array of all prior elements.
#to_a ⇒ Array

Returns self.
#to_ary ⇒ Array

Returns self.
#to_h ⇒ Hash

Returns the result of interpreting ary as an array of [key, value] pairs.
#to_s ⇒ String (also: #inspect)

Creates a string representation of self, by calling #inspect on each element.
#transpose ⇒ Array

Assumes that self is an array of arrays and transposes the rows and columns.
#union(other_ary1, other_ary2, ...) ⇒ Array

Set Union — Returns a new array by joining other_arys with self, excluding any duplicates and preserving the order from the given arrays.
#uniq ⇒ Array

Returns a new array by removing duplicate values in self.
#uniq! ⇒ Array^?

Removes duplicate elements from self.
#unshift(obj, ...) ⇒ Array

Alias for #prepend.
#values_at(selector, ...) ⇒ Array

Returns an array containing the elements in self corresponding to the given selector(s).
#zip(arg, ...) ⇒ Array

Converts any arguments to arrays, then merges elements of self with corresponding elements from each argument.
#|(other_ary) ⇒ Array

Set Union — Returns a new array by joining ary with other_ary, excluding any duplicates and preserving the order from the given arrays.

`::Enumerable` - Included

#all?	Passes each element of the collection to the given block.
#any?	Passes each element of the collection to the given block.
#chain	Returns an enumerator object generated from this enumerator and given enumerables.
#chunk	Enumerates over the items, chunking them together based on the return value of the block.
#chunk_while	Creates an enumerator for each chunked elements.
#collect	Alias for Enumerable#map.
#collect_concat	Alias for Enumerable#flat_map.
#count	Returns the number of items in `enum` through enumeration.
#cycle	Calls block for each element of enum repeatedly n times or forever if none or `nil` is given.
#detect	Alias for Enumerable#find.
#drop	Drops first n elements from enum, and returns rest elements in an array.
#drop_while	Drops elements up to, but not including, the first element for which the block returns `nil` or `false` and returns an array containing the remaining elements.
#each_cons	Iterates the given block for each array of consecutive <n> elements.
#each_entry	Calls block once for each element in `self`, passing that element as a parameter, converting multiple values from yield to an array.
#each_slice	Iterates the given block for each slice of <n> elements.
#each_with_index	Calls block with two arguments, the item and its index, for each item in enum.
#each_with_object	Iterates the given block for each element with an arbitrary object given, and returns the initially given object.
#entries	Alias for Enumerable#to_a.
#filter	Returns an array containing all elements of `enum` for which the given `block` returns a true value.
#filter_map	Returns a new array containing the truthy results (everything except `false` or `nil`) of running the `block` for every element in `enum`.
#find	Passes each entry in enum to block.
#find_all	Alias for Enumerable#filter.
#find_index	Compares each entry in enum with value or passes to block.
#first	Returns the first element, or the first `n` elements, of the enumerable.
#flat_map	Returns a new array with the concatenated results of running block once for every element in enum.
#grep	Returns an array of every element in enum for which `Pattern === element`.
#grep_v	Inverted version of Enumerable#grep.
#group_by	Groups the collection by result of the block.
#include?	Alias for Enumerable#member?.
#inject	Combines all elements of enum by applying a binary operation, specified by a block or a symbol that names a method or operator.
#lazy	Returns an `::Enumerator::Lazy`, which redefines most `::Enumerable` methods to postpone enumeration and enumerate values only on an as-needed basis.
#map	Returns a new array with the results of running block once for every element in enum.
#max	Returns the object in enum with the maximum value.
#max_by	Returns the object in enum that gives the maximum value from the given block.
#member?	Returns `true` if any member of enum equals obj.
#min	Returns the object in enum with the minimum value.
#min_by	Returns the object in enum that gives the minimum value from the given block.
#minmax	Returns a two element array which contains the minimum and the maximum value in the enumerable.
#minmax_by	Returns a two element array containing the objects in enum that correspond to the minimum and maximum values respectively from the given block.
#none?	Passes each element of the collection to the given block.
#one?	Passes each element of the collection to the given block.
#partition	Returns two arrays, the first containing the elements of enum for which the block evaluates to true, the second containing the rest.
#reduce	Alias for Enumerable#inject.
#reject	Returns an array for all elements of `enum` for which the given `block` returns `false`.
#reverse_each	Builds a temporary array and traverses that array in reverse order.
#select	Alias for Enumerable#filter.
#slice_after	Creates an enumerator for each chunked elements.
#slice_before	Creates an enumerator for each chunked elements.
#slice_when	Creates an enumerator for each chunked elements.
#sort	Returns an array containing the items in enum sorted.
#sort_by	Sorts enum using a set of keys generated by mapping the values in enum through the given block.
#sum	Returns the sum of elements in an `::Enumerable`.
#take	Returns first n elements from enum.
#take_while	Passes elements to the block until the block returns `nil` or `false`, then stops iterating and returns an array of all prior elements.
#tally	Tallies the collection, i.e., counts the occurrences of each element.
#to_a	Returns an array containing the items in enum.
#to_h	Returns the result of interpreting enum as a list of `[key, value]` pairs.
#uniq	Returns a new array by removing duplicate values in `self`.
#zip	Takes one element from enum and merges corresponding elements from each args.

Constructor Details

.new(size = 0, default = nil) .new(array) .new(size) {|index| ... }

Returns a new array.

In the first form, if no arguments are sent, the new array will be empty. When a #size and an optional default are sent, an array is created with #size copies of default. Take notice that all elements will reference the same object default.

The second form creates a copy of the array passed as a parameter (the array is generated by calling to_ary on the parameter).

first_array = ["Matz", "Guido"]

second_array = Array.new(first_array) #=> ["Matz", "Guido"]

first_array.equal? second_array       #=> false

In the last form, an array of the given size is created. Each element in this array is created by passing the element’s index to the given block and storing the return value.

Array.new(3) {|index| index ** 2}
# => [0, 1, 4]

Common gotchas

When sending the second parameter, the same object will be used as the value for all the array elements:

a = Array.new(2, Hash.new)
# => [{}, {}]

a[0]['cat'] = 'feline'
a # => [{"cat"=>"feline"}, {"cat"=>"feline"}]

a[1]['cat'] = 'Felix'
a # => [{"cat"=>"Felix"}, {"cat"=>"Felix"}]

Since all the Array elements store the same hash, changes to one of them will affect them all.

If multiple copies are what you want, you should use the block version which uses the result of that block each time an element of the array needs to be initialized:

a = Array.new(2) {Hash.new}
a[0]['cat'] = 'feline'
a # => [{"cat"=>"feline"}, {}]

[ GitHub ]

# File 'array.c', line 1001


static VALUE
rb_ary_initialize(int argc, VALUE *argv, VALUE ary)
{
    long len;
    VALUE size, val;

    rb_ary_modify(ary);
    if (argc == 0) {
        if (ARY_OWNS_HEAP_P(ary) && ARY_HEAP_PTR(ary) != NULL) {
            ary_heap_free(ary);
	}
        rb_ary_unshare_safe(ary);
        FL_SET_EMBED(ary);
	ARY_SET_EMBED_LEN(ary, 0);
	if (rb_block_given_p()) {
	    rb_warning("given block not used");
	}
	return ary;
    }
    rb_scan_args(argc, argv, "02", &size, &val);
    if (argc == 1 && !FIXNUM_P(size)) {
	val = rb_check_array_type(size);
	if (!NIL_P(val)) {
	    rb_ary_replace(ary, val);
	    return ary;
	}
    }

    len = NUM2LONG(size);
    /* NUM2LONG() may call size.to_int, ary can be frozen, modified, etc */
    if (len < 0) {
	rb_raise(rb_eArgError, "negative array size");
    }
    if (len > ARY_MAX_SIZE) {
	rb_raise(rb_eArgError, "array size too big");
    }
    /* recheck after argument conversion */
    rb_ary_modify(ary);
    ary_resize_capa(ary, len);
    if (rb_block_given_p()) {
	long i;

	if (argc == 2) {
	    rb_warn("block supersedes default value argument");
	}
	for (i=0; i<len; i++) {
	    rb_ary_store(ary, i, rb_yield(LONG2NUM(i)));
	    ARY_SET_LEN(ary, i + 1);
	}
    }
    else {
	ary_memfill(ary, 0, len, val);
	ARY_SET_LEN(ary, len);
    }
    return ary;
}

Class Method Details

.[](*args)

Returns a new array populated with the given objects.

Array.[]( 1, 'a', /^A/)  # => [1, "a", /^A/]
Array[ 1, 'a', /^A/ ]    # => [1, "a", /^A/]
[ 1, 'a', /^A/ ]         # => [1, "a", /^A/]

[ GitHub ]

# File 'array.c', line 1066


static VALUE
rb_ary_s_create(int argc, VALUE *argv, VALUE klass)
{
    VALUE ary = ary_new(klass, argc);
    if (argc > 0 && argv) {
        ary_memcpy(ary, 0, argc, argv);
        ARY_SET_LEN(ary, argc);
    }

    return ary;
}

.try_convert(obj) ⇒ `Array`^?

Tries to convert obj into an array, using the #to_ary method. Returns the converted array or nil if obj cannot be converted. This method can be used to check if an argument is an array.

Array.try_convert([1])   #=> [1]
Array.try_convert("1")   #=> nil

if tmp = Array.try_convert(arg)
  # the argument is an array
elsif tmp = String.try_convert(arg)
  # the argument is a string
end

[ GitHub ]

# File 'array.c', line 939


static VALUE
rb_ary_s_try_convert(VALUE dummy, VALUE ary)
{
    return rb_check_array_type(ary);
}

Instance Attribute Details

#empty? ⇒ `Boolean` (readonly)

Returns true if self contains no elements.

[].empty?   #=> true

[ GitHub ]

# File 'array.c', line 2229


static VALUE
rb_ary_empty_p(VALUE ary)
{
    if (RARRAY_LEN(ary) == 0)
	return Qtrue;
    return Qfalse;
}

Instance Method Details

#&(other_ary) ⇒ `Array`

Set Intersection — Returns a new array containing unique elements common to the two arrays. The order is preserved from the original array.

It compares elements using their #hash and #eql? methods for efficiency.

[ 1, 1, 3, 5 ] & [ 3, 2, 1 ]                 #=> [ 1, 3 ]
[ 'a', 'b', 'b', 'z' ] & [ 'a', 'b', 'c' ]   #=> [ 'a', 'b' ]

#(int) ⇒ `Array` #(str) ⇒ String

Repetition — With a ::String argument, equivalent to ary.join(str).

Otherwise, returns a new array built by concatenating the int copies of self.

[ 1, 2, 3 ] * 3    #=> [ 1, 2, 3, 1, 2, 3, 1, 2, 3 ]
[ 1, 2, 3 ] * ","  #=> "1,2,3"

[ GitHub ]

# File 'array.c', line 4091


static VALUE
rb_ary_times(VALUE ary, VALUE times)
{
    VALUE ary2, tmp;
    const VALUE *ptr;
    long t, len;

    tmp = rb_check_string_type(times);
    if (!NIL_P(tmp)) {
	return rb_ary_join(ary, tmp);
    }

    len = NUM2LONG(times);
    if (len == 0) {
	ary2 = ary_new(rb_obj_class(ary), 0);
	goto out;
    }
    if (len < 0) {
	rb_raise(rb_eArgError, "negative argument");
    }
    if (ARY_MAX_SIZE/len < RARRAY_LEN(ary)) {
	rb_raise(rb_eArgError, "argument too big");
    }
    len *= RARRAY_LEN(ary);

    ary2 = ary_new(rb_obj_class(ary), len);
    ARY_SET_LEN(ary2, len);

    ptr = RARRAY_CONST_PTR_TRANSIENT(ary);
    t = RARRAY_LEN(ary);
    if (0 < t) {
	ary_memcpy(ary2, 0, t, ptr);
	while (t <= len/2) {
            ary_memcpy(ary2, t, t, RARRAY_CONST_PTR_TRANSIENT(ary2));
            t *= 2;
        }
        if (t < len) {
            ary_memcpy(ary2, t, len-t, RARRAY_CONST_PTR_TRANSIENT(ary2));
        }
    }
  out:
    return ary2;
}

#+(other_ary) ⇒ `Array`

Concatenation — Returns a new array built by concatenating the two arrays together to produce a third array.

[ 1, 2, 3 ] + [ 4, 5 ]    #=> [ 1, 2, 3, 4, 5 ]
a = [ "a", "b", "c" ]
c = a + [ "d", "e", "f" ]
c                         #=> [ "a", "b", "c", "d", "e", "f" ]
a                         #=> [ "a", "b", "c" ]

Note that

x += y

is the same as

x = x + y

This means that it produces a new array. As a consequence, repeated use of += on arrays can be quite inefficient.

#-(other_ary) ⇒ `Array`

Array Difference

Returns a new array that is a copy of the original array, removing all occurrences of any item that also appear in other_ary. The order is preserved from the original array.

It compares elements using their #hash and #eql? methods for efficiency.

[ 1, 1, 2, 2, 3, 3, 4, 5 ] - [ 1, 2, 4 ]  #=>  [ 3, 3, 5 ]

Note that while 1 and 2 were only present once in the array argument, and were present twice in the receiver array, all occurrences of each ::Integer are removed in the returned array.

If you need set-like behavior, see the library class Set.

#<<(obj) ⇒ `Array`

Append—Pushes the given object on to the end of this array. This expression returns the array itself, so several appends may be chained together.

a = [ 1, 2 ]
a << "c" << "d" << [ 3, 4 ]
        #=>  [ 1, 2, "c", "d", [ 3, 4 ] ]
a
        #=>  [ 1, 2, "c", "d", [ 3, 4 ] ]

[ GitHub ]

# File 'array.c', line 1194


VALUE
rb_ary_push(VALUE ary, VALUE item)
{
    long idx = RARRAY_LEN((ary_verify(ary), ary));
    VALUE target_ary = ary_ensure_room_for_push(ary, 1);
    RARRAY_PTR_USE_TRANSIENT(ary, ptr, {
	RB_OBJ_WRITE(target_ary, &ptr[idx], item);
    });
    ARY_SET_LEN(ary, idx + 1);
    ary_verify(ary);
    return ary;
}

#<=>(other_ary) ⇒ `1`, ...

Comparison — Returns an integer (-1, 0, or +1) if this array is less than, equal to, or greater than other_ary.

Each object in each array is compared (using the <=> operator).

Arrays are compared in an “element-wise” manner; the first element of ary is compared with the first one of other_ary using the <=> operator, then each of the second elements, etc… As soon as the result of any such comparison is non zero (i.e. the two corresponding elements are not equal), that result is returned for the whole array comparison.

If all the elements are equal, then the result is based on a comparison of the array lengths. Thus, two arrays are “equal” according to <=> if, and only if, they have the same length and the value of each element is equal to the value of the corresponding element in the other array.

nil is returned if the other_ary is not an array or if the comparison of two elements returned nil.

[ "a", "a", "c" ]    <=> [ "a", "b", "c" ]   #=> -1
[ 1, 2, 3, 4, 5, 6 ] <=> [ 1, 2 ]            #=> +1
[ 1, 2 ]             <=> [ 1, :two ]         #=> nil

[ GitHub ]

# File 'array.c', line 4419


VALUE
rb_ary_cmp(VALUE ary1, VALUE ary2)
{
    long len;
    VALUE v;

    ary2 = rb_check_array_type(ary2);
    if (NIL_P(ary2)) return Qnil;
    if (ary1 == ary2) return INT2FIX(0);
    v = rb_exec_recursive_paired(recursive_cmp, ary1, ary2, ary2);
    if (v != Qundef) return v;
    len = RARRAY_LEN(ary1) - RARRAY_LEN(ary2);
    if (len == 0) return INT2FIX(0);
    if (len > 0) return INT2FIX(1);
    return INT2FIX(-1);
}

#==(other_ary) ⇒ `Boolean`

Equality — Two arrays are equal if they contain the same number of elements and if each element is equal to (according to Object#==) the corresponding element in other_ary.

[ "a", "c" ]    == [ "a", "c", 7 ]     #=> false
[ "a", "c", 7 ] == [ "a", "c", 7 ]     #=> true
[ "a", "c", 7 ] == [ "a", "d", "f" ]   #=> false

[ GitHub ]

# File 'array.c', line 4252


static VALUE
rb_ary_equal(VALUE ary1, VALUE ary2)
{
    if (ary1 == ary2) return Qtrue;
    if (!RB_TYPE_P(ary2, T_ARRAY)) {
	if (!rb_respond_to(ary2, idTo_ary)) {
	    return Qfalse;
	}
	return rb_equal(ary2, ary1);
    }
    if (RARRAY_LEN(ary1) != RARRAY_LEN(ary2)) return Qfalse;
    if (RARRAY_CONST_PTR_TRANSIENT(ary1) == RARRAY_CONST_PTR_TRANSIENT(ary2)) return Qtrue;
    return rb_exec_recursive_paired(recursive_equal, ary1, ary2, ary2);
}

#[](index) ⇒ Object^? #[](start, length) ⇒ `Array`^? #[](range) ⇒ `Array`^? #slice(index) ⇒ Object^? #slice(start, length) ⇒ `Array`^? #slice(range) ⇒ `Array`^?
Also known as: #slice

Element Reference — Returns the element at #index, or returns a subarray starting at the start index and continuing for #length elements, or returns a subarray specified by range of indices.

Negative indices count backward from the end of the array (-1 is the last element). For start and range cases the starting index is just before an element. Additionally, an empty array is returned when the starting index for an element range is at the end of the array.

Returns nil if the index (or starting index) are out of range.

a = [ "a", "b", "c", "d", "e" ]
a[2] +  a[0] + a[1]    #=> "cab"
a[6]                   #=> nil
a[1, 2]                #=> [ "b", "c" ]
a[1..3]                #=> [ "b", "c", "d" ]
a[4..7]                #=> [ "e" ]
a[6..10]               #=> nil
a[-3, 3]               #=> [ "c", "d", "e" ]
# special cases
a[5]                   #=> nil
a[6, 1]                #=> nil
a[5, 1]                #=> []
a[5..10]               #=> []

[ GitHub ]

# File 'array.c', line 1573


VALUE
rb_ary_aref(int argc, const VALUE *argv, VALUE ary)
{
    rb_check_arity(argc, 1, 2);
    if (argc == 2) {
	return rb_ary_aref2(ary, argv[0], argv[1]);
    }
    return rb_ary_aref1(ary, argv[0]);
}

#[]=(index, obj) ⇒ Object #[]=(start, length, obj or other_ary or nil) ⇒ Object, ... #[]=(range, obj or other_ary or nil) ⇒ Object, ...

Element Assignment — Sets the element at #index, or replaces a subarray from the start index for #length elements, or replaces a subarray specified by the range of indices.

If indices are greater than the current capacity of the array, the array grows automatically. Elements are inserted into the array at start if #length is zero.

Negative indices will count backward from the end of the array. For start and range cases the starting index is just before an element.

An IndexError is raised if a negative index points past the beginning of the array.

#all? {|obj| ... } ⇒ `Boolean` #all? ⇒ `Boolean` #all?(pattern) ⇒ `Boolean`

#any? {|obj| ... } ⇒ `Boolean` #any? ⇒ `Boolean` #any?(pattern) ⇒ `Boolean`

#push(obj, ...) ⇒ `Array` #append(obj, ...) ⇒ `Array`

Alias for #push.

#assoc(obj) ⇒ `element_ary`^?

Searches through an array whose elements are also arrays comparing obj with the first element of each contained array using obj.==.

Returns the first contained array that matches (that is, the first associated array), or nil if no match is found.

#at(index) ⇒ Object^?

Returns the element at #index. A negative index counts from the end of self. Returns nil if the index is out of range. See also #[].

a = [ "a", "b", "c", "d", "e" ]
a.at(0)     #=> "a"
a.at(-1)    #=> "e"

[ GitHub ]

# File 'array.c', line 1628


VALUE
rb_ary_at(VALUE ary, VALUE pos)
{
    return rb_ary_entry(ary, NUM2LONG(pos));
}

#bsearch {|x| ... } ⇒ `elem`

By using binary search, finds a value from this array which meets the given condition in O(log n) where n is the size of the array.

You can use this method in two modes: a find-minimum mode and a find-any mode. In either case, the elements of the array must be monotone (or sorted) with respect to the block.

In find-minimum mode (this is a good choice for typical use cases), the block must always return true or false, and there must be an index i (0 <= i <= ary.size) so that:

the block returns false for any element whose index is less than i, and
the block returns true for any element whose index is greater than or equal to i.

This method returns the i-th element. If i is equal to ary.size, it returns nil.

ary = [0, 4, 7, 10, 12]
ary.bsearch {|x| x >=   4 } #=> 4
ary.bsearch {|x| x >=   6 } #=> 7
ary.bsearch {|x| x >=  -1 } #=> 0
ary.bsearch {|x| x >= 100 } #=> nil

In find-any mode (this behaves like libc’s bsearch(3)), the block must always return a number, and there must be two indices i and j (0 <= i <= j <= ary.size) so that:

the block returns a positive number for ary if 0 <= k < i,
the block returns zero for ary if i <= k < j, and
the block returns a negative number for ary if j <= k < ary.size.

Under this condition, this method returns any element whose index is within i…j. If i is equal to j (i.e., there is no element that satisfies the block), this method returns nil.

ary = [0, 4, 7, 10, 12]
# try to find v such that 4 <= v < 8
ary.bsearch {|x| 1 - x / 4 } #=> 4 or 7
# try to find v such that 8 <= v < 10
ary.bsearch {|x| 4 - x / 2 } #=> nil

You must not mix the two modes at a time; the block must always return either true/false, or always return a number. It is undefined which value is actually picked up at each iteration.

[ GitHub ]

# File 'array.c', line 2928


static VALUE
rb_ary_bsearch(VALUE ary)
{
    VALUE index_result = rb_ary_bsearch_index(ary);

    if (FIXNUM_P(index_result)) {
	return rb_ary_entry(ary, FIX2LONG(index_result));
    }
    return index_result;
}

#bsearch_index {|x| ... } ⇒ Integer^?

By using binary search, finds an index of a value from this array which meets the given condition in O(log n) where n is the size of the array.

It supports two modes, depending on the nature of the block. They are exactly the same as in the case of the #bsearch method, with the only difference being that this method returns the index of the element instead of the element itself. For more details consult the documentation for #bsearch.

[ GitHub ]

# File 'array.c', line 2952


static VALUE
rb_ary_bsearch_index(VALUE ary)
{
    long low = 0, high = RARRAY_LEN(ary), mid;
    int smaller = 0, satisfied = 0;
    VALUE v, val;

    RETURN_ENUMERATOR(ary, 0, 0);
    while (low < high) {
	mid = low + ((high - low) / 2);
	val = rb_ary_entry(ary, mid);
	v = rb_yield(val);
	if (FIXNUM_P(v)) {
	    if (v == INT2FIX(0)) return INT2FIX(mid);
	    smaller = (SIGNED_VALUE)v < 0; /* Fixnum preserves its sign-bit */
	}
	else if (v == Qtrue) {
	    satisfied = 1;
	    smaller = 1;
	}
	else if (v == Qfalse || v == Qnil) {
	    smaller = 0;
	}
	else if (rb_obj_is_kind_of(v, rb_cNumeric)) {
	    const VALUE zero = INT2FIX(0);
	    switch (rb_cmpint(rb_funcallv(v, id_cmp, 1, &zero), v, zero)) {
	      case 0: return INT2FIX(mid);
	      case 1: smaller = 1; break;
	      case -1: smaller = 0;
	    }
	}
	else {
	    rb_raise(rb_eTypeError, "wrong argument type %"PRIsVALUE
		     " (must be numeric, true, false or nil)",
		     rb_obj_class(v));
	}
	if (smaller) {
	    high = mid;
	}
	else {
	    low = mid + 1;
	}
    }
    if (!satisfied) return Qnil;
    return INT2FIX(low);
}

#clear ⇒ `Array`

Removes all elements from self.

a = [ "a", "b", "c", "d", "e" ]
a.clear    #=> [ ]

[ GitHub ]

# File 'array.c', line 3861


VALUE
rb_ary_clear(VALUE ary)
{
    rb_ary_modify_check(ary);
    if (ARY_SHARED_P(ary)) {
	if (!ARY_EMBED_P(ary)) {
	    rb_ary_unshare(ary);
	    FL_SET_EMBED(ary);
            ARY_SET_EMBED_LEN(ary, 0);
	}
    }
    else {
        ARY_SET_LEN(ary, 0);
        if (ARY_DEFAULT_SIZE * 2 < ARY_CAPA(ary)) {
            ary_resize_capa(ary, ARY_DEFAULT_SIZE * 2);
        }
    }
    ary_verify(ary);
    return ary;
}

#collect {|item| ... } ⇒ `Array` #map {|item| ... } ⇒ `Array` #collect ⇒ Enumerator #map ⇒ Enumerator

Alias for #map.

#collect! {|item| ... } ⇒ `Array` #map! {|item| ... } ⇒ `Array` #collect! ⇒ Enumerator #map! ⇒ Enumerator

Alias for #map!.

#combination(n) {|c| ... } ⇒ `Array` #combination(n) ⇒ Enumerator

When invoked with a block, yields all combinations of length n of elements from the array and then returns the array itself.

The implementation makes no guarantees about the order in which the combinations are yielded.

If no block is given, an ::Enumerator is returned instead.

Examples:

a = [1, 2, 3, 4]
a.combination(1).to_a  #=> [[1],[2],[3],[4]]
a.combination(2).to_a  #=> [[1,2],[1,3],[1,4],[2,3],[2,4],[3,4]]
a.combination(3).to_a  #=> [[1,2,3],[1,2,4],[1,3,4],[2,3,4]]
a.combination(4).to_a  #=> [[1,2,3,4]]
a.combination(0).to_a  #=> [[]] # one combination of length 0
a.combination(5).to_a  #=> []   # no combinations of length 5

[ GitHub ]

# File 'array.c', line 5873


static VALUE
rb_ary_combination(VALUE ary, VALUE num)
{
    long i, n, len;

    n = NUM2LONG(num);
    RETURN_SIZED_ENUMERATOR(ary, 1, &num, rb_ary_combination_size);
    len = RARRAY_LEN(ary);
    if (n < 0 || len < n) {
	/* yield nothing */
    }
    else if (n == 0) {
	rb_yield(rb_ary_new2(0));
    }
    else if (n == 1) {
	for (i = 0; i < RARRAY_LEN(ary); i++) {
	    rb_yield(rb_ary_new3(1, RARRAY_AREF(ary, i)));
	}
    }
    else {
	VALUE ary0 = ary_make_shared_copy(ary); /* private defensive copy of ary */
	volatile VALUE t0;
	long *stack = ALLOCV_N(long, t0, n+1);

	RBASIC_CLEAR_CLASS(ary0);
	combinate0(len, n, stack, ary0);
	ALLOCV_END(t0);
	RBASIC_SET_CLASS_RAW(ary0, rb_cArray);
    }
    return ary;
}

#compact ⇒ `Array`

Returns a copy of self with all nil elements removed.

[ "a", nil, "b", nil, "c", nil ].compact
                  #=> [ "a", "b", "c" ]

[ GitHub ]

# File 'array.c', line 5088


static VALUE
rb_ary_compact(VALUE ary)
{
    ary = rb_ary_dup(ary);
    rb_ary_compact_bang(ary);
    return ary;
}

#compact! ⇒ `Array`^?

Removes nil elements from the array.

Returns nil if no changes were made, otherwise returns the array.

[ "a", nil, "b", nil, "c" ].compact! #=> [ "a", "b", "c" ]
[ "a", "b", "c" ].compact!           #=> nil

[ GitHub ]

# File 'array.c', line 5055


static VALUE
rb_ary_compact_bang(VALUE ary)
{
    VALUE *p, *t, *end;
    long n;

    rb_ary_modify(ary);
    p = t = (VALUE *)RARRAY_CONST_PTR_TRANSIENT(ary); /* WB: no new reference */
    end = p + RARRAY_LEN(ary);

    while (t < end) {
	if (NIL_P(*t)) t++;
	else *p++ = *t++;
    }
    n = p - RARRAY_CONST_PTR_TRANSIENT(ary);
    if (RARRAY_LEN(ary) == n) {
	return Qnil;
    }
    ary_resize_smaller(ary, n);

    return ary;
}

#concat(other_ary1, other_ary2, ...) ⇒ `Array`

Appends the elements of other_arys to self.

[ "a", "b" ].concat( ["c", "d"])   #=> [ "a", "b", "c", "d" ]
[ "a" ].concat( ["b"], ["c", "d"]) #=> [ "a", "b", "c", "d" ]
[ "a" ].concat #=> [ "a" ]

a = [ 1, 2, 3 ]
a.concat( [ 4, 5 ])
a                                 #=> [ 1, 2, 3, 4, 5 ]

a = [ 1, 2 ]
a.concat(a, a)                    #=> [1, 2, 1, 2, 1, 2]

#count ⇒ Integer #count(obj) ⇒ Integer #count {|item| ... } ⇒ Integer

Returns the number of elements.

If an argument is given, counts the number of elements which equal obj using #==.

If a block is given, counts the number of elements for which the block returns a true value.

ary = [1, 2, 4, 2]
ary.count                  #=> 4
ary.count(2)               #=> 2
ary.count {|x| x%2 == 0}   #=> 3

[ GitHub ]

# File 'array.c', line 5117


static VALUE
rb_ary_count(int argc, VALUE *argv, VALUE ary)
{
    long i, n = 0;

    if (rb_check_arity(argc, 0, 1) == 0) {
	VALUE v;

	if (!rb_block_given_p())
	    return LONG2NUM(RARRAY_LEN(ary));

	for (i = 0; i < RARRAY_LEN(ary); i++) {
	    v = RARRAY_AREF(ary, i);
	    if (RTEST(rb_yield(v))) n++;
	}
    }
    else {
        VALUE obj = argv[0];

	if (rb_block_given_p()) {
	    rb_warn("given block not used");
	}
	for (i = 0; i < RARRAY_LEN(ary); i++) {
	    if (rb_equal(RARRAY_AREF(ary, i), obj)) n++;
	}
    }

    return LONG2NUM(n);
}

#cycle(n = nil) {|obj| ... } ⇒ `nil` #cycle(n = nil) ⇒ Enumerator

Calls the given block for each element n times or forever if nil is given.

Does nothing if a non-positive number is given or the array is empty.

Returns nil if the loop has finished without getting interrupted.

If no block is given, an ::Enumerator is returned instead.

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.

[ GitHub ]

# File 'array.c', line 5609


static VALUE
rb_ary_cycle(int argc, VALUE *argv, VALUE ary)
{
    long n, i;

    rb_check_arity(argc, 0, 1);

    RETURN_SIZED_ENUMERATOR(ary, argc, argv, rb_ary_cycle_size);
    if (argc == 0 || NIL_P(argv[0])) {
        n = -1;
    }
    else {
        n = NUM2LONG(argv[0]);
        if (n <= 0) return Qnil;
    }

    while (RARRAY_LEN(ary) > 0 && (n < 0 || 0 < n--)) {
        for (i=0; i<RARRAY_LEN(ary); i++) {
            rb_yield(RARRAY_AREF(ary, i));
        }
    }
    return Qnil;
}

#deconstruct

[ GitHub ]

# File 'array.c', line 6682


static VALUE
rb_ary_deconstruct(VALUE ary)
{
    return ary;
}

#delete(obj) ⇒ `item`^? #delete(obj) ⇒ `item`, `result` `of` `block`

Deletes all items from self that are equal to obj.

Returns the last deleted item, or nil if no matching item is found.

If the optional code block is given, the result of the block is returned if the item is not found. (To remove nil elements and get an informative return value, use #compact!)

a = [ "a", "b", "b", "b", "c" ]
a.delete("b")                   #=> "b"
a                               #=> ["a", "c"]
a.delete("z")                   #=> nil
a.delete("z") {"not found"}     #=> "not found"

[ GitHub ]

# File 'array.c', line 3364


VALUE
rb_ary_delete(VALUE ary, VALUE item)
{
    VALUE v = item;
    long i1, i2;

    for (i1 = i2 = 0; i1 < RARRAY_LEN(ary); i1++) {
	VALUE e = RARRAY_AREF(ary, i1);

	if (rb_equal(e, item)) {
	    v = e;
	    continue;
	}
	if (i1 != i2) {
	    rb_ary_store(ary, i2, e);
	}
	i2++;
    }
    if (RARRAY_LEN(ary) == i2) {
	if (rb_block_given_p()) {
	    return rb_yield(item);
	}
	return Qnil;
    }

    ary_resize_smaller(ary, i2);

    ary_verify(ary);
    return v;
}

#delete_at(index) ⇒ Object^?

Deletes the element at the specified #index, returning that element, or nil if the #index is out of range.

#delete_if {|item| ... } ⇒ `Array` #delete_if ⇒ Enumerator

Deletes every element of self for which block evaluates to true.

The array is changed instantly every time the block is called, not after the iteration is over.

#difference(other_ary1, other_ary2, ...) ⇒ `Array`

Array Difference

Returns a new array that is a copy of the original array, removing all occurrences of any item that also appear in other_ary. The order is preserved from the original array.

It compares elements using their #hash and #eql? methods for efficiency.

[ 1, 1, 2, 2, 3, 3, 4, 5 ].difference([ 1, 2, 4 ])     #=> [ 3, 3, 5 ]

Note that while 1 and 2 were only present once in the array argument, and were present twice in the receiver array, all occurrences of each ::Integer are removed in the returned array.

Multiple array arguments can be supplied and all occurrences of any element in those supplied arrays that match the receiver will be removed from the returned array.

[ 1, 'c', :s, 'yep' ].difference([ 1 ], [ 'a', 'c' ])  #=> [ :s, "yep" ]

If you need set-like behavior, see the library class Set.

#dig(idx, ...) ⇒ Object

Extracts the nested value specified by the sequence of idx objects by calling dig at each step, returning nil if any intermediate step is nil.

a = [[1, [2, 3]]]

a.dig(0, 1, 1)                    #=> 3
a.dig(1, 2, 3)                    #=> nil
a.dig(0, 0, 0)                    #=> TypeError: Integer does not have #dig method
[42, {foo: :bar}].dig(1, :foo)    #=> :bar

[ GitHub ]

# File 'array.c', line 6500


static VALUE
rb_ary_dig(int argc, VALUE *argv, VALUE self)
{
    rb_check_arity(argc, 1, UNLIMITED_ARGUMENTS);
    self = rb_ary_at(self, *argv);
    if (!--argc) return self;
    ++argv;
    return rb_obj_dig(argc, argv, self, Qnil);
}

#drop(n) ⇒ `Array`

Drops first n elements from ary and returns the rest of the elements in an array.

If a negative number is given, raises an ::ArgumentError.

#drop_while {|obj| ... } ⇒ `Array` #drop_while ⇒ Enumerator

Drops elements up to, but not including, the first element for which the block returns nil or false and returns an array containing the remaining elements.

If no block is given, an ::Enumerator is returned instead.

#each {|item| ... } ⇒ `Array` #each ⇒ Enumerator

Calls the given block once for each element in self, passing that element as a parameter. Returns the array itself.

If no block is given, an ::Enumerator is returned.

a = [ "a", "b", "c" ]
a.each {|x| print x, " -- " }

produces:

a -- b -- c --

[ GitHub ]

# File 'array.c', line 2128


VALUE
rb_ary_each(VALUE ary)
{
    long i;
    ary_verify(ary);
    RETURN_SIZED_ENUMERATOR(ary, 0, 0, ary_enum_length);
    for (i=0; i<RARRAY_LEN(ary); i++) {
	rb_yield(RARRAY_AREF(ary, i));
    }
    return ary;
}

#each_index {|index| ... } ⇒ `Array` #each_index ⇒ Enumerator

Same as #each, but passes the #index of the element instead of the element itself.

An Enumerator is returned if no block is given.

a = [ "a", "b", "c" ]
a.each_index {|x| print x, " -- " }

produces:

0 -- 1 -- 2 --

[ GitHub ]

# File 'array.c', line 2158


static VALUE
rb_ary_each_index(VALUE ary)
{
    long i;
    RETURN_SIZED_ENUMERATOR(ary, 0, 0, ary_enum_length);

    for (i=0; i<RARRAY_LEN(ary); i++) {
	rb_yield(LONG2NUM(i));
    }
    return ary;
}

#eql?(other) ⇒ `Boolean`

Returns true if self and other are the same object, or are both arrays with the same content (according to Object#eql?).

[ GitHub ]

# File 'array.c', line 4288


static VALUE
rb_ary_eql(VALUE ary1, VALUE ary2)
{
    if (ary1 == ary2) return Qtrue;
    if (!RB_TYPE_P(ary2, T_ARRAY)) return Qfalse;
    if (RARRAY_LEN(ary1) != RARRAY_LEN(ary2)) return Qfalse;
    if (RARRAY_CONST_PTR_TRANSIENT(ary1) == RARRAY_CONST_PTR_TRANSIENT(ary2)) return Qtrue;
    return rb_exec_recursive_paired(recursive_eql, ary1, ary2, ary2);
}

#fetch(index) ⇒ Object #fetch(index, default) ⇒ Object #fetch(index) {|index| ... } ⇒ Object

Tries to return the element at position #index, but throws an ::IndexError exception if the referenced #index lies outside of the array bounds. This error can be prevented by supplying a second argument, which will act as a default value.

Alternatively, if a block is given it will only be executed when an invalid #index is referenced.

Negative values of #index count from the end of the array.

a = [ 11, 22, 33, 44 ]
a.fetch(1)               #=> 22
a.fetch(-1)              #=> 44
a.fetch(4, 'cat')        #=> "cat"
a.fetch(100) {|i| puts "#{i} is out of bounds"}
                         #=> "100 is out of bounds"

[ GitHub ]

# File 'array.c', line 1713


static VALUE
rb_ary_fetch(int argc, VALUE *argv, VALUE ary)
{
    VALUE pos, ifnone;
    long block_given;
    long idx;

    rb_scan_args(argc, argv, "11", &pos, &ifnone);
    block_given = rb_block_given_p();
    if (block_given && argc == 2) {
	rb_warn("block supersedes default value argument");
    }
    idx = NUM2LONG(pos);

    if (idx < 0) {
	idx +=  RARRAY_LEN(ary);
    }
    if (idx < 0 || RARRAY_LEN(ary) <= idx) {
	if (block_given) return rb_yield(pos);
	if (argc == 1) {
	    rb_raise(rb_eIndexError, "index %ld outside of array bounds: %ld...%ld",
			idx - (idx < 0 ? RARRAY_LEN(ary) : 0), -RARRAY_LEN(ary), RARRAY_LEN(ary));
	}
	return ifnone;
    }
    return RARRAY_AREF(ary, idx);
}

#fill(obj) ⇒ `Array` #fill(obj, start [, length]) ⇒ `Array` #fill(obj, range) ⇒ `Array` #fill {|index| ... } ⇒ `Array` #fill(start [, length]) {|index| ... } ⇒ `Array` #fill(range) {|index| ... } ⇒ `Array`

The first three forms set the selected elements of self (which may be the entire array) to obj.

A start of nil is equivalent to zero.

A #length of nil is equivalent to the length of the array.

The last three forms fill the array with the value of the given block, which is passed the absolute index of each element to be filled.

Negative values of start count from the end of the array, where -1 is the last element.

a = [ "a", "b", "c", "d" ]
a.fill("x")              #=> ["x", "x", "x", "x"]
a.fill("z", 2, 2)        #=> ["x", "x", "z", "z"]
a.fill("y", 0..1)        #=> ["y", "y", "z", "z"]
a.fill {|i| i*i}         #=> [0, 1, 4, 9]
a.fill(-2) {|i| i*i*i}   #=> [0, 1, 8, 27]

[ GitHub ]

# File 'array.c', line 3912


static VALUE
rb_ary_fill(int argc, VALUE *argv, VALUE ary)
{
    VALUE item = Qundef, arg1, arg2;
    long beg = 0, end = 0, len = 0;

    if (rb_block_given_p()) {
	rb_scan_args(argc, argv, "02", &arg1, &arg2);
	argc += 1;		/* hackish */
    }
    else {
	rb_scan_args(argc, argv, "12", &item, &arg1, &arg2);
    }
    switch (argc) {
      case 1:
	beg = 0;
	len = RARRAY_LEN(ary);
	break;
      case 2:
	if (rb_range_beg_len(arg1, &beg, &len, RARRAY_LEN(ary), 1)) {
	    break;
	}
	/* fall through */
      case 3:
	beg = NIL_P(arg1) ? 0 : NUM2LONG(arg1);
	if (beg < 0) {
	    beg = RARRAY_LEN(ary) + beg;
	    if (beg < 0) beg = 0;
	}
	len = NIL_P(arg2) ? RARRAY_LEN(ary) - beg : NUM2LONG(arg2);
	break;
    }
    rb_ary_modify(ary);
    if (len < 0) {
        return ary;
    }
    if (beg >= ARY_MAX_SIZE || len > ARY_MAX_SIZE - beg) {
	rb_raise(rb_eArgError, "argument too big");
    }
    end = beg + len;
    if (RARRAY_LEN(ary) < end) {
	if (end >= ARY_CAPA(ary)) {
	    ary_resize_capa(ary, end);
	}
	ary_mem_clear(ary, RARRAY_LEN(ary), end - RARRAY_LEN(ary));
	ARY_SET_LEN(ary, end);
    }

    if (item == Qundef) {
	VALUE v;
	long i;

	for (i=beg; i<end; i++) {
	    v = rb_yield(LONG2NUM(i));
	    if (i>=RARRAY_LEN(ary)) break;
	    ARY_SET(ary, i, v);
	}
    }
    else {
	ary_memfill(ary, beg, len, item);
    }
    return ary;
}

#select {|item| ... } ⇒ `Array` #select ⇒ Enumerator #filter {|item| ... } ⇒ `Array` #filter ⇒ Enumerator
Also known as: #select

Returns a new array containing all elements of ary for which the given block returns a true value.

If no block is given, an ::Enumerator is returned instead.

[1,2,3,4,5].select {|num| num.even? }     #=> [2, 4]

a = %w[ a b c d e f ]
a.select {|v| v =~ /[aeiou]/ }    #=> ["a", "e"]

#select! {|item| ... } ⇒ `Array`^? #select! ⇒ Enumerator #filter! {|item| ... } ⇒ `Array`^? #filter! ⇒ Enumerator
Also known as: #select!

Invokes the given block passing in successive elements from self, deleting elements for which the block returns a false value.

The array may not be changed instantly every time the block is called.

If changes were made, it will return self, otherwise it returns nil.

If no block is given, an ::Enumerator is returned instead.

#find_index(obj) ⇒ Integer^? #find_index {|item| ... } ⇒ Integer^? #find_index ⇒ Enumerator #index(obj) ⇒ Integer^? #index {|item| ... } ⇒ Integer^? #index ⇒ Enumerator

Alias for #index.

#first ⇒ Object^? #first(n) ⇒ `Array`

Returns the first element, or the first n elements, of the array. If the array is empty, the first form returns nil, and the second form returns an empty array. See also #last for the opposite effect.

a = [ "q", "r", "s", "t" ]
a.first     #=> "q"
a.first(2)  #=> ["q", "r"]

[ GitHub ]

# File 'array.c', line 1649


static VALUE
rb_ary_first(int argc, VALUE *argv, VALUE ary)
{
    if (argc == 0) {
	if (RARRAY_LEN(ary) == 0) return Qnil;
	return RARRAY_AREF(ary, 0);
    }
    else {
	return ary_take_first_or_last(argc, argv, ary, ARY_TAKE_FIRST);
    }
}

#flatten ⇒ `Array` #flatten(level) ⇒ `Array`

Returns a new array that is a one-dimensional flattening of self (recursively).

That is, for every element that is an array, extract its elements into the new array.

The optional level argument determines the level of recursion to flatten.

s = [ 1, 2, 3 ]           #=> [1, 2, 3]
t = [ 4, 5, 6, [7, 8] ]   #=> [4, 5, 6, [7, 8]]
a = [ s, t, 9, 10 ]       #=> [[1, 2, 3], [4, 5, 6, [7, 8]], 9, 10]
a.flatten                 #=> [1, 2, 3, 4, 5, 6, 7, 8, 9, 10]
a = [ 1, 2, [3, [4, 5] ] ]
a.flatten(1)              #=> [1, 2, 3, [4, 5]]

[ GitHub ]

# File 'array.c', line 5303


static VALUE
rb_ary_flatten(int argc, VALUE *argv, VALUE ary)
{
    int level = -1;
    VALUE result;

    if (rb_check_arity(argc, 0, 1) && !NIL_P(argv[0])) {
        level = NUM2INT(argv[0]);
        if (level == 0) return ary_make_shared_copy(ary);
    }

    result = flatten(ary, level);
    if (result == ary) {
        result = ary_make_shared_copy(ary);
    }

    return result;
}

#flatten! ⇒ `Array`^? #flatten!(level) ⇒ `Array`^?

Flattens self in place.

Returns nil if no modifications were made (i.e., the array contains no subarrays.)

The optional level argument determines the level of recursion to flatten.

a = [ 1, 2, [3, [4, 5] ] ]
a.flatten!   #=> [1, 2, 3, 4, 5]
a.flatten!   #=> nil
a            #=> [1, 2, 3, 4, 5]
a = [ 1, 2, [3, [4, 5] ] ]
a.flatten!(1) #=> [1, 2, 3, [4, 5]]

[ GitHub ]

# File 'array.c', line 5259


static VALUE
rb_ary_flatten_bang(int argc, VALUE *argv, VALUE ary)
{
    int mod = 0, level = -1;
    VALUE result, lv;

    lv = (rb_check_arity(argc, 0, 1) ? argv[0] : Qnil);
    rb_ary_modify_check(ary);
    if (!NIL_P(lv)) level = NUM2INT(lv);
    if (level == 0) return Qnil;

    result = flatten(ary, level);
    if (result == ary) {
	return Qnil;
    }
    if (!(mod = ARY_EMBED_P(result))) rb_obj_freeze(result);
    rb_ary_replace(ary, result);
    if (mod) ARY_SET_EMBED_LEN(result, 0);

    return ary;
}

#hash ⇒ Integer

Compute a hash-code for this array.

Two arrays with the same content will have the same hash code (and will compare using #eql?).

#include?(object) ⇒ `Boolean`

Returns true if the given object is present in self (that is, if any element #== object), otherwise returns false.

a = [ "a", "b", "c" ]
a.include?("b")   #=> true
a.include?("z")   #=> false

[ GitHub ]

# File 'array.c', line 4339


VALUE
rb_ary_includes(VALUE ary, VALUE item)
{
    long i;
    VALUE e;

    for (i=0; i<RARRAY_LEN(ary); i++) {
	e = RARRAY_AREF(ary, i);
	if (rb_equal(e, item)) {
	    return Qtrue;
	}
    }
    return Qfalse;
}

#find_index(obj) ⇒ Integer^? #find_index {|item| ... } ⇒ Integer^? #find_index ⇒ Enumerator #index(obj) ⇒ Integer^? #index {|item| ... } ⇒ Integer^? #index ⇒ Enumerator
Also known as: #find_index

Returns the index of the first object in ary such that the object is #== to obj.

If a block is given instead of an argument, returns the index of the first object for which the block returns true. Returns nil if no match is found.

#replace(other_ary) ⇒ `Array` #initialize_copy(other_ary) ⇒ `Array`

Alias for #replace.

#insert(index, obj...) ⇒ `Array`

Inserts the given values before the element with the given #index.

Negative indices count backwards from the end of the array, where -1 is the last element. If a negative index is used, the given values will be inserted after that element, so using an index of -1 will insert the values at the end of the array.

a = %w{ a b c d }
a.insert(2, 99)         #=> ["a", "b", 99, "c", "d"]
a.insert(-2, 1, 2, 3)   #=> ["a", "b", 99, "c", 1, 2, 3, "d"]

[ GitHub ]

# File 'array.c', line 2077


static VALUE
rb_ary_insert(int argc, VALUE *argv, VALUE ary)
{
    long pos;

    rb_check_arity(argc, 1, UNLIMITED_ARGUMENTS);
    rb_ary_modify_check(ary);
    pos = NUM2LONG(argv[0]);
    if (argc == 1) return ary;
    if (pos == -1) {
	pos = RARRAY_LEN(ary);
    }
    else if (pos < 0) {
	long minpos = -RARRAY_LEN(ary) - 1;
	if (pos < minpos) {
	    rb_raise(rb_eIndexError, "index %ld too small for array; minimum: %ld",
		     pos, minpos);
	}
	pos++;
    }
    rb_ary_splice(ary, pos, 0, argv + 1, argc - 1);
    return ary;
}

#inspect ⇒ String #to_s ⇒ String

Alias for #to_s.

#intersection(other_ary1, other_ary2, ...) ⇒ `Array`

Set Intersection — Returns a new array containing unique elements common to self and other_arys. Order is preserved from the original array.

It compares elements using their #hash and #eql? methods for efficiency.

[ 1, 1, 3, 5 ].intersection([ 3, 2, 1 ])                    # => [ 1, 3 ]
[ "a", "b", "z" ].intersection([ "a", "b", "c" ], [ "b" ])  # => [ "b" ]
[ "a" ].intersection #=> [ "a" ]

#join(separator = $,) ⇒ String

Returns a string created by converting each element of the array to a string, separated by the given separator. If the separator is nil, it uses current $,. If both the separator and $, are nil, it uses an empty string.

[ "a", "b", "c" ].join        #=> "abc"
[ "a", "b", "c" ].join("-")   #=> "a-b-c"

For nested arrays, join is applied recursively:

[ "a", [1, 2, [:x, :y]], "b" ].join("-")   #=> "a-1-2-x-y-b"

[ GitHub ]

# File 'array.c', line 2401


static VALUE
rb_ary_join_m(int argc, VALUE *argv, VALUE ary)
{
    VALUE sep;

    if (rb_check_arity(argc, 0, 1) == 0 || NIL_P(sep = argv[0])) {
        sep = rb_output_fs;
        if (!NIL_P(sep)) {
            rb_warn("$, is set to non-nil value");
        }
    }

    return rb_ary_join(ary, sep);
}

#keep_if {|item| ... } ⇒ `Array` #keep_if ⇒ Enumerator

Deletes every element of self for which the given block evaluates to false, and returns self.

If no block is given, an ::Enumerator is returned instead.

a = %w[ a b c d e f ]
a.keep_if {|v| v =~ /[aeiou]/ }    #=> ["a", "e"]
a                                  #=> ["a", "e"]

#last ⇒ Object^? #last(n) ⇒ `Array`

Returns the last element(s) of self. If the array is empty, the first form returns nil.

See also #first for the opposite effect.

a = [ "w", "x", "y", "z" ]
a.last     #=> "z"
a.last(2)  #=> ["y", "z"]

[ GitHub ]

# File 'array.c', line 1676


VALUE
rb_ary_last(int argc, const VALUE *argv, VALUE ary)
{
    if (argc == 0) {
	long len = RARRAY_LEN(ary);
	if (len == 0) return Qnil;
	return RARRAY_AREF(ary, len-1);
    }
    else {
	return ary_take_first_or_last(argc, argv, ary, ARY_TAKE_LAST);
    }
}

#length ⇒ Integer Also known as: #size

Returns the number of elements in self. May be zero.

[ 1, 2, 3, 4, 5 ].length   #=> 5
[].length                  #=> 0

[ GitHub ]

# File 'array.c', line 2213


static VALUE
rb_ary_length(VALUE ary)
{
    long len = RARRAY_LEN(ary);
    return LONG2NUM(len);
}

#collect {|item| ... } ⇒ `Array` #map {|item| ... } ⇒ `Array` #collect ⇒ Enumerator #map ⇒ Enumerator
Also known as: #collect

Invokes the given block once for each element of self.

Creates a new array containing the values returned by the block.

#collect! {|item| ... } ⇒ `Array` #map! {|item| ... } ⇒ `Array` #collect! ⇒ Enumerator #map! ⇒ Enumerator
Also known as: #collect!

Invokes the given block once for each element of self, replacing the element with the value returned by the block.

#max ⇒ Object #max {|a, b| ... } ⇒ Object #max(n) ⇒ `Array` #max(n) {|a, b| ... } ⇒ `Array`

Returns the object in ary with the maximum value. The first form assumes all objects implement Comparable; the second uses the block to return a <=> b.

ary = %w(albatross dog horse)
ary.max                                   #=> "horse"
ary.max {|a, b| a.length <=> b.length}    #=> "albatross"

If the n argument is given, maximum n elements are returned as an array.

ary = %w[albatross dog horse]
ary.max(2)                                  #=> ["horse", "dog"]
ary.max(2) {|a, b| a.length <=> b.length }  #=> ["albatross", "horse"]

[ GitHub ]

# File 'array.c', line 4828


static VALUE
rb_ary_max(int argc, VALUE *argv, VALUE ary)
{
    struct cmp_opt_data cmp_opt = { 0, 0 };
    VALUE result = Qundef, v;
    VALUE num;
    long i;

    if (rb_check_arity(argc, 0, 1) && !NIL_P(num = argv[0]))
       return rb_nmin_run(ary, num, 0, 1, 1);

    if (rb_block_given_p()) {
	for (i = 0; i < RARRAY_LEN(ary); i++) {
	   v = RARRAY_AREF(ary, i);
	   if (result == Qundef || rb_cmpint(rb_yield_values(2, v, result), v, result) > 0) {
	       result = v;
	   }
	}
    }
    else {
	for (i = 0; i < RARRAY_LEN(ary); i++) {
	   v = RARRAY_AREF(ary, i);
	   if (result == Qundef || OPTIMIZED_CMP(v, result, cmp_opt) > 0) {
	       result = v;
	   }
	}
    }
    if (result == Qundef) return Qnil;
    return result;
}

#min ⇒ Object #min {|a, b| ... } ⇒ Object #min(n) ⇒ `Array` #min(n) {|a, b| ... } ⇒ `Array`

Returns the object in ary with the minimum value. The first form assumes all objects implement Comparable; the second uses the block to return a <=> b.

ary = %w(albatross dog horse)
ary.min                                   #=> "albatross"
ary.min {|a, b| a.length <=> b.length}    #=> "dog"

If the n argument is given, minimum n elements are returned as an array.

ary = %w[albatross dog horse]
ary.min(2)                                  #=> ["albatross", "dog"]
ary.min(2) {|a, b| a.length <=> b.length }  #=> ["dog", "horse"]

[ GitHub ]

# File 'array.c', line 4881


static VALUE
rb_ary_min(int argc, VALUE *argv, VALUE ary)
{
    struct cmp_opt_data cmp_opt = { 0, 0 };
    VALUE result = Qundef, v;
    VALUE num;
    long i;

    if (rb_check_arity(argc, 0, 1) && !NIL_P(num = argv[0]))
       return rb_nmin_run(ary, num, 0, 0, 1);

    if (rb_block_given_p()) {
	for (i = 0; i < RARRAY_LEN(ary); i++) {
	   v = RARRAY_AREF(ary, i);
	   if (result == Qundef || rb_cmpint(rb_yield_values(2, v, result), v, result) < 0) {
	       result = v;
	   }
	}
    }
    else {
	for (i = 0; i < RARRAY_LEN(ary); i++) {
	   v = RARRAY_AREF(ary, i);
	   if (result == Qundef || OPTIMIZED_CMP(v, result, cmp_opt) < 0) {
	       result = v;
	   }
	}
    }
    if (result == Qundef) return Qnil;
    return result;
}

#minmax ⇒ `Array`, Object #minmax {|a, b| ... } ⇒ `Array`, Object

Returns a two element array which contains the minimum and the maximum value in the array.

Can be given an optional block to override the default comparison method a <=> b.

[ GitHub ]

# File 'array.c', line 4923


static VALUE
rb_ary_minmax(VALUE ary)
{
    if (rb_block_given_p()) {
        return rb_call_super(0, NULL);
    }
    return rb_assoc_new(rb_ary_min(0, 0, ary), rb_ary_max(0, 0, ary));
}

#none? {|obj| ... } ⇒ `Boolean` #none? ⇒ `Boolean` #none?(pattern) ⇒ `Boolean`

#one? {|obj| ... } ⇒ `Boolean` #one? ⇒ `Boolean` #one?(pattern) ⇒ `Boolean`

#pack(aTemplateString) ⇒ `aBinaryString` #pack(aTemplateString, buffer: aBufferString) ⇒ `aBufferString`

Packs the contents of arr into a binary sequence according to the directives in aTemplateString (see the table below) Directives “A,” “a,” and “Z” may be followed by a count, which gives the width of the resulting field. The remaining directives also may take a count, indicating the number of array elements to convert. If the count is an asterisk (“*”), all remaining array elements will be converted. Any of the directives “sSiIlL” may be followed by an underscore (“_”) or exclamation mark (“!”) to use the underlying platform’s native size for the specified type; otherwise, they use a platform-independent size. Spaces are ignored in the template string. See also String#unpack.

a = [ "a", "b", "c" ]
n = [ 65, 66, 67 ]
a.pack("A3A3A3")   #=> "a  b  c  "
a.pack("a3a3a3")   #=> "a\000\000b\000\000c\000\000"
n.pack("ccc")      #=> "ABC"

If aBufferString is specified and its capacity is enough, pack uses it as the buffer and returns it. When the offset is specified by the beginning of aTemplateString, the result is filled after the offset. If original contents of aBufferString exists and it’s longer than the offset, the rest of offsetOfBuffer are overwritten by the result. If it’s shorter, the gap is filled with “\0”.

Note that “buffer:” option does not guarantee not to allocate memory in pack. If the capacity of aBufferString is not enough, pack allocates memory.

Directives for pack.

Integer       | Array   |
Directive     | Element | Meaning
----------------------------------------------------------------------------
C             | Integer | 8-bit unsigned (unsigned char)
S             | Integer | 16-bit unsigned, native endian (uint16_t)
L             | Integer | 32-bit unsigned, native endian (uint32_t)
Q             | Integer | 64-bit unsigned, native endian (uint64_t)
J             | Integer | pointer width unsigned, native endian (uintptr_t)
              |         | (J is available since Ruby 2.3.)
              |         |
c             | Integer | 8-bit signed (signed char)
s             | Integer | 16-bit signed, native endian (int16_t)
l             | Integer | 32-bit signed, native endian (int32_t)
q             | Integer | 64-bit signed, native endian (int64_t)
j             | Integer | pointer width signed, native endian (intptr_t)
              |         | (j is available since Ruby 2.3.)
              |         |
S_ S!         | Integer | unsigned short, native endian
I I_ I!       | Integer | unsigned int, native endian
L_ L!         | Integer | unsigned long, native endian
Q_ Q!         | Integer | unsigned long long, native endian (ArgumentError
              |         | if the platform has no long long type.)
              |         | (Q_ and Q! is available since Ruby 2.1.)
J!            | Integer | uintptr_t, native endian (same with J)
              |         | (J! is available since Ruby 2.3.)
              |         |
s_ s!         | Integer | signed short, native endian
i i_ i!       | Integer | signed int, native endian
l_ l!         | Integer | signed long, native endian
q_ q!         | Integer | signed long long, native endian (ArgumentError
              |         | if the platform has no long long type.)
              |         | (q_ and q! is available since Ruby 2.1.)
j!            | Integer | intptr_t, native endian (same with j)
              |         | (j! is available since Ruby 2.3.)
              |         |
S> s> S!> s!> | Integer | same as the directives without ">" except
L> l> L!> l!> |         | big endian
I!> i!>       |         | (available since Ruby 1.9.3)
Q> q> Q!> q!> |         | "S>" is same as "n"
J> j> J!> j!> |         | "L>" is same as "N"
              |         |
S< s< S!< s!< | Integer | same as the directives without "<" except
L< l< L!< l!< |         | little endian
I!< i!<       |         | (available since Ruby 1.9.3)
Q< q< Q!< q!< |         | "S<" is same as "v"
J< j< J!< j!< |         | "L<" is same as "V"
              |         |
n             | Integer | 16-bit unsigned, network (big-endian) byte order
N             | Integer | 32-bit unsigned, network (big-endian) byte order
v             | Integer | 16-bit unsigned, VAX (little-endian) byte order
V             | Integer | 32-bit unsigned, VAX (little-endian) byte order
              |         |
U             | Integer | UTF-8 character
w             | Integer | BER-compressed integer

Float        | Array   |
Directive    | Element | Meaning
---------------------------------------------------------------------------
D d          | Float   | double-precision, native format
F f          | Float   | single-precision, native format
E            | Float   | double-precision, little-endian byte order
e            | Float   | single-precision, little-endian byte order
G            | Float   | double-precision, network (big-endian) byte order
g            | Float   | single-precision, network (big-endian) byte order

String       | Array   |
Directive    | Element | Meaning
---------------------------------------------------------------------------
A            | String  | arbitrary binary string (space padded, count is width)
a            | String  | arbitrary binary string (null padded, count is width)
Z            | String  | same as ``a'', except that null is added with *
B            | String  | bit string (MSB first)
b            | String  | bit string (LSB first)
H            | String  | hex string (high nibble first)
h            | String  | hex string (low nibble first)
u            | String  | UU-encoded string
M            | String  | quoted printable, MIME encoding (see also RFC2045)
             |         | (text mode but input must use LF and output LF)
m            | String  | base64 encoded string (see RFC 2045)
             |         | (if count is 0, no line feed are added, see RFC 4648)
             |         | (count specifies input bytes between each LF,
             |         | rounded down to nearest multiple of 3)
P            | String  | pointer to a structure (fixed-length string)
p            | String  | pointer to a null-terminated string

Misc.        | Array   |
Directive    | Element | Meaning
---------------------------------------------------------------------------
@            | ---     | moves to absolute position
X            | ---     | back up a byte
x            | ---     | null byte

[ GitHub ]

# File 'pack.rb', line 133


def pack(fmt, buffer: nil)
  __builtin_pack_pack(fmt, buffer)
end

#permutation {|p| ... } ⇒ `Array` #permutation ⇒ Enumerator #permutation(n) {|p| ... } ⇒ `Array` #permutation(n) ⇒ Enumerator

When invoked with a block, yield all permutations of length n of the elements of the array, then return the array itself.

If n is not specified, yield all permutations of all elements.

The implementation makes no guarantees about the order in which the permutations are yielded.

If no block is given, an ::Enumerator is returned instead.

Examples:

a = [1, 2, 3]
a.permutation.to_a    #=> [[1,2,3],[1,3,2],[2,1,3],[2,3,1],[3,1,2],[3,2,1]]
a.permutation(1).to_a #=> [[1],[2],[3]]
a.permutation(2).to_a #=> [[1,2],[1,3],[2,1],[2,3],[3,1],[3,2]]
a.permutation(3).to_a #=> [[1,2,3],[1,3,2],[2,1,3],[2,3,1],[3,1,2],[3,2,1]]
a.permutation(0).to_a #=> [[]] # one permutation of length 0
a.permutation(4).to_a #=> []   # no permutations of length 4

[ GitHub ]

# File 'array.c', line 5780


static VALUE
rb_ary_permutation(int argc, VALUE *argv, VALUE ary)
{
    long r, n, i;

    n = RARRAY_LEN(ary);                  /* Array length */
    RETURN_SIZED_ENUMERATOR(ary, argc, argv, rb_ary_permutation_size);   /* Return enumerator if no block */
    r = n;
    if (rb_check_arity(argc, 0, 1) && !NIL_P(argv[0]))
        r = NUM2LONG(argv[0]);            /* Permutation size from argument */

    if (r < 0 || n < r) {
	/* no permutations: yield nothing */
    }
    else if (r == 0) { /* exactly one permutation: the zero-length array */
	rb_yield(rb_ary_new2(0));
    }
    else if (r == 1) { /* this is a special, easy case */
	for (i = 0; i < RARRAY_LEN(ary); i++) {
	    rb_yield(rb_ary_new3(1, RARRAY_AREF(ary, i)));
	}
    }
    else {             /* this is the general case */
	volatile VALUE t0;
	long *p = ALLOCV_N(long, t0, r+roomof(n, sizeof(long)));
	char *used = (char*)(p + r);
	VALUE ary0 = ary_make_shared_copy(ary); /* private defensive copy of ary */
	RBASIC_CLEAR_CLASS(ary0);

	MEMZERO(used, char, n); /* initialize array */

	permute0(n, r, p, used, ary0); /* compute and yield permutations */
	ALLOCV_END(t0);
	RBASIC_SET_CLASS_RAW(ary0, rb_cArray);
    }
    return ary;
}

#pop ⇒ Object^? #pop(n) ⇒ `Array`

Removes the last element from self and returns it, or nil if the array is empty.

If a number n is given, returns an array of the last n elements (or less) just like array.slice!(-n, n) does. See also #push for the opposite effect.

a = [ "a", "b", "c", "d" ]
a.pop     #=> "d"
a.pop(2)  #=> ["b", "c"]
a         #=> ["a"]

[ GitHub ]

# File 'array.c', line 1277


static VALUE
rb_ary_pop_m(int argc, VALUE *argv, VALUE ary)
{
    VALUE result;

    if (argc == 0) {
	return rb_ary_pop(ary);
    }

    rb_ary_modify_check(ary);
    result = ary_take_first_or_last(argc, argv, ary, ARY_TAKE_LAST);
    ARY_INCREASE_LEN(ary, -RARRAY_LEN(result));
    ary_verify(ary);
    return result;
}

#unshift(obj, ...) ⇒ `Array` #prepend(obj, ...) ⇒ `Array`
Also known as: #unshift

Prepends objects to the front of self, moving other elements upwards. See also #shift for the opposite effect.

a = [ "b", "c", "d" ]
a.unshift("a")   #=> ["a", "b", "c", "d"]
a.unshift(1, 2)  #=> [ 1, 2, "a", "b", "c", "d"]

[ GitHub ]

# File 'array.c', line 1476


static VALUE
rb_ary_unshift_m(int argc, VALUE *argv, VALUE ary)
{
    long len = RARRAY_LEN(ary);
    VALUE target_ary;

    if (argc == 0) {
	rb_ary_modify_check(ary);
	return ary;
    }

    target_ary = ary_ensure_room_for_unshift(ary, argc);
    ary_memcpy0(ary, 0, argc, argv, target_ary);
    ARY_SET_LEN(ary, len + argc);
    return ary;
}

#product(other_ary, ...) ⇒ `Array` #product(other_ary, ...) {|p| ... } ⇒ `Array`

Returns an array of all combinations of elements from all arrays.

The length of the returned array is the product of the length of self and the argument arrays.

If given a block, #product will yield all combinations and return self instead.

[1,2,3].product([4,5])     #=> [[1,4],[1,5],[2,4],[2,5],[3,4],[3,5]]
[1,2].product([1,2])       #=> [[1,1],[1,2],[2,1],[2,2]]
[1,2].product([3,4],[5,6]) #=> [[1,3,5],[1,3,6],[1,4,5],[1,4,6],
                           #     [2,3,5],[2,3,6],[2,4,5],[2,4,6]]
[1,2].product()            #=> [[1],[2]]
[1,2].product([])          #=> []

[ GitHub ]

# File 'array.c', line 6128


static VALUE
rb_ary_product(int argc, VALUE *argv, VALUE ary)
{
    int n = argc+1;    /* How many arrays we're operating on */
    volatile VALUE t0 = tmpary(n);
    volatile VALUE t1 = Qundef;
    VALUE *arrays = RARRAY_PTR(t0); /* The arrays we're computing the product of */
    int *counters = ALLOCV_N(int, t1, n); /* The current position in each one */
    VALUE result = Qnil;      /* The array we'll be returning, when no block given */
    long i,j;
    long resultlen = 1;

    RBASIC_CLEAR_CLASS(t0);

    /* initialize the arrays of arrays */
    ARY_SET_LEN(t0, n);
    arrays[0] = ary;
    for (i = 1; i < n; i++) arrays[i] = Qnil;
    for (i = 1; i < n; i++) arrays[i] = to_ary(argv[i-1]);

    /* initialize the counters for the arrays */
    for (i = 0; i < n; i++) counters[i] = 0;

    /* Otherwise, allocate and fill in an array of results */
    if (rb_block_given_p()) {
	/* Make defensive copies of arrays; exit if any is empty */
	for (i = 0; i < n; i++) {
	    if (RARRAY_LEN(arrays[i]) == 0) goto done;
	    arrays[i] = ary_make_shared_copy(arrays[i]);
	}
    }
    else {
	/* Compute the length of the result array; return [] if any is empty */
	for (i = 0; i < n; i++) {
	    long k = RARRAY_LEN(arrays[i]);
	    if (k == 0) {
		result = rb_ary_new2(0);
		goto done;
	    }
            if (MUL_OVERFLOW_LONG_P(resultlen, k))
		rb_raise(rb_eRangeError, "too big to product");
	    resultlen *= k;
	}
	result = rb_ary_new2(resultlen);
    }
    for (;;) {
	int m;
	/* fill in one subarray */
	VALUE subarray = rb_ary_new2(n);
	for (j = 0; j < n; j++) {
	    rb_ary_push(subarray, rb_ary_entry(arrays[j], counters[j]));
	}

	/* put it on the result array */
	if (NIL_P(result)) {
	    FL_SET(t0, FL_USER5);
	    rb_yield(subarray);
	    if (! FL_TEST(t0, FL_USER5)) {
		rb_raise(rb_eRuntimeError, "product reentered");
	    }
	    else {
		FL_UNSET(t0, FL_USER5);
	    }
	}
	else {
	    rb_ary_push(result, subarray);
	}

	/*
	 * Increment the last counter.  If it overflows, reset to 0
	 * and increment the one before it.
	 */
	m = n-1;
	counters[m]++;
	while (counters[m] == RARRAY_LEN(arrays[m])) {
	    counters[m] = 0;
	    /* If the first counter overflows, we are done */
	    if (--m < 0) goto done;
	    counters[m]++;
	}
    }
done:
    tmpary_discard(t0);
    ALLOCV_END(t1);

    return NIL_P(result) ? ary : result;
}

#push(obj, ...) ⇒ `Array` #append(obj, ...) ⇒ `Array`
Also known as: #append

Append — Pushes the given object(s) on to the end of this array. This expression returns the array itself, so several appends may be chained together. See also #pop for the opposite effect.

a = [ "a", "b", "c" ]
a.push("d", "e", "f")
        #=> ["a", "b", "c", "d", "e", "f"]
[1, 2, 3].push(4).push(5)
        #=> [1, 2, 3, 4, 5]

[ GitHub ]

# File 'array.c', line 1234


static VALUE
rb_ary_push_m(int argc, VALUE *argv, VALUE ary)
{
    return rb_ary_cat(ary, argv, argc);
}

#rassoc(obj) ⇒ `element_ary`^?

Searches through the array whose elements are also arrays.

Compares obj with the second element of each contained array using obj.==.

Returns the first contained array that matches obj.

#reject {|item| ... } ⇒ `Array` #reject ⇒ Enumerator

Returns a new array containing the items in self for which the given block is not true. The ordering of non-rejected elements is maintained.

#reject! {|item| ... } ⇒ `Array`^? #reject! ⇒ Enumerator

Deletes every element of self for which the block evaluates to true, if no changes were made returns nil.

The array may not be changed instantly every time the block is called.

See also Enumerable#reject and #delete_if.

If no block is given, an ::Enumerator is returned instead.

[ GitHub ]

# File 'array.c', line 3588


static VALUE
rb_ary_reject_bang(VALUE ary)
{
    RETURN_SIZED_ENUMERATOR(ary, 0, 0, ary_enum_length);
    rb_ary_modify(ary);
    return ary_reject_bang(ary);
}

#repeated_combination(n) {|c| ... } ⇒ `Array` #repeated_combination(n) ⇒ Enumerator

When invoked with a block, yields all repeated combinations of length n of elements from the array and then returns the array itself.

The implementation makes no guarantees about the order in which the repeated combinations are yielded.

If no block is given, an ::Enumerator is returned instead.

Examples:

a = [1, 2, 3]
a.repeated_combination(1).to_a  #=> [[1], [2], [3]]
a.repeated_combination(2).to_a  #=> [[1,1],[1,2],[1,3],[2,2],[2,3],[3,3]]
a.repeated_combination(3).to_a  #=> [[1,1,1],[1,1,2],[1,1,3],[1,2,2],[1,2,3],
                                #    [1,3,3],[2,2,2],[2,2,3],[2,3,3],[3,3,3]]
a.repeated_combination(4).to_a  #=> [[1,1,1,1],[1,1,1,2],[1,1,1,3],[1,1,2,2],[1,1,2,3],
                                #    [1,1,3,3],[1,2,2,2],[1,2,2,3],[1,2,3,3],[1,3,3,3],
                                #    [2,2,2,2],[2,2,2,3],[2,2,3,3],[2,3,3,3],[3,3,3,3]]
a.repeated_combination(0).to_a  #=> [[]] # one combination of length 0

[ GitHub ]

# File 'array.c', line 6072


static VALUE
rb_ary_repeated_combination(VALUE ary, VALUE num)
{
    long n, i, len;

    n = NUM2LONG(num);                 /* Combination size from argument */
    RETURN_SIZED_ENUMERATOR(ary, 1, &num, rb_ary_repeated_combination_size);   /* Return enumerator if no block */
    len = RARRAY_LEN(ary);
    if (n < 0) {
	/* yield nothing */
    }
    else if (n == 0) {
	rb_yield(rb_ary_new2(0));
    }
    else if (n == 1) {
	for (i = 0; i < RARRAY_LEN(ary); i++) {
	    rb_yield(rb_ary_new3(1, RARRAY_AREF(ary, i)));
	}
    }
    else if (len == 0) {
	/* yield nothing */
    }
    else {
	volatile VALUE t0;
	long *p = ALLOCV_N(long, t0, n);
	VALUE ary0 = ary_make_shared_copy(ary); /* private defensive copy of ary */
	RBASIC_CLEAR_CLASS(ary0);

	rcombinate0(len, n, p, n, ary0); /* compute and yield repeated combinations */
	ALLOCV_END(t0);
	RBASIC_SET_CLASS_RAW(ary0, rb_cArray);
    }
    return ary;
}

#repeated_permutation(n) {|p| ... } ⇒ `Array` #repeated_permutation(n) ⇒ Enumerator

When invoked with a block, yield all repeated permutations of length n of the elements of the array, then return the array itself.

The implementation makes no guarantees about the order in which the repeated permutations are yielded.

If no block is given, an ::Enumerator is returned instead.

Examples:

a = [1, 2]
a.repeated_permutation(1).to_a  #=> [[1], [2]]
a.repeated_permutation(2).to_a  #=> [[1,1],[1,2],[2,1],[2,2]]
a.repeated_permutation(3).to_a  #=> [[1,1,1],[1,1,2],[1,2,1],[1,2,2],
                                #    [2,1,1],[2,1,2],[2,2,1],[2,2,2]]
a.repeated_permutation(0).to_a  #=> [[]] # one permutation of length 0

[ GitHub ]

# File 'array.c', line 5978


static VALUE
rb_ary_repeated_permutation(VALUE ary, VALUE num)
{
    long r, n, i;

    n = RARRAY_LEN(ary);                  /* Array length */
    RETURN_SIZED_ENUMERATOR(ary, 1, &num, rb_ary_repeated_permutation_size);      /* Return Enumerator if no block */
    r = NUM2LONG(num);                    /* Permutation size from argument */

    if (r < 0) {
	/* no permutations: yield nothing */
    }
    else if (r == 0) { /* exactly one permutation: the zero-length array */
	rb_yield(rb_ary_new2(0));
    }
    else if (r == 1) { /* this is a special, easy case */
	for (i = 0; i < RARRAY_LEN(ary); i++) {
	    rb_yield(rb_ary_new3(1, RARRAY_AREF(ary, i)));
	}
    }
    else {             /* this is the general case */
	volatile VALUE t0;
	long *p = ALLOCV_N(long, t0, r);
	VALUE ary0 = ary_make_shared_copy(ary); /* private defensive copy of ary */
	RBASIC_CLEAR_CLASS(ary0);

	rpermute0(n, r, p, ary0); /* compute and yield repeated permutations */
	ALLOCV_END(t0);
	RBASIC_SET_CLASS_RAW(ary0, rb_cArray);
    }
    return ary;
}

#replace(other_ary) ⇒ `Array` #initialize_copy(other_ary) ⇒ `Array`
Also known as: #initialize_copy

Replaces the contents of self with the contents of other_ary, truncating or expanding if necessary.

a = [ "a", "b", "c", "d", "e" ]
a.replace([ "x", "y", "z" ])   #=> ["x", "y", "z"]
a                              #=> ["x", "y", "z"]

[ GitHub ]

# File 'array.c', line 3810


VALUE
rb_ary_replace(VALUE copy, VALUE orig)
{
    rb_ary_modify_check(copy);
    orig = to_ary(orig);
    if (copy == orig) return copy;

    if (RARRAY_LEN(orig) <= RARRAY_EMBED_LEN_MAX) {
        VALUE shared_root = 0;

        if (ARY_OWNS_HEAP_P(copy)) {
            ary_heap_free(copy);
	}
        else if (ARY_SHARED_P(copy)) {
            shared_root = ARY_SHARED_ROOT(copy);
            FL_UNSET_SHARED(copy);
        }
        FL_SET_EMBED(copy);
        ary_memcpy(copy, 0, RARRAY_LEN(orig), RARRAY_CONST_PTR_TRANSIENT(orig));
        if (shared_root) {
            rb_ary_decrement_share(shared_root);
        }
        ARY_SET_LEN(copy, RARRAY_LEN(orig));
    }
    else {
        VALUE shared_root = ary_make_shared(orig);
        if (ARY_OWNS_HEAP_P(copy)) {
            ary_heap_free(copy);
        }
        else {
            rb_ary_unshare_safe(copy);
        }
        FL_UNSET_EMBED(copy);
        ARY_SET_PTR(copy, ARY_HEAP_PTR(orig));
        ARY_SET_LEN(copy, ARY_HEAP_LEN(orig));
        rb_ary_set_shared(copy, shared_root);
    }
    ary_verify(copy);
    return copy;
}

#reverse ⇒ `Array`

Returns a new array containing self‘s elements in reverse order.

[ "a", "b", "c" ].reverse   #=> ["c", "b", "a"]
[ 1 ].reverse               #=> [1]

[ GitHub ]

# File 'array.c', line 2586


static VALUE
rb_ary_reverse_m(VALUE ary)
{
    long len = RARRAY_LEN(ary);
    VALUE dup = rb_ary_new2(len);

    if (len > 0) {
        const VALUE *p1 = RARRAY_CONST_PTR_TRANSIENT(ary);
        VALUE *p2 = (VALUE *)RARRAY_CONST_PTR_TRANSIENT(dup) + len - 1;
	do *p2-- = *p1++; while (--len > 0);
    }
    ARY_SET_LEN(dup, RARRAY_LEN(ary));
    return dup;
}

#reverse! ⇒ `Array`

Reverses self in place.

a = [ "a", "b", "c" ]
a.reverse!       #=> ["c", "b", "a"]
a                #=> ["c", "b", "a"]

[ GitHub ]

# File 'array.c', line 2570


static VALUE
rb_ary_reverse_bang(VALUE ary)
{
    return rb_ary_reverse(ary);
}

#reverse_each {|item| ... } ⇒ `Array` #reverse_each ⇒ Enumerator

Same as #each, but traverses self in reverse order.

a = [ "a", "b", "c" ]
a.reverse_each {|x| print x, " " }

produces:

c b a

[ GitHub ]

# File 'array.c', line 2185


static VALUE
rb_ary_reverse_each(VALUE ary)
{
    long len;

    RETURN_SIZED_ENUMERATOR(ary, 0, 0, ary_enum_length);
    len = RARRAY_LEN(ary);
    while (len--) {
	long nlen;
	rb_yield(RARRAY_AREF(ary, len));
	nlen = RARRAY_LEN(ary);
	if (nlen < len) {
	    len = nlen;
	}
    }
    return ary;
}

#rindex(obj) ⇒ Integer^? #rindex {|item| ... } ⇒ Integer^? #rindex ⇒ Enumerator

Returns the index of the last object in self #== to obj.

If a block is given instead of an argument, returns the index of the first object for which the block returns true, starting from the last object.

Returns nil if no match is found.

#rotate(count = 1) ⇒ `Array`

Returns a new array by rotating self so that the element at #count is the first element of the new array.

If #count is negative then it rotates in the opposite direction, starting from the end of self where -1 is the last element.

a = [ "a", "b", "c", "d" ]
a.rotate         #=> ["b", "c", "d", "a"]
a                #=> ["a", "b", "c", "d"]
a.rotate(2)      #=> ["c", "d", "a", "b"]
a.rotate(-3)     #=> ["b", "c", "d", "a"]

[ GitHub ]

# File 'array.c', line 2673


static VALUE
rb_ary_rotate_m(int argc, VALUE *argv, VALUE ary)
{
    VALUE rotated;
    const VALUE *ptr;
    long len;
    long cnt = (rb_check_arity(argc, 0, 1) ? NUM2LONG(argv[0]) : 1);

    len = RARRAY_LEN(ary);
    rotated = rb_ary_new2(len);
    if (len > 0) {
	cnt = rotate_count(cnt, len);
        ptr = RARRAY_CONST_PTR_TRANSIENT(ary);
	len -= cnt;
	ary_memcpy(rotated, 0, len, ptr + cnt);
	ary_memcpy(rotated, len, cnt, ptr);
    }
    ARY_SET_LEN(rotated, RARRAY_LEN(ary));
    return rotated;
}

#rotate!(count = 1) ⇒ `Array`

Rotates self in place so that the element at #count comes first, and returns self.

If #count is negative then it rotates in the opposite direction, starting from the end of the array where -1 is the last element.

a = [ "a", "b", "c", "d" ]
a.rotate!        #=> ["b", "c", "d", "a"]
a                #=> ["b", "c", "d", "a"]
a.rotate!(2)     #=> ["d", "a", "b", "c"]
a.rotate!(-3)    #=> ["a", "b", "c", "d"]

[ GitHub ]

# File 'array.c', line 2648


static VALUE
rb_ary_rotate_bang(int argc, VALUE *argv, VALUE ary)
{
    long n = (rb_check_arity(argc, 0, 1) ? NUM2LONG(argv[0]) : 1);
    rb_ary_rotate(ary, n);
    return ary;
}

#sample ⇒ Object #sample(random: rng) ⇒ Object #sample(n) ⇒ `Array` #sample(n, random: rng) ⇒ `Array`

Choose a random element or n random elements from the array.

The elements are chosen by using random and unique indices into the array in order to ensure that an element doesn’t repeat itself unless the array already contained duplicate elements.

If the array is empty the first form returns nil and the second form returns an empty array.

a = [ 1, 2, 3, 4, 5, 6, 7, 8, 9, 10 ]
a.sample         #=> 7
a.sample(4)      #=> [6, 4, 2, 5]

The optional rng argument will be used as the random number generator.

a.sample(random: Random.new(1))     #=> 6
a.sample(4, random: Random.new(1))  #=> [6, 10, 9, 2]

[ GitHub ]

# File 'array.c', line 5431


static VALUE
rb_ary_sample(int argc, VALUE *argv, VALUE ary)
{
    VALUE nv, result;
    VALUE opts, randgen = rb_cRandom;
    long n, len, i, j, k, idx[10];
    long rnds[numberof(idx)];
    long memo_threshold;

    if (OPTHASH_GIVEN_P(opts)) {
	VALUE rnd;
	ID keyword_ids[1];

	keyword_ids[0] = id_random;
	rb_get_kwargs(opts, keyword_ids, 0, 1, &rnd);
	if (rnd != Qundef) {
	    randgen = rnd;
	}
    }
    len = RARRAY_LEN(ary);
    if (rb_check_arity(argc, 0, 1) == 0) {
	if (len < 2)
	    i = 0;
	else
	    i = RAND_UPTO(len);

	return rb_ary_elt(ary, i);
    }
    nv = argv[0];
    n = NUM2LONG(nv);
    if (n < 0) rb_raise(rb_eArgError, "negative sample number");
    if (n > len) n = len;
    if (n <= numberof(idx)) {
	for (i = 0; i < n; ++i) {
	    rnds[i] = RAND_UPTO(len - i);
	}
    }
    k = len;
    len = RARRAY_LEN(ary);
    if (len < k && n <= numberof(idx)) {
	for (i = 0; i < n; ++i) {
	    if (rnds[i] >= len) return rb_ary_new_capa(0);
	}
    }
    if (n > len) n = len;
    switch (n) {
      case 0:
	return rb_ary_new_capa(0);
      case 1:
	i = rnds[0];
	return rb_ary_new_from_values(1, &RARRAY_AREF(ary, i));
      case 2:
	i = rnds[0];
	j = rnds[1];
	if (j >= i) j++;
	return rb_ary_new_from_args(2, RARRAY_AREF(ary, i), RARRAY_AREF(ary, j));
      case 3:
	i = rnds[0];
	j = rnds[1];
	k = rnds[2];
	{
	    long l = j, g = i;
	    if (j >= i) l = i, g = ++j;
	    if (k >= l && (++k >= g)) ++k;
	}
	return rb_ary_new_from_args(3, RARRAY_AREF(ary, i), RARRAY_AREF(ary, j), RARRAY_AREF(ary, k));
    }
    memo_threshold =
	len < 2560 ? len / 128 :
	len < 5120 ? len / 64 :
	len < 10240 ? len / 32 :
	len / 16;
    if (n <= numberof(idx)) {
	long sorted[numberof(idx)];
	sorted[0] = idx[0] = rnds[0];
	for (i=1; i<n; i++) {
	    k = rnds[i];
	    for (j = 0; j < i; ++j) {
		if (k < sorted[j]) break;
		++k;
	    }
	    memmove(&sorted[j+1], &sorted[j], sizeof(sorted[0])*(i-j));
	    sorted[j] = idx[i] = k;
	}
	result = rb_ary_new_capa(n);
        RARRAY_PTR_USE_TRANSIENT(result, ptr_result, {
	    for (i=0; i<n; i++) {
		ptr_result[i] = RARRAY_AREF(ary, idx[i]);
	    }
	});
    }
    else if (n <= memo_threshold / 2) {
	long max_idx = 0;
#undef RUBY_UNTYPED_DATA_WARNING
#define RUBY_UNTYPED_DATA_WARNING 0
	VALUE vmemo = Data_Wrap_Struct(0, 0, st_free_table, 0);
	st_table *memo = st_init_numtable_with_size(n);
	DATA_PTR(vmemo) = memo;
	result = rb_ary_new_capa(n);
	RARRAY_PTR_USE(result, ptr_result, {
	    for (i=0; i<n; i++) {
		long r = RAND_UPTO(len-i) + i;
		ptr_result[i] = r;
		if (r > max_idx) max_idx = r;
	    }
	    len = RARRAY_LEN(ary);
	    if (len <= max_idx) n = 0;
	    else if (n > len) n = len;
            RARRAY_PTR_USE_TRANSIENT(ary, ptr_ary, {
		for (i=0; i<n; i++) {
		    long j2 = j = ptr_result[i];
		    long i2 = i;
		    st_data_t value;
		    if (st_lookup(memo, (st_data_t)i, &value)) i2 = (long)value;
		    if (st_lookup(memo, (st_data_t)j, &value)) j2 = (long)value;
		    st_insert(memo, (st_data_t)j, (st_data_t)i2);
		    ptr_result[i] = ptr_ary[j2];
		}
	    });
	});
	DATA_PTR(vmemo) = 0;
	st_free_table(memo);
    }
    else {
	result = rb_ary_dup(ary);
	RBASIC_CLEAR_CLASS(result);
	RB_GC_GUARD(ary);
	RARRAY_PTR_USE(result, ptr_result, {
	    for (i=0; i<n; i++) {
		j = RAND_UPTO(len-i) + i;
		nv = ptr_result[j];
		ptr_result[j] = ptr_result[i];
		ptr_result[i] = nv;
	    }
	});
	RBASIC_SET_CLASS_RAW(result, rb_cArray);
    }
    ARY_SET_LEN(result, n);

    return result;
}

#select {|item| ... } ⇒ `Array` #select ⇒ Enumerator #filter {|item| ... } ⇒ `Array` #filter ⇒ Enumerator

Alias for #filter.

#select! {|item| ... } ⇒ `Array`^? #select! ⇒ Enumerator #filter! {|item| ... } ⇒ `Array`^? #filter! ⇒ Enumerator

Alias for #filter!.

#shift ⇒ Object^? #shift(n) ⇒ `Array`

Removes the first element of self and returns it (shifting all other elements down by one). Returns nil if the array is empty.

If a number n is given, returns an array of the first n elements (or less) just like array.slice!(0, n) does. With ary containing only the remainder elements, not including what was shifted to new_ary. See also #unshift for the opposite effect.

args = [ "-m", "-q", "filename" ]
args.shift     #=> "-m"
args           #=> ["-q", "filename"]

args = [ "-m", "-q", "filename" ]
args.shift(2)  #=> ["-m", "-q"]
args           #=> ["filename"]

[ GitHub ]

# File 'array.c', line 1350


static VALUE
rb_ary_shift_m(int argc, VALUE *argv, VALUE ary)
{
    VALUE result;
    long n;

    if (argc == 0) {
	return rb_ary_shift(ary);
    }

    rb_ary_modify_check(ary);
    result = ary_take_first_or_last(argc, argv, ary, ARY_TAKE_FIRST);
    n = RARRAY_LEN(result);
    rb_ary_behead(ary,n);

    return result;
}

#shuffle ⇒ `Array` #shuffle(random: rng) ⇒ `Array`

Returns a new array with elements of self shuffled.

a = [ 1, 2, 3 ]           #=> [1, 2, 3]
a.shuffle                 #=> [2, 3, 1]
a                         #=> [1, 2, 3]

The optional rng argument will be used as the random number generator.

a.shuffle(random: Random.new(1))  #=> [1, 3, 2]

[ GitHub ]

# File 'array.c', line 5395


static VALUE
rb_ary_shuffle(int argc, VALUE *argv, VALUE ary)
{
    ary = rb_ary_dup(ary);
    rb_ary_shuffle_bang(argc, argv, ary);
    return ary;
}

#shuffle! ⇒ `Array` #shuffle!(random: rng) ⇒ `Array`

Shuffles elements in self in place.

a = [ 1, 2, 3 ]           #=> [1, 2, 3]
a.shuffle!                #=> [2, 3, 1]
a                         #=> [2, 3, 1]

The optional rng argument will be used as the random number generator.

a.shuffle!(random: Random.new(1))  #=> [1, 3, 2]

[ GitHub ]

# File 'array.c', line 5344


static VALUE
rb_ary_shuffle_bang(int argc, VALUE *argv, VALUE ary)
{
    VALUE opts, randgen = rb_cRandom;
    long i, len;

    if (OPTHASH_GIVEN_P(opts)) {
	VALUE rnd;
	ID keyword_ids[1];

	keyword_ids[0] = id_random;
	rb_get_kwargs(opts, keyword_ids, 0, 1, &rnd);
	if (rnd != Qundef) {
	    randgen = rnd;
	}
    }
    rb_check_arity(argc, 0, 0);
    rb_ary_modify(ary);
    i = len = RARRAY_LEN(ary);
    RARRAY_PTR_USE(ary, ptr, {
	while (i) {
	    long j = RAND_UPTO(i);
	    VALUE tmp;
            if (len != RARRAY_LEN(ary) || ptr != RARRAY_CONST_PTR_TRANSIENT(ary)) {
                rb_raise(rb_eRuntimeError, "modified during shuffle");
	    }
	    tmp = ptr[--i];
	    ptr[i] = ptr[j];
	    ptr[j] = tmp;
	}
    }); /* WB: no new reference */
    return ary;
}

#length ⇒ Integer #size ⇒ Integer

Alias for #length.

#[](index) ⇒ Object^? #[](start, length) ⇒ `Array`^? #[](range) ⇒ `Array`^? #slice(index) ⇒ Object^? #slice(start, length) ⇒ `Array`^? #slice(range) ⇒ `Array`^?

Alias for #[].

#slice!(index) ⇒ Object^? #slice!(start, length) ⇒ `Array`^? #slice!(range) ⇒ `Array`^?

Deletes the element(s) given by an #index (optionally up to #length elements) or by a range.

Returns the deleted object (or objects), or nil if the #index is out of range.

a = [ "a", "b", "c" ]
a.slice!(1)     #=> "b"
a               #=> ["a", "c"]
a.slice!(-1)    #=> "c"
a               #=> ["a"]
a.slice!(100)   #=> nil
a               #=> ["a"]

[ GitHub ]

# File 'array.c', line 3482


static VALUE
rb_ary_slice_bang(int argc, VALUE *argv, VALUE ary)
{
    VALUE arg1, arg2;
    long pos, len, orig_len;

    rb_ary_modify_check(ary);
    if (argc == 2) {
	pos = NUM2LONG(argv[0]);
	len = NUM2LONG(argv[1]);
      delete_pos_len:
	if (len < 0) return Qnil;
	orig_len = RARRAY_LEN(ary);
	if (pos < 0) {
	    pos += orig_len;
	    if (pos < 0) return Qnil;
	}
	else if (orig_len < pos) return Qnil;
	if (orig_len < pos + len) {
	    len = orig_len - pos;
	}
	if (len == 0) return rb_ary_new2(0);
        arg2 = rb_ary_new4(len, RARRAY_CONST_PTR_TRANSIENT(ary)+pos);
	RBASIC_SET_CLASS(arg2, rb_obj_class(ary));
	rb_ary_splice(ary, pos, len, 0, 0);
	return arg2;
    }

    rb_check_arity(argc, 1, 2);
    arg1 = argv[0];

    if (!FIXNUM_P(arg1)) {
	switch (rb_range_beg_len(arg1, &pos, &len, RARRAY_LEN(ary), 0)) {
	  case Qtrue:
	    /* valid range */
	    goto delete_pos_len;
	  case Qnil:
	    /* invalid range */
	    return Qnil;
	  default:
	    /* not a range */
	    break;
	}
    }

    return rb_ary_delete_at(ary, NUM2LONG(arg1));
}

#sort ⇒ `Array` #sort {|a, b| ... } ⇒ `Array`

Returns a new array created by sorting self.

Comparisons for the sort will be done using the #<=> operator or using an optional code block.

The block must implement a comparison between a and b and return an integer less than 0 when b follows a, 0 when a and b are equivalent, or an integer greater than 0 when a follows b.

The result is not guaranteed to be stable. When the comparison of two elements returns 0, the order of the elements is unpredictable.

ary = [ "d", "a", "e", "c", "b" ]
ary.sort                     #=> ["a", "b", "c", "d", "e"]
ary.sort {|a, b| b <=> a}    #=> ["e", "d", "c", "b", "a"]

To produce the reverse order, the following can also be used (and may be faster):

ary.sort.reverse!             #=> ["e", "d", "c", "b", "a"]

#sort! ⇒ `Array` #sort! {|a, b| ... } ⇒ `Array`

Sorts self in place.

Comparisons for the sort will be done using the #<=> operator or using an optional code block.

The result is not guaranteed to be stable. When the comparison of two elements returns 0, the order of the elements is unpredictable.

ary = [ "d", "a", "e", "c", "b" ]
ary.sort!                     #=> ["a", "b", "c", "d", "e"]
ary.sort! {|a, b| b <=> a}    #=> ["e", "d", "c", "b", "a"]

#sort_by! {|obj| ... } ⇒ `Array` #sort_by! ⇒ Enumerator

Sorts self in place using a set of keys generated by mapping the values in self through the given block.

The result is not guaranteed to be stable. When two keys are equal, the order of the corresponding elements is unpredictable.

If no block is given, an ::Enumerator is returned instead.

#sum(init = 0) ⇒ Numeric #sum(init = 0) {|e| ... } ⇒ Numeric

Returns the sum of elements. For example, [e1, e2, e3].sum returns init + e1 + e2 + e3.

If a block is given, the block is applied to each element before addition.

If ary is empty, it returns init.

[].sum                             #=> 0
[].sum(0.0)                        #=> 0.0
[1, 2, 3].sum                      #=> 6
[3, 5.5].sum                       #=> 8.5
[2.5, 3.0].sum(0.0) {|e| e * e }   #=> 15.25
[Object.new].sum                   #=> TypeError

The (arithmetic) mean value of an array can be obtained as follows.

mean = ary.sum(0.0) / ary.length

This method can be used for non-numeric objects by explicit init argument.

["a", "b", "c"].sum("")            #=> "abc"
[[1], [[2]], [3]].sum([])          #=> [1, [2], 3]

However, #join and #flatten is faster than sum for array of strings and array of arrays.

["a", "b", "c"].join               #=> "abc"
[[1], [[2]], [3]].flatten(1)       #=> [1, [2], 3]

sum method may not respect method redefinition of “+” methods such as Integer#+.

[ GitHub ]

# File 'array.c', line 6572


static VALUE
rb_ary_sum(int argc, VALUE *argv, VALUE ary)
{
    VALUE e, v, r;
    long i, n;
    int block_given;

    v = (rb_check_arity(argc, 0, 1) ? argv[0] : LONG2FIX(0));

    block_given = rb_block_given_p();

    if (RARRAY_LEN(ary) == 0)
        return v;

    n = 0;
    r = Qundef;
    for (i = 0; i < RARRAY_LEN(ary); i++) {
        e = RARRAY_AREF(ary, i);
        if (block_given)
            e = rb_yield(e);
        if (FIXNUM_P(e)) {
            n += FIX2LONG(e); /* should not overflow long type */
            if (!FIXABLE(n)) {
                v = rb_big_plus(LONG2NUM(n), v);
                n = 0;
            }
        }
        else if (RB_TYPE_P(e, T_BIGNUM))
            v = rb_big_plus(e, v);
        else if (RB_TYPE_P(e, T_RATIONAL)) {
            if (r == Qundef)
                r = e;
            else
                r = rb_rational_plus(r, e);
        }
        else
            goto not_exact;
    }
    v = finish_exact_sum(n, r, v, argc!=0);
    return v;

  not_exact:
    v = finish_exact_sum(n, r, v, i!=0);

    if (RB_FLOAT_TYPE_P(e)) {
        /*
         * Kahan-Babuska balancing compensated summation algorithm
         * See http://link.springer.com/article/10.1007/s00607-005-0139-x
         */
        double f, c;
        double x, t;

        f = NUM2DBL(v);
        c = 0.0;
        goto has_float_value;
        for (; i < RARRAY_LEN(ary); i++) {
            e = RARRAY_AREF(ary, i);
            if (block_given)
                e = rb_yield(e);
            if (RB_FLOAT_TYPE_P(e))
              has_float_value:
                x = RFLOAT_VALUE(e);
            else if (FIXNUM_P(e))
                x = FIX2LONG(e);
            else if (RB_TYPE_P(e, T_BIGNUM))
                x = rb_big2dbl(e);
            else if (RB_TYPE_P(e, T_RATIONAL))
                x = rb_num2dbl(e);
            else
                goto not_float;

            if (isnan(f)) continue;
            if (isnan(x)) {
                f = x;
                continue;
            }
            if (isinf(x)) {
                if (isinf(f) && signbit(x) != signbit(f))
                    f = NAN;
                else
                    f = x;
                continue;
            }
            if (isinf(f)) continue;

            t = f + x;
            if (fabs(f) >= fabs(x))
                c += ((f - t) + x);
            else
                c += ((x - t) + f);
            f = t;
        }
        f += c;
        return DBL2NUM(f);

      not_float:
        v = DBL2NUM(f);
    }

    goto has_some_value;
    for (; i < RARRAY_LEN(ary); i++) {
        e = RARRAY_AREF(ary, i);
        if (block_given)
            e = rb_yield(e);
      has_some_value:
        v = rb_funcall(v, idPLUS, 1, e);
    }
    return v;
}

#take(n) ⇒ `Array`

Returns first n elements from the array.

If a negative number is given, raises an ::ArgumentError.

#take_while {|obj| ... } ⇒ `Array` #take_while ⇒ Enumerator

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 instead.

#to_a ⇒ `Array`

Returns self.

If called on a subclass of Array, converts the receiver to an Array object.

[ GitHub ]

# File 'array.c', line 2467


static VALUE
rb_ary_to_a(VALUE ary)
{
    if (rb_obj_class(ary) != rb_cArray) {
	VALUE dup = rb_ary_new2(RARRAY_LEN(ary));
	rb_ary_replace(dup, ary);
	return dup;
    }
    return ary;
}

#to_ary ⇒ `Array`

Returns self.

[ GitHub ]

# File 'array.c', line 2527


static VALUE
rb_ary_to_ary_m(VALUE ary)
{
    return ary;
}

#to_h ⇒ Hash #to_h {|item| ... } ⇒ Hash

Returns the result of interpreting ary as an array of [key, value] pairs.

[[:foo, :bar], [1, 2]].to_h
  # => {:foo => :bar, 1 => 2}

If a block is given, the results of the block on each element of the array will be used as pairs.

["foo", "bar"].to_h {|s| [s.ord, s]}
  # => {102=>"foo", 98=>"bar"}

[ GitHub ]

# File 'array.c', line 2496


static VALUE
rb_ary_to_h(VALUE ary)
{
    long i;
    VALUE hash = rb_hash_new_with_size(RARRAY_LEN(ary));
    int block_given = rb_block_given_p();

    for (i=0; i<RARRAY_LEN(ary); i++) {
	const VALUE e = rb_ary_elt(ary, i);
	const VALUE elt = block_given ? rb_yield_force_blockarg(e) : e;
	const VALUE key_value_pair = rb_check_array_type(elt);
	if (NIL_P(key_value_pair)) {
	    rb_raise(rb_eTypeError, "wrong element type %"PRIsVALUE" at %ld (expected array)",
		     rb_obj_class(elt), i);
	}
	if (RARRAY_LEN(key_value_pair) != 2) {
	    rb_raise(rb_eArgError, "wrong array length at %ld (expected 2, was %ld)",
		i, RARRAY_LEN(key_value_pair));
	}
	rb_hash_aset(hash, RARRAY_AREF(key_value_pair, 0), RARRAY_AREF(key_value_pair, 1));
    }
    return hash;
}

#inspect ⇒ String #to_s ⇒ String
Also known as: #inspect

Creates a string representation of self, by calling #inspect on each element.

[ "a", "b", "c" ].to_s     #=> "[\"a\", \"b\", \"c\"]"

[ GitHub ]

# File 'array.c', line 2445


static VALUE
rb_ary_inspect(VALUE ary)
{
    if (RARRAY_LEN(ary) == 0) return rb_usascii_str_new2("[]");
    return rb_exec_recursive(inspect_ary, ary, 0);
}

#transpose ⇒ `Array`

Assumes that self is an array of arrays and transposes the rows and columns.

a = [[1,2], [3,4], [5,6]]
a.transpose   #=> [[1, 3, 5], [2, 4, 6]]

If the length of the subarrays don’t match, an ::IndexError is raised.

[ GitHub ]

# File 'array.c', line 3769


static VALUE
rb_ary_transpose(VALUE ary)
{
    long elen = -1, alen, i, j;
    VALUE tmp, result = 0;

    alen = RARRAY_LEN(ary);
    if (alen == 0) return rb_ary_dup(ary);
    for (i=0; i<alen; i++) {
	tmp = to_ary(rb_ary_elt(ary, i));
	if (elen < 0) {		/* first element */
	    elen = RARRAY_LEN(tmp);
	    result = rb_ary_new2(elen);
	    for (j=0; j<elen; j++) {
		rb_ary_store(result, j, rb_ary_new2(alen));
	    }
	}
	else if (elen != RARRAY_LEN(tmp)) {
	    rb_raise(rb_eIndexError, "element size differs (%ld should be %ld)",
		     RARRAY_LEN(tmp), elen);
	}
	for (j=0; j<elen; j++) {
	    rb_ary_store(rb_ary_elt(result, j), i, rb_ary_elt(tmp, j));
	}
    }
    return result;
}

#union(other_ary1, other_ary2, ...) ⇒ `Array`

Set Union — Returns a new array by joining other_arys with self, excluding any duplicates and preserving the order from the given arrays.

It compares elements using their #hash and #eql? methods for efficiency.

[ "a", "b", "c" ].union( [ "c", "d", "a" ] )    #=> [ "a", "b", "c", "d" ]
[ "a" ].union( ["e", "b"], ["a", "c", "b"] )    #=> [ "a", "e", "b", "c" ]
[ "a" ].union #=> [ "a" ]

#uniq ⇒ `Array` #uniq {|item| ... } ⇒ `Array`

Returns a new array by removing duplicate values in self.

If a block is given, it will use the return value of the block for comparison.

It compares values using their #hash and #eql? methods for efficiency.

self is traversed in order, and the first occurrence is kept.

a = [ "a", "a", "b", "b", "c" ]
a.uniq   # => ["a", "b", "c"]

b = [["student","sam"], ["student","george"], ["teacher","matz"]]
b.uniq {|s| s.first}   # => [["student", "sam"], ["teacher", "matz"]]

[ GitHub ]

# File 'array.c', line 5018


static VALUE
rb_ary_uniq(VALUE ary)
{
    VALUE hash, uniq;

    if (RARRAY_LEN(ary) <= 1) {
        hash = 0;
        uniq = rb_ary_dup(ary);
    }
    else if (rb_block_given_p()) {
	hash = ary_make_hash_by(ary);
	uniq = rb_hash_values(hash);
    }
    else {
	hash = ary_make_hash(ary);
	uniq = rb_hash_values(hash);
    }
    RBASIC_SET_CLASS(uniq, rb_obj_class(ary));
    if (hash) {
        ary_recycle_hash(hash);
    }

    return uniq;
}

#uniq! ⇒ `Array`^? #uniq! {|item| ... } ⇒ `Array`^?

Removes duplicate elements from self.

If a block is given, it will use the return value of the block for comparison.

It compares values using their #hash and #eql? methods for efficiency.

self is traversed in order, and the first occurrence is kept.

Returns nil if no changes are made (that is, no duplicates are found).

a = [ "a", "a", "b", "b", "c" ]
a.uniq!   # => ["a", "b", "c"]

b = [ "a", "b", "c" ]
b.uniq!   # => nil

c = [["student","sam"], ["student","george"], ["teacher","matz"]]
c.uniq! {|s| s.first}   # => [["student", "sam"], ["teacher", "matz"]]

[ GitHub ]

# File 'array.c', line 4966


static VALUE
rb_ary_uniq_bang(VALUE ary)
{
    VALUE hash;
    long hash_size;

    rb_ary_modify_check(ary);
    if (RARRAY_LEN(ary) <= 1)
        return Qnil;
    if (rb_block_given_p())
	hash = ary_make_hash_by(ary);
    else
	hash = ary_make_hash(ary);

    hash_size = RHASH_SIZE(hash);
    if (RARRAY_LEN(ary) == hash_size) {
	return Qnil;
    }
    rb_ary_modify_check(ary);
    ARY_SET_LEN(ary, 0);
    if (ARY_SHARED_P(ary) && !ARY_EMBED_P(ary)) {
	rb_ary_unshare(ary);
	FL_SET_EMBED(ary);
    }
    ary_resize_capa(ary, hash_size);
    rb_hash_foreach(hash, push_value, ary);
    ary_recycle_hash(hash);

    return ary;
}

#unshift(obj, ...) ⇒ `Array` #prepend(obj, ...) ⇒ `Array`

Alias for #prepend.

#values_at(selector, ...) ⇒ `Array`

Returns an array containing the elements in self corresponding to the given selector(s).

The selectors may be either integer indices or ranges.

#zip(arg, ...) ⇒ `Array` #zip(arg, ...) {|arr| ... } ⇒ `nil`

Converts any arguments to arrays, then merges elements of self with corresponding elements from each argument.

This generates a sequence of ary.size n-element arrays, where n is one more than the count of arguments.

If the size of any argument is less than the size of the initial array, nil values are supplied.

If a block is given, it is invoked for each output array, otherwise an array of arrays is returned.

a = [ 4, 5, 6 ]
b = [ 7, 8, 9 ]
[1, 2, 3].zip(a, b)   #=> [[1, 4, 7], [2, 5, 8], [3, 6, 9]]
[1, 2].zip(a, b)      #=> [[1, 4, 7], [2, 5, 8]]
a.zip([1, 2], [8])    #=> [[4, 1, 8], [5, 2, nil], [6, nil, nil]]

[ GitHub ]

# File 'array.c', line 3698


static VALUE
rb_ary_zip(int argc, VALUE *argv, VALUE ary)
{
    int i, j;
    long len = RARRAY_LEN(ary);
    VALUE result = Qnil;

    for (i=0; i<argc; i++) {
	argv[i] = take_items(argv[i], len);
    }

    if (rb_block_given_p()) {
	int arity = rb_block_arity();

	if (arity > 1) {
	    VALUE work, *tmp;

	    tmp = ALLOCV_N(VALUE, work, argc+1);

	    for (i=0; i<RARRAY_LEN(ary); i++) {
		tmp[0] = RARRAY_AREF(ary, i);
		for (j=0; j<argc; j++) {
		    tmp[j+1] = rb_ary_elt(argv[j], i);
		}
		rb_yield_values2(argc+1, tmp);
	    }

	    if (work) ALLOCV_END(work);
	}
	else {
	    for (i=0; i<RARRAY_LEN(ary); i++) {
		VALUE tmp = rb_ary_new2(argc+1);

		rb_ary_push(tmp, RARRAY_AREF(ary, i));
		for (j=0; j<argc; j++) {
		    rb_ary_push(tmp, rb_ary_elt(argv[j], i));
		}
		rb_yield(tmp);
	    }
	}
    }
    else {
	result = rb_ary_new_capa(len);

	for (i=0; i<len; i++) {
	    VALUE tmp = rb_ary_new_capa(argc+1);

	    rb_ary_push(tmp, RARRAY_AREF(ary, i));
	    for (j=0; j<argc; j++) {
		rb_ary_push(tmp, rb_ary_elt(argv[j], i));
	    }
	    rb_ary_push(result, tmp);
	}
    }

    return result;
}

#|(other_ary) ⇒ `Array`

Set Union — Returns a new array by joining ary with other_ary, excluding any duplicates and preserving the order from the given arrays.

It compares elements using their #hash and #eql? methods for efficiency.

[ "a", "b", "c" ] | [ "c", "d", "a" ]    #=> [ "a", "b", "c", "d" ]
[ "c", "d", "a" ] | [ "a", "b", "c" ]    #=> [ "c", "d", "a", "b" ]

Class: Array

Overview

Creating Arrays

Example Usage

Accessing Elements

Obtaining Information about an Array

Adding Items to Arrays

Removing Items from an Array

Iterating over Arrays

Selecting Items from an Array

Non-destructive Selection

Destructive Selection

Class Method Summary

Instance Attribute Summary

Instance Method Summary

::Enumerable - Included

Constructor Details

.new(size = 0, default = nil) .new(array) .new(size) {|index| ... }

Common gotchas

Class Method Details

.[](*args)

.try_convert(obj) ⇒ Array?

Instance Attribute Details

#empty? ⇒ Boolean (readonly)

Instance Method Details

#&(other_ary) ⇒ Array

#*(int) ⇒ Array #*(str) ⇒ String

#+(other_ary) ⇒ Array

#-(other_ary) ⇒ Array

#<<(obj) ⇒ Array

#<=>(other_ary) ⇒ 1, ...

#==(other_ary) ⇒ Boolean

#[](index) ⇒ Object? #[](start, length) ⇒ Array? #[](range) ⇒ Array? #slice(index) ⇒ Object? #slice(start, length) ⇒ Array? #slice(range) ⇒ Array? Also known as: #slice

#[]=(index, obj) ⇒ Object #[]=(start, length, obj or other_ary or nil) ⇒ Object, ... #[]=(range, obj or other_ary or nil) ⇒ Object, ...

#all? {|obj| ... } ⇒ Boolean #all? ⇒ Boolean #all?(pattern) ⇒ Boolean

#any? {|obj| ... } ⇒ Boolean #any? ⇒ Boolean #any?(pattern) ⇒ Boolean

#push(obj, ...) ⇒ Array #append(obj, ...) ⇒ Array

#assoc(obj) ⇒ element_ary?

#at(index) ⇒ Object?

#bsearch {|x| ... } ⇒ elem

#bsearch_index {|x| ... } ⇒ Integer?

#clear ⇒ Array

#collect {|item| ... } ⇒ Array #map {|item| ... } ⇒ Array #collect ⇒ Enumerator #map ⇒ Enumerator

#collect! {|item| ... } ⇒ Array #map! {|item| ... } ⇒ Array #collect! ⇒ Enumerator #map! ⇒ Enumerator

#combination(n) {|c| ... } ⇒ Array #combination(n) ⇒ Enumerator

#compact ⇒ Array

#compact! ⇒ Array?

#concat(other_ary1, other_ary2, ...) ⇒ Array

#count ⇒ Integer #count(obj) ⇒ Integer #count {|item| ... } ⇒ Integer

#cycle(n = nil) {|obj| ... } ⇒ nil #cycle(n = nil) ⇒ Enumerator

#deconstruct

#delete(obj) ⇒ item? #delete(obj) ⇒ item, result of block

#delete_at(index) ⇒ Object?

#delete_if {|item| ... } ⇒ Array #delete_if ⇒ Enumerator

#difference(other_ary1, other_ary2, ...) ⇒ Array

#dig(idx, ...) ⇒ Object

#drop(n) ⇒ Array

#drop_while {|obj| ... } ⇒ Array #drop_while ⇒ Enumerator

#each {|item| ... } ⇒ Array #each ⇒ Enumerator

#each_index {|index| ... } ⇒ Array #each_index ⇒ Enumerator

#eql?(other) ⇒ Boolean

#fetch(index) ⇒ Object #fetch(index, default) ⇒ Object #fetch(index) {|index| ... } ⇒ Object

#fill(obj) ⇒ Array #fill(obj, start [, length]) ⇒ Array #fill(obj, range) ⇒ Array #fill {|index| ... } ⇒ Array #fill(start [, length]) {|index| ... } ⇒ Array #fill(range) {|index| ... } ⇒ Array

#select {|item| ... } ⇒ Array #select ⇒ Enumerator #filter {|item| ... } ⇒ Array #filter ⇒ Enumerator Also known as: #select

#select! {|item| ... } ⇒ Array? #select! ⇒ Enumerator #filter! {|item| ... } ⇒ Array? #filter! ⇒ Enumerator Also known as: #select!

#find_index(obj) ⇒ Integer? #find_index {|item| ... } ⇒ Integer? #find_index ⇒ Enumerator #index(obj) ⇒ Integer? #index {|item| ... } ⇒ Integer? #index ⇒ Enumerator

#first ⇒ Object? #first(n) ⇒ Array

#flatten ⇒ Array #flatten(level) ⇒ Array

#flatten! ⇒ Array? #flatten!(level) ⇒ Array?

#hash ⇒ Integer

#include?(object) ⇒ Boolean

#find_index(obj) ⇒ Integer? #find_index {|item| ... } ⇒ Integer? #find_index ⇒ Enumerator #index(obj) ⇒ Integer? #index {|item| ... } ⇒ Integer? #index ⇒ Enumerator Also known as: #find_index

#replace(other_ary) ⇒ Array #initialize_copy(other_ary) ⇒ Array

#insert(index, obj...) ⇒ Array

#inspect ⇒ String #to_s ⇒ String

#intersection(other_ary1, other_ary2, ...) ⇒ Array

#join(separator = $,) ⇒ String

#keep_if {|item| ... } ⇒ Array #keep_if ⇒ Enumerator

#last ⇒ Object? #last(n) ⇒ Array

#length ⇒ Integer Also known as: #size

`::Enumerable` - Included

.try_convert(obj) ⇒ `Array`^?

#empty? ⇒ `Boolean` (readonly)

#&(other_ary) ⇒ `Array`

#(int) ⇒ `Array` #(str) ⇒ String

#+(other_ary) ⇒ `Array`

#-(other_ary) ⇒ `Array`

#<<(obj) ⇒ `Array`

#<=>(other_ary) ⇒ `1`, ...

#==(other_ary) ⇒ `Boolean`

#[](index) ⇒ Object^? #[](start, length) ⇒ `Array`^? #[](range) ⇒ `Array`^? #slice(index) ⇒ Object^? #slice(start, length) ⇒ `Array`^? #slice(range) ⇒ `Array`^?
Also known as: #slice

#all? {|obj| ... } ⇒ `Boolean` #all? ⇒ `Boolean` #all?(pattern) ⇒ `Boolean`

#any? {|obj| ... } ⇒ `Boolean` #any? ⇒ `Boolean` #any?(pattern) ⇒ `Boolean`

#push(obj, ...) ⇒ `Array` #append(obj, ...) ⇒ `Array`

#assoc(obj) ⇒ `element_ary`^?

#at(index) ⇒ Object^?

#bsearch {|x| ... } ⇒ `elem`

#bsearch_index {|x| ... } ⇒ Integer^?

#clear ⇒ `Array`

#collect {|item| ... } ⇒ `Array` #map {|item| ... } ⇒ `Array` #collect ⇒ Enumerator #map ⇒ Enumerator

#collect! {|item| ... } ⇒ `Array` #map! {|item| ... } ⇒ `Array` #collect! ⇒ Enumerator #map! ⇒ Enumerator

#combination(n) {|c| ... } ⇒ `Array` #combination(n) ⇒ Enumerator

#compact ⇒ `Array`

#compact! ⇒ `Array`^?

#concat(other_ary1, other_ary2, ...) ⇒ `Array`

#cycle(n = nil) {|obj| ... } ⇒ `nil` #cycle(n = nil) ⇒ Enumerator

#delete(obj) ⇒ `item`^? #delete(obj) ⇒ `item`, `result` `of` `block`

#delete_at(index) ⇒ Object^?

#delete_if {|item| ... } ⇒ `Array` #delete_if ⇒ Enumerator

#difference(other_ary1, other_ary2, ...) ⇒ `Array`

#drop(n) ⇒ `Array`

#drop_while {|obj| ... } ⇒ `Array` #drop_while ⇒ Enumerator

#each {|item| ... } ⇒ `Array` #each ⇒ Enumerator

#each_index {|index| ... } ⇒ `Array` #each_index ⇒ Enumerator

#eql?(other) ⇒ `Boolean`

#fill(obj) ⇒ `Array` #fill(obj, start [, length]) ⇒ `Array` #fill(obj, range) ⇒ `Array` #fill {|index| ... } ⇒ `Array` #fill(start [, length]) {|index| ... } ⇒ `Array` #fill(range) {|index| ... } ⇒ `Array`

#select {|item| ... } ⇒ `Array` #select ⇒ Enumerator #filter {|item| ... } ⇒ `Array` #filter ⇒ Enumerator
Also known as: #select

#select! {|item| ... } ⇒ `Array`^? #select! ⇒ Enumerator #filter! {|item| ... } ⇒ `Array`^? #filter! ⇒ Enumerator
Also known as: #select!

#find_index(obj) ⇒ Integer^? #find_index {|item| ... } ⇒ Integer^? #find_index ⇒ Enumerator #index(obj) ⇒ Integer^? #index {|item| ... } ⇒ Integer^? #index ⇒ Enumerator

#first ⇒ Object^? #first(n) ⇒ `Array`

#flatten ⇒ `Array` #flatten(level) ⇒ `Array`

#flatten! ⇒ `Array`^? #flatten!(level) ⇒ `Array`^?

#include?(object) ⇒ `Boolean`

#find_index(obj) ⇒ Integer^? #find_index {|item| ... } ⇒ Integer^? #find_index ⇒ Enumerator #index(obj) ⇒ Integer^? #index {|item| ... } ⇒ Integer^? #index ⇒ Enumerator
Also known as: #find_index

#replace(other_ary) ⇒ `Array` #initialize_copy(other_ary) ⇒ `Array`

#insert(index, obj...) ⇒ `Array`

#intersection(other_ary1, other_ary2, ...) ⇒ `Array`

#keep_if {|item| ... } ⇒ `Array` #keep_if ⇒ Enumerator

#last ⇒ Object^? #last(n) ⇒ `Array`

#collect {|item| ... } ⇒ `Array` #map {|item| ... } ⇒ `Array` #collect ⇒ Enumerator #map ⇒ Enumerator
Also known as: #collect

#collect! {|item| ... } ⇒ `Array` #map! {|item| ... } ⇒ `Array` #collect! ⇒ Enumerator #map! ⇒ Enumerator
Also known as: #collect!

#max ⇒ Object #max {|a, b| ... } ⇒ Object #max(n) ⇒ `Array` #max(n) {|a, b| ... } ⇒ `Array`

#min ⇒ Object #min {|a, b| ... } ⇒ Object #min(n) ⇒ `Array` #min(n) {|a, b| ... } ⇒ `Array`

#minmax ⇒ `Array`, Object #minmax {|a, b| ... } ⇒ `Array`, Object

#none? {|obj| ... } ⇒ `Boolean` #none? ⇒ `Boolean` #none?(pattern) ⇒ `Boolean`

#one? {|obj| ... } ⇒ `Boolean` #one? ⇒ `Boolean` #one?(pattern) ⇒ `Boolean`

#pack(aTemplateString) ⇒ `aBinaryString` #pack(aTemplateString, buffer: aBufferString) ⇒ `aBufferString`

#permutation {|p| ... } ⇒ `Array` #permutation ⇒ Enumerator #permutation(n) {|p| ... } ⇒ `Array` #permutation(n) ⇒ Enumerator

#pop ⇒ Object^? #pop(n) ⇒ `Array`

#unshift(obj, ...) ⇒ `Array` #prepend(obj, ...) ⇒ `Array`
Also known as: #unshift

#product(other_ary, ...) ⇒ `Array` #product(other_ary, ...) {|p| ... } ⇒ `Array`

#push(obj, ...) ⇒ `Array` #append(obj, ...) ⇒ `Array`
Also known as: #append

#rassoc(obj) ⇒ `element_ary`^?

#reject {|item| ... } ⇒ `Array` #reject ⇒ Enumerator

#reject! {|item| ... } ⇒ `Array`^? #reject! ⇒ Enumerator

#repeated_combination(n) {|c| ... } ⇒ `Array` #repeated_combination(n) ⇒ Enumerator

#repeated_permutation(n) {|p| ... } ⇒ `Array` #repeated_permutation(n) ⇒ Enumerator

#replace(other_ary) ⇒ `Array` #initialize_copy(other_ary) ⇒ `Array`
Also known as: #initialize_copy

#reverse ⇒ `Array`

#reverse! ⇒ `Array`

#reverse_each {|item| ... } ⇒ `Array` #reverse_each ⇒ Enumerator

#rindex(obj) ⇒ Integer^? #rindex {|item| ... } ⇒ Integer^? #rindex ⇒ Enumerator

#rotate(count = 1) ⇒ `Array`

#rotate!(count = 1) ⇒ `Array`

#sample ⇒ Object #sample(random: rng) ⇒ Object #sample(n) ⇒ `Array` #sample(n, random: rng) ⇒ `Array`

#select {|item| ... } ⇒ `Array` #select ⇒ Enumerator #filter {|item| ... } ⇒ `Array` #filter ⇒ Enumerator

#select! {|item| ... } ⇒ `Array`^? #select! ⇒ Enumerator #filter! {|item| ... } ⇒ `Array`^? #filter! ⇒ Enumerator

#shift ⇒ Object^? #shift(n) ⇒ `Array`

#shuffle ⇒ `Array` #shuffle(random: rng) ⇒ `Array`

#shuffle! ⇒ `Array` #shuffle!(random: rng) ⇒ `Array`