The Array class is one of Ruby's built-in classes. Arrays are compact, ordered collections of objects. Ruby arrays can hold objects such as String, Integer, Fixnum, Hash, Symbol, even other Array objects. Any object that Ruby can create, it can hold in an array. Each element in an array is associated with and referred to by an index (also known as a subscript in other languages). Array elements are automatically indexed (numbered) with an integer (Fixnum), starting with 0, then numbered consecutively, adding 1 for each additional element. In certain instances, you can refer to the last element of an array with -1, the second to last with -2, and so forth. That's handy. Ruby arrays are not as rigid as arrays in other languages. With static, compiled programming languages, you have to guess the ultimate size of the array at the time it is created. Not so with Ruby—arrays grow automatically.
There are many ways to create or initialize an array. One way is with the new class method:
months = Array.new
You can set the size of an array (the number of elements in an array) like this:
months = Array.new(12) [or] months = Array.new 12The array months now has a size (or length) of 12 elements. You can return the size of an array with either the size or length methods:
months.size # => 12 [or] months.length # => 12Another form of new lets you assign an object (such as a string) to each element in the array:
month = Array.new(12, "month")
You can also use a block with new, populating each element with what the block evaluates to:
num = Array.new(10) { |e| e = e * 2 }giving you an array like this:
[0, 2, 4, 6, 8, 10, 12, 14, 16, 18]
There is another method of Array, []. It works like this:
month_abbrv = Array.[]( "jan", "feb", "mar", "apr", "may", "jun", "jul", "aug", "sep", "oct", "nov", "dec" )
or like this, dropping the dot (.) and parentheses (( )), which is possible because of Ruby's flexible method syntax:
month_abbrv = Array[ "jan", "feb", "mar", "apr", "may", "jun", "jul", "aug", "sep", "oct", "nov", "dec" ]
An even simpler method for creating an array is this one, just using the square brackets:
months = [ nil, "January", "February", "March", "April", "May", "June", "July", "August", "September", "October", "November", "December" ]
The Kernel module, included in Object, has an Array method, which only accepts a single argument. Here the method takes a range as an argument to create an array of digits:
digits = Array(0..9) # => [1, 2, 3, 4, 5, 6, 7, 8, 9]With the %w notation, you can define an array of strings. It assumes that all elements are strings (even nil), but it sure saves keystrokes (no typing quotes or commas):
months = %w[ nil January February March April May June July August September October November December ]
To fill an array with numbers as strings using %w:
year = %w[ 2000 2001 2002 2003 2004 2005 2006 2007 2008 2009 ]
As numbers (not strings):
year = [2000, 2001, 2002, 2003, 2004, 2005, 2006, 2007, 2008, 2009]
You can even have an array that contains objects from different classes, not all just one type. For example, here's an array that contains four elements, each a different kind of object:
hodge_podge = ["January", 1, :year, [2006,01,01]]
Following are the public methods of the Array class, adapted and abbreviated from http://www.ruby-doc.org/core/classes/Array.html, where you will find examples and more detailed explanations of these methods.
Array.[]( . . . ) [or] Array[ . . . ] [or] [ . . . ]Array.new(size=0, obj=nil) [or] Array.new(array) [or] Array.new(size) { |index| block }Returns a new array. In the first form, the new array is empty. In the second it is created with size copies of obj (that is, size references to the same obj). The third form creates a copy of the array passed as a parameter. In the last form, an array of the given size is created. Each element in this array is calculated by passing the element's index to the given block and storing the return value.
array & other_arrayReturns a new array containing elements common to the two arrays, with no duplicates.
array * int [or] array * strReturns a new array built by concatenating the int copies of self. With a String argument, equivalent to self.join(str).
array + other_arrayReturns a new array built by concatenating the two arrays together to produce a third array.
array - other_arrayReturns a new array that is a copy of the original array, removing any items that also appear in other_array.
array | other_arrayReturns a new array by joining array with other_array, removing duplicates.
array << objPushes the given object onto the end of array. This expression returns the array itself, so several appends may be chained together.
array <=> other_arrayReturns an integer (-1, 0, or +1) if this array is less than, equal to, or greater than other_array. 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 value 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.
array == other_arrayTwo 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.
array[index] [or] array[start, length] [or] array[range] [or] array.slice(index) [or] array.slice(start, length) [or] array.slice(range)Returns the element at index, or returns a subarray starting at start and continuing for length elements, or returns a subarray specified by range. Negative indices count backward from the end of the array (-1 is the last element). Returns nil if the index (or starting index) is out of range.
array[index] = obj [or] array[start, length] = obj or an_array or nil [or] array[range] = obj or an_array or nilSets the element at index, or replaces a subarray starting at start and continuing for length elements, or replaces a subarray specified by range. If indices are greater than the current capacity of the array, the array grows automatically. Negative indices will count backward from the end of the array. Inserts elements if length is zero. If nil is used in the second and third form, deletes elements from self. See also Array#push and Array#unshift.
array.abbrev(pattern = nil)Calculates the set of unambiguous abbreviations for the strings in self. If passed a pattern or a string, only the strings matching the pattern or starting with the string are considered.
array.assoc(obj)Searches through an array whose elements are also arrays comparing obj with the first element of each contained array using obj.==. Returns the first contained array that matches (that is, the first associated array), or nil if no match is found. See also Array#rassoc.
array.at(index)Returns the element at index. A negative index counts from the end of self. 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.)
array.clearRemoves all elements from array.
array.collect { |item| block } [or] array.map { |item| block }Invokes block once for each element of self. Creates a new array containing the values returned by the block.
array.collect! { |item| block } [or] array.map! { |item| block }Invokes block once for each element of self, replacing the element with the value returned by block.
array.compactReturns a copy of self with all nil elements removed.
array.compact!Removes nil elements from array. Returns nil if no changes were made.
array.concat(other_array)Appends the elements in other_array to self.
array.delete(obj) [or] array.delete(obj) { block }Deletes items from self that are equal to obj. 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.
array.delete_at(index)Deletes the element at the specified index, returning that element, or nil if the index is out of range. See also Array#slice!.
array.delete_if { |item| block }Deletes every element of self for which block evaluates to true.
array.each { |item| block }Calls block once for each element in self, passing that element as a parameter.
array.each_index { |index| block }Same as Array#each, but passes the index of the element instead of the element itself.
array.empty?Returns true if the self array contains no elements.
array.eql?(other)Returns true if array and other are the same object, or are both arrays with the same content.
array.fetch(index) [or] array.fetch(index, default) [or] array.fetch(index) { |index| block }Tries to return the element at position index. If index lies outside the array, the first form throws an IndexError exception, the second form returns default, and the third form returns the value of invoking block, passing in index. Negative values of index count from the end of the array.
array.fill(obj) [or] array.fill(obj, start [, length]) [or] array.fill(obj, range) [or] array.fill { |index| block } [or] array.fill(start [, length] ) { |index| block } [or] array.fill(range) { |index| block }The first three forms set the selected elements of self (which may be the entire array) to obj. A start of nil is equivalent to zero. A length of nil is equivalent to self.length. The last three forms fill the array with the value of the block. The block is passed the absolute index of each element to be filled.
array.first [or] array.first(n)Returns the first element, or the first n elements, of the array. If the array is empty, the first form returns nil, and the second form returns an empty array.
array.flattenReturns 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.
array.flatten!Flattens array in place. Returns nil if no modifications were made. (array contains no subarrays.)
array.frozen?Returns true if array is frozen (or temporarily frozen while being sorted).
array.hashCompute a hash-code for array. Two arrays with the same content will have the same hash code (and will compare using eql?).
array.include?(obj)Returns true if obj is present in self, false otherwise.
array.index(obj)Returns the index of the first object in self that is == to obj. Returns nil if no match is found.
array.indexes(i1, i2, ... iN) [or] array.indices(i1, i2, ... iN)Deprecated; use Array#values_at.
array.indices(i1, i2, ... iN) [or] array.indexes(i1, i2, ... iN)Deprecated; use Array#values_at.
array.insert(index, obj...)Inserts the given values before the element with the given index (which may be negative).
array.inspectCreates a printable version of array.
array.join(sep=$,)Returns a string created by converting each element of the array to a string, separated by sep.
array.last [or] array.last(n)Returns the last element(s) of self. If array is empty, the first form returns nil.
array.lengthReturns the number of elements in self. May be zero.
array.map { |item| block } [or] array.collect { |item| block }Invokes block once for each element of self. Creates a new array containing the values returned by the block.
array.map! { |item| block } [or] array.collect! { |item| block }Invokes block once for each element of array, replacing the element with the value returned by block.
array.nitemsReturns the number of non-nil elements in self. May be zero.
array.pack(aTemplateString)Packs the contents of array into a binary sequence according to the directives in aTemplateString (see Table 19). 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.
Table 19 lists pack directives for use with Array#pack.
Table 19. Array pack directives
Directive | Description |
|---|---|
| Moves to absolute position. |
| ASCII string (space padded, count is width). |
| ASCII string (null padded, count is width). |
| Bit string (descending bit order). |
| Bit string (ascending bit order). |
| Unsigned char. |
| Char. |
| Double-precision float, native format. |
| Double-precision float, little-endian byte order. |
| Single-precision float, little-endian byte order. |
| Single-precision float, native format. |
| Double-precision float, network (big-endian) byte order. |
| Single-precision float, network (big-endian) byte order. |
| Hex string (high nibble first). |
| Hex string (low nibble first). |
| Unsigned integer. |
| Integer. |
| Unsigned long. |
| Long. |
| Quoted printable, MIME encoding (see RFC 2045). |
| Base64-encoded string. |
| Long, network (big-endian) byte order. |
| Short, network (big-endian) byte order. |
| Pointer to a structure (fixed-length string). |
| Pointer to a null-terminated string. |
| 64-bit number. |
| Unsigned short. |
| Short. |
| UTF-8. |
| UU-encoded string. |
| Long, little-endian byte order. |
| Short, little-endian byte order. |
| BER-compressed integer |
| Back up a byte. |
| Null byte. |
| Same as a, except that null is added with *. |
array.popRemoves the last element from array and returns it, or nil if array is empty.
array.push(obj, . . . )Pushes (appends) the given obj onto the end of this array. This expression returns the array itself, so several appends may be chained together.
array.rassoc(key)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 Array#assoc.
array.reject { |item| block }Returns a new array containing the items array for which the block is not true.
array.reject! { |item| block }Deletes elements from array for which the block evaluates to true, but returns nil if no changes were made. Equivalent to Array#delete_if.
array.replace(other_array)Replaces the contents of array with the contents of other_array, truncating or expanding if necessary.
array.reverseReturns a new array containing array's elements in reverse order.
array.reverse!Reverses array in place.
array.reverse_each {|item| block }Same as Array#each, but traverses array in reverse order.
array.rindex(obj)Returns the index of the last object in array == to obj. Returns nil if no match is found.
array.select {|item| block }Invokes the block passing in successive elements from array, returning an array containing those elements for which the block returns a true value.
array.shiftReturns the first element of self and removes it (shifting all other elements down by one). Returns nil if the array is empty.
array.sizeReturns the length of array (number of elements). Alias for length.
array.slice(index) [or] array.slice(start, length) [or] array.slice(range) [or] array[index] [or] array[start, length] [or] array[range]Returns the element at index, or returns a subarray starting at start and continuing for length elements, or returns a subarray specified by range. Negative indices count backward from the end of the array (-1 is the last element). Returns nil if the index (or starting index) are out of range.
array.slice!(index) [or] array.slice!(start, length) [or] array.slice!(range)Deletes the element(s) given by an index (optionally with a length) or by a range. Returns the deleted object, subarray, or nil if index is out of range.
array.sort [or] array.sort { | a,b | block }Returns a new array created by sorting self.
array.sort! [or] array.sort! { | a,b | block }Sorts self.
array.to_aReturns self. If called on a subclass of Array, converts the receiver to an Array object.
array.to_aryReturns self.
array.to_sReturns self.join.
array.transposeAssumes that self is an array of arrays and transposes the rows and columns.
array.uniqReturns a new array by removing duplicate values in array.
array.uniq!Removes duplicate elements from self. Returns nil if no changes are made (that is, no duplicates are found).
array.unshift(obj, . . . )Prepends objects to the front of array, other elements up one.
array.values_at(selector, . . . )Returns an array containing the elements in self corresponding to the given selector (one or more). The selectors may be either integer indices or ranges. See also Array#select.
array.zip(arg, . . . ) [or] array.zip(arg, . . . ){ | arr | block }Converts any arguments to arrays, then merges elements of array with corresponding elements from each argument.