Array

An Array is an ordered, integer-indexed collection of objects, called elements. Any object may be an Array element.

Array Indexes

Array indexing starts at 0, as in C or Java.

A positive index is an offset from the first element:

• Index 0 indicates the first element.

• Index 1 indicates the second element.

• …

A negative index is an offset, backwards, from the end of the array:

• Index -1 indicates the last element.

• Index -2 indicates the next-to-last element.

• …

A non-negative index is in range if it is smaller than the size of the array. For a 3-element array:

• Indexes 0 through 2 are in range.

• Index 3 is out of range.

A negative index is in range if its absolute value is not larger than the size of the array. For a 3-element array:

• Indexes -1 through -3 are in range.

• Index -4 is out of range.

Creating Arrays

You can create an Array object explicitly with:

• An array literal.

You can convert certain objects to Arrays with:

• Method Array.

An Array 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 calling Array.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 Array#[] 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 Array#[].

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]

What’s Here

First, what’s elsewhere. Class Array:

• Inherits from class Object.

• Includes module Enumerable, which provides dozens of additional methods.

Here, class Array provides methods that are useful for:

• Creating an Array

• Querying

• Comparing

• Fetching

• Assigning

• Deleting

• Combining

• Iterating

• Converting

• And more.…

Methods for Creating an Array

::[]

Returns a new array populated with given objects.

::new

Returns a new array.

::try_convert

Returns a new array created from a given object.

Methods for Querying

length, size

Returns the count of elements.

include?

Returns whether any element == a given object.

empty?

Returns whether there are no elements.

all?

Returns whether all elements meet a given criterion.

any?

Returns whether any element meets a given criterion.

none?

Returns whether no element == a given object.

one?

Returns whether exactly one element == a given object.

count

Returns the count of elements that meet a given criterion.

find_index, index

Returns the index of the first element that meets a given criterion.

rindex

Returns the index of the last element that meets a given criterion.

hash

Returns the integer hash code.

Methods for Comparing

#<=>

Returns -1, 0, or 1 as self is less than, equal to, or greater than a given object.

#==

Returns whether each element in self is == to the corresponding element in a given object.

eql?

Returns whether each element in self is eql? to the corresponding element in a given object.

Methods for Fetching

These methods do not modify self.

[]

Returns one or more elements.

fetch

Returns the element at a given offset.

first

Returns one or more leading elements.

last

Returns one or more trailing elements.

max

Returns one or more maximum-valued elements, as determined by <=> or a given block.

max

Returns one or more minimum-valued elements, as determined by <=> or a given block.

minmax

Returns the minimum-valued and maximum-valued elements, as determined by <=> or a given block.

assoc

Returns the first element that is an array whose first element == a given object.

rassoc

Returns the first element that is an array whose second element == a given object.

at

Returns the element at a given offset.

values_at

Returns the elements at given offsets.

dig

Returns the object in nested objects that is specified by a given index and additional arguments.

drop

Returns trailing elements as determined by a given index.

take

Returns leading elements as determined by a given index.

drop_while

Returns trailing elements as determined by a given block.

take_while

Returns leading elements as determined by a given block.

slice

Returns consecutive elements as determined by a given argument.

sort

Returns all elements in an order determined by <=> or a given block.

reverse

Returns all elements in reverse order.

compact

Returns an array containing all non-nil elements.

select, filter

Returns an array containing elements selected by a given block.

uniq

Returns an array containing non-duplicate elements.

rotate

Returns all elements with some rotated from one end to the other.

bsearch

Returns an element selected via a binary search as determined by a given block.

bsearch_index

Returns the index of an element selected via a binary search as determined by a given block.

sample

Returns one or more random elements.

shuffle

Returns elements in a random order.

Methods for Assigning

These methods add, replace, or reorder elements in self.

[]=

Assigns specified elements with a given object.

push, append, <<

Appends trailing elements.

unshift, prepend

Prepends leading elements.

insert

Inserts given objects at a given offset; does not replace elements.

concat

Appends all elements from given arrays.

fill

Replaces specified elements with specified objects.

replace

Replaces the content of self with the content of a given array.

reverse!

Replaces self with its elements reversed.

rotate!

Replaces self with its elements rotated.

shuffle!

Replaces self with its elements in random order.

sort!

Replaces self with its elements sorted, as determined by <=> or a given block.

sort_by!

Replaces self with its elements sorted, as determined by a given block.

Methods for Deleting

Each of these methods removes elements from self:

pop

Removes and returns the last element.

shift

Removes and returns the first element.

compact!

Removes all non-nil elements.

delete

Removes elements equal to a given object.

delete_at

Removes the element at a given offset.

delete_if

Removes elements specified by a given block.

keep_if

Removes elements not specified by a given block.

reject!

Removes elements specified by a given block.

select!, filter!

Removes elements not specified by a given block.

slice!

Removes and returns a sequence of elements.

uniq!

Removes duplicates.

Methods for Combining

#&

Returns an array containing elements found both in self and a given array.

intersection

Returns an array containing elements found both in self and in each given array.

+

Returns an array containing all elements of self followed by all elements of a given array.

-

Returns an array containiing all elements of self that are not found in a given array.

#|

Returns an array containing all elements of self and all elements of a given array, duplicates removed.

union

Returns an array containing all elements of self and all elements of given arrays, duplicates removed.

difference

Returns an array containing all elements of self that are not found in any of the given arrays..

product

Returns or yields all combinations of elements from self and given arrays.

Methods for Iterating

each

Passes each element to a given block.

reverse_each

Passes each element, in reverse order, to a given block.

each_index

Passes each element index to a given block.

cycle

Calls a given block with each element, then does so again, for a specified number of times, or forever.

combination

Calls a given block with combinations of elements of self; a combination does not use the same element more than once.

permutation

Calls a given block with permutations of elements of self; a permutation does not use the same element more than once.

repeated_combination

Calls a given block with combinations of elements of self; a combination may use the same element more than once.

repeated_permutation

Calls a given block with permutations of elements of self; a permutation may use the same element more than once.

Methods for Converting

map, collect

Returns an array containing the block return-value for each element.

map!, collect!

Replaces each element with a block return-value.

flatten

Returns an array that is a recursive flattening of self.

flatten!

Replaces each nested array in self with the elements from that array.

inspect, to_s

Returns a new String containing the elements.

join

Returns a newsString containing the elements joined by the field separator.

to_a

Returns self or a new array containing all elements.

to_ary

Returns self.

to_h

Returns a new hash formed from the elements.

transpose

Transposes self, which must be an array of arrays.

zip

Returns a new array of arrays containing self and given arrays; follow the link for details.

Other Methods

*

Returns one of the following:

• With integer argument n, a new array that is the concatenation of n copies of self.

• With string argument field_separator, a new string that is equivalent to join(field_separator).

abbrev

Returns a hash of unambiguous abbreviations for elements.

pack

Packs the elements into a binary sequence.

sum

Returns a sum of elements according to either + or a given block.

for pack.c