|
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:
|
|
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:
|
|
empty?
|
arr.empty?
-> true or false
|
|
Returns true if arr array contains no elements.
|
|
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.gif) b![[visible space]](visible_space.gif) c![[visible space]](visible_space.gif) "
|
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:
|
|
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"]
|
|