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.
Enumerable
collect
, detect
, each_with_index
, entries
, find
, find_all
, grep
, include?
, map
, max
, member?
, min
, reject
, select
, sort
, to_a
Array.[](
...)
.
Array.[]( 1, 'a', /^A/ ) → [1, "a", /^A/]
Array[ 1, 'a', /^A/ ] → [1, "a", /^A/]
[ 1, 'a', /^A/ ] → [1, "a", /^A/]
Array.new → []
Array.new(2) → [nil, nil]
Array.new(5, "A") → ["A", "A", "A", "A", "A"]
Array.new(2, Hash.new) → [{}, {}]
[ 1, 1, 3, 5 ] & [ 1, 2, 3 ] → [1, 3]
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]
[ 1, 2, 3 ] + [ 4, 5 ] → [1, 2, 3, 4, 5]
[ 1, 1, 2, 2, 3, 3, 3, 4, 5 ] - [ 1, 2, 4 ] → [3, 5]
Array#push
.
[ 1, 2 ] << "c" << "d" << [ 3, 4 ] → [1, 2, "c", "d", [3, 4]]
<=>
). 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
true
or false
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
true
or false
case
expressions. For arrays, this is the same as Array#==
.
nil
nil
nil
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"]
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"]
[ "a", "b", "c" ] | [ "c", "d", "a" ] → ["a", "b", "c", "d"]
nil
.==
.
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
nil
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"
a = [ "a", "b", "c", "d", "e" ]
a.clear → []
Array#collect!
.
a = [ "a", "b", "c", "d" ]
a.collect {|x| x + "!" } → ["a!", "b!", "c!", "d!"]
a → ["a", "b", "c", "d"]
Array#collect
.
a = [ "a", "b", "c", "d" ]
a.collect! {|x| x + "!" } → ["a!", "b!", "c!", "d!"]
a → ["a!", "b!", "c!", "d!"]
nil
elements removed.
[ "a", nil, "b", nil, "c", nil ].compact → ["a", "b", "c"]
nil
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
[ "a", "b" ].concat( ["c", "d"] ) → ["a", "b", "c", "d"]
nil
nil
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"
nil
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
true
.
a = [ "a", "b", "c" ]
a.delete_if {|x| x >= "b" } → ["a"]
a = [ "a", "b", "c" ]
a.each {|x| print x, " -- " }
produces:
a -- b -- c --
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 --
true
or false
true
if arr array contains no elements.
[].empty? → true
true
or false
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
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"]
nil
nil
.
a = [ "q", "r", "s", "t" ]
a.first → "q"
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]
nil
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]
true
or false
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
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” |
nil
==
anObject. Returns
nil
if no match is found.
a = [ "a", "b", "c" ]
a.index("b") → 1
a.index("z") → nil
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]
Array#indexes
.
[ "a", "b", "c" ].join → "abc"
[ "a", "b", "c" ].join("-") → "a-b-c"
nil
nil
.
[ "w", "x", "y", "z" ].last → "z"
[ 1, 2, 3, 4, 5 ].length → 5
Array#collect!
.
nil
elements in arr. May be zero.
[ 1, nil, 3, nil, 5 ].nitems → 3
*
”), 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
.
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"
nil
nil
if the array is empty (as with a stack).
a = [ "a", "m", "z" ]
a.pop → "z"
a → ["a", "m"]
a = [ "a", "b", "c" ]
a.push("d", "e", "f") → ["a", "b", "c", "d", "e", "f"]
nil
==
. 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
nil
Array#delete_if
, but returns nil
if no
changes were made.
a = [ "a", "b", "c", "d", "e" ]
a.replace( [ "x", "y", "z" ] ) → ["x", "y", "z"]
a → ["x", "y", "z"]
[ "a", "b", "c" ].reverse → ["c", "b", "a"]
[ 1 ].reverse → [1]
nil
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
Array#each
, but traverses arr in reverse order.
a = [ "a", "b", "c" ]
a.reverse_each {|x| print x, " " }
produces:
c b a
nil
==
anObject. Returns
nil
if no match is found.
a = [ "a", "b", "b", "b", "c" ]
a.rindex("b") → 3
a.rindex("z") → nil
nil
nil
if the array
is empty.
args = [ "-m", "-q", "filename" ]
args.shift → "-m"
args → ["-q", "filename"]
Array#length
.
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"]
nil
nil
nil
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"]
<=>
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"]
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"]
Array#to_a
.
.join
.
[ "a", "e", "i", "o" ].to_s → "aeio"
a = [ "a", "a", "b", "b", "c" ]
a.uniq → ["a", "b", "c"]
nil
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
a = [ "b", "c", "d" ]
a.unshift("a") → ["a", "b", "c", "d"]
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.