Ruby v1.6 Class and Library Reference: Array

class Array |
Parent: | Object
Version: | 1.6

### Index:

[ ] new & * + - << <=> == === [ ] [ ]= | assoc at clear collect collect! compact compact! concat delete delete_at delete_if each each_index empty? eql? fill first flatten flatten! include? index indexes indices join last length map! nitems pack pop push rassoc reject! replace reverse reverse! reverse_each rindex shift size slice slice! sort sort! to_a to_ary to_s uniq uniq! unshift

Arrays are ordered, integer-indexed collections of any object. Array indexing starts at 0, as in C or Java. A negative index is assumed 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.

mixins
Enumerable: | collect, detect, each_with_index, entries, find, find_all, grep, include?, map, max, member?, min, reject, select, sort, to_a

class methods
[ ] | Array[ [anObject]* ] -> anArray
|  | Returns a new array populated with the given objects. Equivalent to the operator form `Array.[](`...`)`.
`Array.[]( 1, 'a', /^A/ )` | -> | `[1, "a", /^A/]`
`Array[ 1, 'a', /^A/ ]` | -> | `[1, "a", /^A/]`
`[ 1, 'a', /^A/ ]` | -> | `[1, "a", /^A/]`
new | Array.new( anInteger=0, anObject=nil ) -> anArray
|  | Returns a new array, optionally with a size and initial value (that is, anInteger references to the same anObject).
`Array.new` | -> | `[]`
`Array.new(2)` | -> | `[nil, nil]`
`Array.new(5, "A")` | -> | `["A", "A", "A", "A", "A"]`
`Array.new(2, Hash.new)` | -> | `[{}, {}]`

