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.

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 ]

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 ) Array . new ( 3 , 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 }

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

empty_table = Array . new ( 3 ) { Array . new ( 3 ) }

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" })

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.

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 ] arr [ 100 ] arr [ -3 ] arr [ 2 , 3 ] arr [ 1 .. 4 ] arr [ 1 .. -3 ]

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

arr . at ( 0 )

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 ) arr . fetch ( 100 , "oops" )

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

arr . first arr . last

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

arr . take ( 3 )

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

arr . drop ( 3 )

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 browsers . count

To check whether an array contains any elements at all

browsers . empty?

To check whether a particular item is included in the array

browsers . include? ( 'Konqueror' )

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 ) arr << 6

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

arr . unshift ( 0 )

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

arr . insert ( 3 , 'apple' )

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

arr . insert ( 3 , 'orange' , 'pear' , 'grapefruit' )

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 arr

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

arr . shift arr

To delete an element at a particular index:

arr . delete_at ( 2 ) arr

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

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

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 arr arr . compact! arr

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

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 , " " }

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

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 } arr arr . map! { | a | a ** 2 } arr

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.

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

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: