Programming Ruby

The Pragmatic Programmer's Guide
Contents ^
Next >

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 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 285). 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 378.

a = [ "a", "b", "c" ]
n = [ 65, 66, 67 ]
a.pack("A3A3A3") » "a[visible space][visible space]b[visible space][visible space]c[visible space][visible space]"
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"]

Contents ^
Next >

Extracted from the book "Programming Ruby - The Pragmatic Programmer's Guide"
Copyright © 2001 by Addison Wesley Longman, Inc. This material may be distributed only subject to the terms and conditions set forth in the Open Publication License, v1.0 or later (the latest version is presently available at http://www.opencontent.org/openpub/)).

Distribution of substantively modified versions of this document is prohibited without the explicit permission of the copyright holder.

Distribution of the work or derivative of the work in any standard (paper) book form is prohibited unless prior permission is obtained from the copyright holder.