instance methods
& | arr & anOtherArray -> anArray
|  | Set Intersection-Returns a new array containing elements common to the two arrays, with no duplicates.
`[ 1, 1, 3, 5 ] & [ 1, 2, 3 ]` | -> | `[1, 3]`
* | arr * anInteger -> anArray arr * aString -> anOtherString
|  | Repetition-With a `String` argument, equivalent to `arr.join(aString)`. Otherwise, returns a new array built by concatenating the anInteger copies of arr.
`[ 1, 2, 3 ] * 3` | -> | `[1, 2, 3, 1, 2, 3, 1, 2, 3]`
+ | arr + anOtherArray -> anArray
|  | 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]`
- | arr - anOtherArray -> anArray
|  | Set Difference-Returns a new array that is a copy of the original array, removing any items that also appear in anOtherArray and duplicated items.
`[ 1, 1, 2, 2, 3, 3, 3, 4, 5 ] - [ 1, 2, 4 ]` | -> | `[3, 5]`
<< | arr << anObject -> arr
|  | 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. See also `Array#push`.
`[ 1, 2 ] << "c" << "d" << [ 3, 4 ]` | -> | `[1, 2, "c", "d", [3, 4]]`
<=> | arr <=> anOtherArray -> -1, 0, +1
|  | Comparison-Returns an integer -1, 0, or +1 if this array is less than, equal to, or greater than anOtherArray. Each object in each array is compared (using `<=>`). If any value isn't equal, then that inequality is the return value. If all the values found are equal, then the return is based on a comparison of the array lengths. Thus, two arrays are ``equal'' according to `Array#<=>` 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.
`[ "a", "a", "c" ] <=> [ "a", "b", "c" ]` | -> | `-1`
`[ 1, 2, 3, 4, 5, 6 ] <=> [ 1, 2 ]` | -> | `1`
== | arr == anOtherArray -> `true` or `false`
|  | 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 the other array.
`[ "a", "c" ] == [ "a", "c", 7 ]` | -> | `false`
`[ "a", "c", 7 ] == [ "a", "c", 7 ]` | -> | `true`
`[ "a", "c", 7 ] == [ "a", "d", "f" ]` | -> | `false`
=== | arr === anOtherArray -> `true` or `false`
|  | Case Equality-Equality as evaluated by `case` expressions. For arrays, this is the same as `Array#==`.
[ ] | arr[anInteger] -> anObject or `nil` arr[start, length] -> aSubArray or `nil` arr[aRange] -> aSubArray or `nil`
|  | Element Reference-Returns the element at index anInteger, or returns a subarray starting at index start and continuing for length elements, or returns a subarray specified by aRange. Negative indices count backward from the end of the array (-1 is the last element). Returns `nil` if any indices 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"]`
[ ]= | arr[anInteger] = anObject -> anObject arr[start, length] = aSubArray -> aSubArray arr[aRange] = aSubArray -> aSubArray
|  | Element Assignment-Sets the element at index anInteger, or replaces a subarray starting at index start and continuing for length elements, or replaces a subarray specified by aRange. If anInteger is greater than the current capacity of the array, the array grows automatically. A negative anInteger will count backward from the end of the array. Inserts elements if length is zero. If subArray is `nil`, deletes elements from arr. An `IndexError` is raised if a negative index points past the beginning of the array. See also `Array#push`, `Array#unshift`.
`a = Array.new` | -> | `[]`
`a[4] = "4"; a` | -> | `[nil, nil, nil, nil, "4"]`
`a[0, 3] = [ 'a', 'b', 'c' ]; a` | -> | `["a", "b", "c", nil, "4"]`
`a[1..2] = [ 1, 2 ]; a` | -> | `["a", 1, 2, nil, "4"]`
`a[0, 2] = "?"; a` | -> | `["?", 2, nil, "4"]`
`a[0..2] = "A"; a` | -> | `["A", "4"]`
`a[-1] = "Z"; a` | -> | `["A", "Z"]`
`a[1..-1] = nil; a` | -> | `["A"]`
| | arr | anOtherArray -> anArray
|  | Set Union-Returns a new array by joining this array with anOtherArray, removing duplicates.
`[ "a", "b", "c" ] | [ "c", "d", "a" ]` | -> | `["a", "b", "c", "d"]`
assoc | arr.assoc( anObject ) -> anArray or `nil`
|  | Searches through an array whose elements are also arrays comparing anObject with the first element of each contained array using anObject`.==` . Returns the first contained array that matches (that is, the first associated array), or `nil` if no match is found. See also `Array#rassoc`.
`s1 = [ "colors", "red", "blue", "green" ]`
`s2 = [ "letters", "a", "b", "c" ]`
`s3 = "foo"`
`a = [ s1, s2, s3 ]`
`a.assoc("letters")` | -> | `["letters", "a", "b", "c"]`
`a.assoc("foo")` | -> | `nil`
at | arr.at( anInteger ) -> anObject or `nil`
|  | Returns the element at index anInteger. A negative index counts from the end of arr. Returns `nil` if the index is out of range. See also `Array#[]`. (`Array#at` is slightly faster than `Array#[]`, as it does not accept ranges and so on.)
`a = [ "a", "b", "c", "d", "e" ]`
`a.at(0)` | -> | `"a"`
`a.at(-1)` | -> | `"e"`
clear | arr.clear -> arr
|  | Removes all elements from arr.
`a = [ "a", "b", "c", "d", "e" ]`
`a.clear` | -> | `[]`
collect | arr.collect {| obj | block } -> anArray
|  | Returns a new array by invoking block once for every element, passing each element as a parameter to block. The result of block is used as the given element in the new array. See also `Array#collect!`.
`a = [ "a", "b", "c", "d" ]`
`a.collect {|x| x + "!" }` | -> | `["a!", "b!", "c!", "d!"]`
`a` | -> | `["a", "b", "c", "d"]`
collect! | arr.collect! {| obj | block } -> arr
|  | Invokes block once for each element of arr, replacing the element with the value returned by block. See also `Array#collect`.
`a = [ "a", "b", "c", "d" ]`
`a.collect! {|x| x + "!" }` | -> | `["a!", "b!", "c!", "d!"]`
`a` | -> | `["a!", "b!", "c!", "d!"]`
compact | arr.compact -> anArray
|  | Returns a new array based on the arr with all `nil` elements removed.
`[ "a", nil, "b", nil, "c", nil ].compact` | -> | `["a", "b", "c"]`
compact! | arr.compact! -> arr or `nil`
|  | Same as `Array#compact`, but modifies the receiver in place. Returns `nil` if no changes were made.
`[ "a", nil, "b", nil, "c" ].compact!` | -> | `["a", "b", "c"]`
`[ "a", "b", "c" ].compact!` | -> | `nil`
concat | arr.concat( anOtherArray ) -> arr
|  | Appends the elements in anOtherArray to arr.
`[ "a", "b" ].concat( ["c", "d"] )` | -> | `["a", "b", "c", "d"]`
delete | arr.delete( anObject ) -> anObject or `nil` arr.delete( anObject ) { block } -> anObject or `nil`
|  | Deletes items from the self{:0578:}:0578: that are equal to anObject. If the item is not found, returns `nil`. If the optional code block is given, returns the result of block if the item is not found.
`a = [ "a", "b", "b", "b", "c" ]`
`a.delete("b")` | -> | `"b"`
`a` | -> | `["a", "c"]`
`a.delete("z")` | -> | `nil`
`a.delete("z") { "not found" }` | -> | `"not found"`
delete_at | arr.delete_at( anIndex ) -> anObject or `nil`
|  | Deletes the element at the specified index, returning that element, or `nil` if the index is out of range. See also `Array#slice!`.
`a = %w( ant bat cat dog )`
`a.delete_at(2)` | -> | `"cat"`
`a` | -> | `["ant", "bat", "dog"]`
`a.delete_at(99)` | -> | `nil`
delete_if | arr.delete_if { block } -> arr
|  | Deletes every element of arr for which block evaluates to `true`.
`a = [ "a", "b", "c" ]`
`a.delete_if {|x| x >= "b" }` | -> | `["a"]`
each | arr.each {| item | block } -> arr
|  | Calls block once for each element in arr, passing that element as a parameter.
    a = [ "a", "b", "c" ]
    a.each {|x| print x, " - " }
produces:
    a - b - c -
each_index | arr.each_index {| anIndex | block } -> arr
|  | Same as `Array#each`, but passes the index of the element instead of the element itself.
    a = [ "a", "b", "c" ]
    a.each_index {|x| print x, " - " }
produces:
    0 - 1 - 2 -
empty? | arr.empty? -> `true` or `false`
|  | Returns `true` if arr array contains no elements.
`[].empty?` | -> | `true`
eql? | arr.eql?( anOtherArray ) -> `true` or `false`
|  | An array is equal to another array if the lengths are equal and each corresponding element is equal (according to `Object#eql?`). See also `Array#<=>`. `eql?` is used for `Hash` comparison.
`[ "a", "b", "c" ].eql?(["a", "b", "c"])` | -> | `true`
`[ "a", "b", "c" ].eql?(["a", "b"])` | -> | `false`
`[ "a", "b", "c" ].eql?(["b", "c", "d"])` | -> | `false`
fill | arr.fill( anObject ) -> arr arr.fill( anObject, start [, length] ) -> arr arr.fill( anObject, aRange ) -> arr
|  | Sets the selected elements of arr (which may be the entire array) to anObject. A start of `nil` is equivalent to zero. A length of `nil` is equivalent to arr.length.
`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"]`
first | arr.first -> anObject or `nil`
|  | Returns the first element of the array. If the array is empty, returns `nil`.
`a = [ "q", "r", "s", "t" ]`
`a.first` | -> | `"q"`
flatten | arr.flatten -> anArray
|  | Returns a new array that is a one-dimensional flattening of this array (recursively). That is, for every element that is an array, extract its elements into the new array.
`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]`
flatten! | arr.flatten! -> arr or `nil`
|  | Same as `Array#flatten`, but modifies the receiver in place. Returns `nil` if no modifications were made (i.e., arr contains no subarrays.)
`a = [ 1, 2, [3, [4, 5] ] ]`
`a.flatten!` | -> | `[1, 2, 3, 4, 5]`
`a.flatten!` | -> | `nil`
`a` | -> | `[1, 2, 3, 4, 5]`
include? | arr.include?( anObject ) -> `true` or `false`
|  | Returns `true` if the given object is present in arr (that is, if any object `==` anObject), `false` otherwise.
`a = [ "a", "b", "c" ]`
`a.include?("b")` | -> | `true`
`a.include?("z")` | -> | `false`
Template characters for `Array#pack`
Directive | Meaning
@ | Moves to absolute position
A | ASCII string (space padded, count is width)
a | ASCII string (null padded, count is width)
B | Bit string (descending bit order)
b | Bit string (ascending bit order)
C | Unsigned char
c | Char
d | Double-precision float, native format
E | Double-precision float, little-endian byte order
e | Single-precision float, little-endian byte order
f | Single-precision float, native format
G | Double-precision float, network (big-endian) byte order
g | Single-precision float, network (big-endian) byte order
H | Hex string (high nibble first)
h | Hex string (low nibble first)
I | Unsigned integer
i | Integer
L | Unsigned long
l | Long
M | Quoted printable, MIME encoding (see RFC2045)
m | Base64 encoded string
N | Long, network (big-endian) byte order
n | Short, network (big-endian) byte-order
P | Pointer to a structure (fixed-length string)
p | Pointer to a null-terminated string
S | Unsigned short
s | Short
U | UTF-8
u | UU-encoded string
V | Long, little-endian byte order
v | Short, little-endian byte order
X | Back up a byte
x | Null byte
Z | Same as ``A''
index | arr.index( anObject ) -> anInteger or `nil`
|  | Returns the index of the first object in arr such that the object `==` anObject. Returns `nil` if no match is found.
`a = [ "a", "b", "c" ]`
`a.index("b")` | -> | `1`
`a.index("z")` | -> | `nil`
indexes | arr.indexes( i1, i2, ... iN ) -> anArray
|  | Returns a new array consisting of elements at the given indices. May insert `nil` for indices out of range.
`a = [ "a", "b", "c", "d", "e", "f", "g" ]`
`a.indexes(0, 2, 4)` | -> | `["a", "c", "e"]`
`a.indexes(0, 2, 4, 12)` | -> | `["a", "c", "e", nil]`
indices | arr.indices( i1, i2, ... iN ) -> anArray
|  | Synonym for `Array#indexes`.
join | arr.join( aSepString=`$,` ) -> aString
|  | Returns a string created by converting each element of the array to a string, separated by aSepString.
`[ "a", "b", "c" ].join` | -> | `"abc"`
`[ "a", "b", "c" ].join("-")` | -> | `"a-b-c"`
last | arr.last -> anObject or `nil`
|  | Returns the last element of arr. If the array is empty, returns `nil`.
`[ "w", "x", "y", "z" ].last` | -> | `"z"`
length | arr.length -> anInteger
|  | Returns the number of elements in arr. May be zero.
`[ 1, 2, 3, 4, 5 ].length` | -> | `5`
map! | arr.map! {| obj | block } -> arr
|  | Synonym for `Array#collect!`.
nitems | arr.nitems -> anInteger
|  | Returns the number of non-`nil` elements in arr. May be zero.
`[ 1, nil, 3, nil, 5 ].nitems` | -> | `3`
pack | arr.pack ( aTemplateString ) -> aBinaryString
|  | Packs the contents of arr into a binary sequence according to the directives in aTemplateString (see Table 22.1 on page 289). 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 (```_`'') 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` on page 383.
`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"`
pop | arr.pop -> anObject or `nil`
|  | Removes the last element from arr and returns it, or `nil` if the array is empty (as with a stack).
`a = [ "a", "m", "z" ]`
`a.pop` | -> | `"z"`
`a` | -> | `["a", "m"]`
push | arr.push( [anObject]+ ) -> arr
|  | Appends the given argument(s) to the end of arr (as with a stack).
`a = [ "a", "b", "c" ]`
`a.push("d", "e", "f")` | -> | `["a", "b", "c", "d", "e", "f"]`
rassoc | arr.rassoc( key ) -> anArray or `nil`
|  | Searches through the array whose elements are also arrays. Compares key with the second element of each contained array using `==`. Returns the first contained array that matches. See also `assoc`.
`a = [ [ 1, "one"], [2, "two"], [3, "three"], ["ii", "two"] ]`
`a.rassoc("two")` | -> | `[2, "two"]`
`a.rassoc("four")` | -> | `nil`
reject! | arr.reject! { block } -> arr or `nil`
|  | Equivalent to `Array#delete_if`, but returns `nil` if no changes were made.
replace | arr.replace( anOtherArray ) -> arr
|  | Replaces the contents of arr with the contents of anOtherArray, truncating or expanding if necessary.
`a = [ "a", "b", "c", "d", "e" ]`
`a.replace( [ "x", "y", "z" ] )` | -> | `["x", "y", "z"]`
`a` | -> | `["x", "y", "z"]`
reverse | arr.reverse -> anArray
|  | Returns a new array using arr's elements in reverse order.
`[ "a", "b", "c" ].reverse` | -> | `["c", "b", "a"]`
`[ 1 ].reverse` | -> | `[1]`
reverse! | arr.reverse! -> arr or `nil`
|  | Same as `reverse`, but returns `nil` if arr is unchanged (arr`.length` is zero or one).
`a = [ "a", "b", "c" ]`
`a.reverse!` | -> | `["c", "b", "a"]`
`a` | -> | `["c", "b", "a"]`
`[ 1 ].reverse!` | -> | `nil`
reverse_each | arr.reverse_each { block }
|  | Same as `Array#each`, but traverses arr in reverse order.
    a = [ "a", "b", "c" ]
    a.reverse_each {|x| print x, " " }
produces:
    c b a
rindex | arr.rindex( anObject ) -> anInteger or `nil`
|  | Returns the index of the last object in arr such that the object `==` anObject. Returns `nil` if no match is found.
`a = [ "a", "b", "b", "b", "c" ]`
`a.rindex("b")` | -> | `3`
`a.rindex("z")` | -> | `nil`
shift | arr.shift -> anObject or `nil`
|  | Returns the first element of arr and removes it (shifting all other elements down by one). Returns `nil` if the array is empty.
`args = [ "-m", "-q", "filename" ]`
`args.shift` | -> | `"-m"`
`args` | -> | `["-q", "filename"]`
size | arr.size -> anInteger
|  | Synonym for `Array#length`.
slice | arr.slice( anInteger ) -> anObject arr.slice( start, length ) -> aSubArray arr.slice( aRange ) -> aSubArray
|  | Synonym for `Array#[ ]`.
`a = [ "a", "b", "c", "d", "e" ]`
`a.slice(2) + a.slice(0) + a.slice(1)` | -> | `"cab"`
`a.slice(6)` | -> | `nil`
`a.slice(1, 2)` | -> | `["b", "c"]`
`a.slice(1..3)` | -> | `["b", "c", "d"]`
`a.slice(4..7)` | -> | `["e"]`
`a.slice(6..10)` | -> | `nil`
`a.slice(-3, 3)` | -> | `["c", "d", "e"]`
slice! | arr.slice!( anInteger ) -> anObject or `nil` arr.slice!( start, length ) -> aSubArray or `nil` arr.slice!( aRange ) -> aSubArray or `nil`
|  | Deletes the element(s) given by an index (optionally with a length) or by a range. Returns the deleted object, subarray, or `nil` if the index is out of range. Equivalent to:
    def slice!(*args)
      result = self[*args]
      self[*args] = nil
      result
    end
`a = [ "a", "b", "c" ]`
`a.slice!(1)` | -> | `"b"`
`a` | -> | `["a", "c"]`
`a.slice!(-1)` | -> | `"c"`
`a` | -> | `["a"]`
`a.slice!(100)` | -> | `nil`
`a` | -> | `["a"]`
sort | arr.sort -> anArray arr.sort {| a,b | block } -> anArray
|  | Returns a new array created by sorting arr. Comparisons for the sort will be done using the `<=>` operator or using an optional code block. The block implements a comparison between a and b, returning -1, 0, or +1.
`a = [ "d", "a", "e", "c", "b" ]`
`a.sort` | -> | `["a", "b", "c", "d", "e"]`
`a.sort {|x,y| y <=> x }` | -> | `["e", "d", "c", "b", "a"]`
sort! | arr.sort! -> arr arr.sort! {| a,b | block } -> arr
|  | Same as `Array#sort`, but modifies the receiver in place. arr is effectively frozen while a sort is in progress.
`a = [ "d", "a", "e", "c", "b" ]`
`a.sort!` | -> | `["a", "b", "c", "d", "e"]`
`a` | -> | `["a", "b", "c", "d", "e"]`
to_a | arr.to_a -> arr
|  | Returns arr.
to_ary | arr.to_ary -> arr
|  | Synonym for `Array#to_a`.
to_s | arr.to_s -> aString
|  | Returns arr`.join`.
`[ "a", "e", "i", "o" ].to_s` | -> | `"aeio"`
uniq | arr.uniq -> anArray
|  | Returns a new array by removing duplicate values in arr.
`a = [ "a", "a", "b", "b", "c" ]`
`a.uniq` | -> | `["a", "b", "c"]`
uniq! | arr.uniq! -> arr or `nil`
|  | Same as `Array#uniq`, but modifies the receiver in place. 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`
unshift | arr.unshift( anObject ) -> arr
|  | Prepends anObject to the front of arr, and shifts all other elements up one.
`a = [ "b", "c", "d" ]`
`a.unshift("a")` | -> | `["a", "b", "c", "d"]`

Extracted from the book "Programming Ruby - The Pragmatic Programmer's Guide"
Copyright © 2000 Addison Wesley Longman, Inc. Released under the terms of the Open Publication License V1.0.
This reference is available for download.