Array

        # Array < Object

---
# Includes:
Enumerable (from ruby core)

(from ruby core)
---
An Array is an ordered, integer-indexed collection of objects, called
*elements*.  Any object may be an Array element.

## Array Indexes

Array indexing starts at 0, as in C or Java.

A positive index is an offset from the first element:
*   Index 0 indicates the first element.
*   Index 1 indicates the second element.
*   ...


A negative index is an offset, backwards, from the end of the array:
*   Index -1 indicates the last element.
*   Index -2 indicates the next-to-last element.
*   ...


A non-negative index is *in range* if it is smaller than the size of the
array.  For a 3-element array:
*   Indexes 0 through 2 are in range.
*   Index 3 is out of range.


A negative index is *in range* if its absolute value is not larger than
the size of the array.  For a 3-element array:
*   Indexes -1 through -3 are in range.
*   Index -4 is out of range.


## Creating Arrays

You can create an Array object explicitly with:

*   An [array
    literal](doc/syntax/literals_rdoc.html#label-Array+Literals).


You can convert certain objects to Arrays with:

*   Method [Array](Kernel.html#method-i-Array).


An Array can contain different types of objects.  For example, the array
below contains an Integer, a String and a Float:

    ary = [1, "two", 3.0] #=> [1, "two", 3.0]

An array can also be created by calling Array.new with zero, one (the
initial size of the Array) or two arguments (the initial size and a
default object).

    ary = Array.new    #=> []
    Array.new(3)       #=> [nil, nil, nil]
    Array.new(3, true) #=> [true, true, true]

Note that the second argument populates the array with references to the
same object.  Therefore, it is only recommended in cases when you need
to instantiate arrays with natively immutable objects such as Symbols,
numbers, true or false.

To create an array with separate objects a block can be passed instead.
This method is safe to use with mutable objects such as hashes, strings
or other arrays:

    Array.new(4) {Hash.new}    #=> [{}, {}, {}, {}]
    Array.new(4) {|i| i.to_s } #=> ["0", "1", "2", "3"]

This is also a quick way to build up multi-dimensional arrays:

    empty_table = Array.new(3) {Array.new(3)}
    #=> [[nil, nil, nil], [nil, nil, nil], [nil, nil, nil]]

An array can also be created by using the Array() method, provided by
Kernel, which tries to call #to_ary, then #to_a on its argument.

    Array({:a => "a", :b => "b"}) #=> [[:a, "a"], [:b, "b"]]

## Example Usage

In addition to the methods it mixes in through the Enumerable module,
the Array class has proprietary methods for accessing, searching and
otherwise manipulating arrays.

Some of the more common ones are illustrated below.

## Accessing Elements

Elements in an array can be retrieved using the Array#[] method.  It can
take a single integer argument (a numeric index), a pair of arguments
(start and length) or a range. Negative indices start counting from the
end, with -1 being the last element.

    arr = [1, 2, 3, 4, 5, 6]
    arr[2]    #=> 3
    arr[100]  #=> nil
    arr[-3]   #=> 4
    arr[2, 3] #=> [3, 4, 5]
    arr[1..4] #=> [2, 3, 4, 5]
    arr[1..-3] #=> [2, 3, 4]

Another way to access a particular array element is by using the #at
method

    arr.at(0) #=> 1

The #slice method works in an identical manner to Array#[].

To raise an error for indices outside of the array bounds or else to
provide a default value when that happens, you can use #fetch.

    arr = ['a', 'b', 'c', 'd', 'e', 'f']
    arr.fetch(100) #=> IndexError: index 100 outside of array bounds: -6...6
    arr.fetch(100, "oops") #=> "oops"

The special methods #first and #last will return the first and last
elements of an array, respectively.

    arr.first #=> 1
    arr.last  #=> 6

To return the first `n` elements of an array, use #take

    arr.take(3) #=> [1, 2, 3]

#drop does the opposite of #take, by returning the elements after `n`
elements have been dropped:

    arr.drop(3) #=> [4, 5, 6]

## Obtaining Information about an Array

Arrays keep track of their own length at all times.  To query an array
about the number of elements it contains, use #length, #count or #size.

    browsers = ['Chrome', 'Firefox', 'Safari', 'Opera', 'IE']
    browsers.length #=> 5
    browsers.count #=> 5

To check whether an array contains any elements at all

    browsers.empty? #=> false

To check whether a particular item is included in the array

    browsers.include?('Konqueror') #=> false

## Adding Items to Arrays

Items can be added to the end of an array by using either #push or #<<

    arr = [1, 2, 3, 4]
    arr.push(5) #=> [1, 2, 3, 4, 5]
    arr << 6    #=> [1, 2, 3, 4, 5, 6]

#unshift will add a new item to the beginning of an array.

    arr.unshift(0) #=> [0, 1, 2, 3, 4, 5, 6]

With #insert you can add a new element to an array at any position.

    arr.insert(3, 'apple')  #=> [0, 1, 2, 'apple', 3, 4, 5, 6]

Using the #insert method, you can also insert multiple values at once:

    arr.insert(3, 'orange', 'pear', 'grapefruit')
    #=> [0, 1, 2, "orange", "pear", "grapefruit", "apple", 3, 4, 5, 6]

## Removing Items from an Array

The method #pop removes the last element in an array and returns it:

    arr =  [1, 2, 3, 4, 5, 6]
    arr.pop #=> 6
    arr #=> [1, 2, 3, 4, 5]

To retrieve and at the same time remove the first item, use #shift:

    arr.shift #=> 1
    arr #=> [2, 3, 4, 5]

To delete an element at a particular index:

    arr.delete_at(2) #=> 4
    arr #=> [2, 3, 5]

To delete a particular element anywhere in an array, use #delete:

    arr = [1, 2, 2, 3]
    arr.delete(2) #=> 2
    arr #=> [1,3]

A useful method if you need to remove `nil` values from an array is
#compact:

    arr = ['foo', 0, nil, 'bar', 7, 'baz', nil]
    arr.compact  #=> ['foo', 0, 'bar', 7, 'baz']
    arr          #=> ['foo', 0, nil, 'bar', 7, 'baz', nil]
    arr.compact! #=> ['foo', 0, 'bar', 7, 'baz']
    arr          #=> ['foo', 0, 'bar', 7, 'baz']

Another common need is to remove duplicate elements from an array.

It has the non-destructive #uniq, and destructive method #uniq!

    arr = [2, 5, 6, 556, 6, 6, 8, 9, 0, 123, 556]
    arr.uniq #=> [2, 5, 6, 556, 8, 9, 0, 123]

## Iterating over Arrays

Like all classes that include the Enumerable module, Array has an each
method, which defines what elements should be iterated over and how.  In
case of Array's #each, all elements in the Array instance are yielded to
the supplied block in sequence.

Note that this operation leaves the array unchanged.

    arr = [1, 2, 3, 4, 5]
    arr.each {|a| print a -= 10, " "}
    # prints: -9 -8 -7 -6 -5
    #=> [1, 2, 3, 4, 5]

Another sometimes useful iterator is #reverse_each which will iterate
over the elements in the array in reverse order.

    words = %w[first second third fourth fifth sixth]
    str = ""
    words.reverse_each {|word| str += "#{word} "}
    p str #=> "sixth fifth fourth third second first "

The #map method can be used to create a new array based on the original
array, but with the values modified by the supplied block:

    arr.map {|a| 2*a}     #=> [2, 4, 6, 8, 10]
    arr                   #=> [1, 2, 3, 4, 5]
    arr.map! {|a| a**2}   #=> [1, 4, 9, 16, 25]
    arr                   #=> [1, 4, 9, 16, 25]

## Selecting Items from an Array

Elements can be selected from an array according to criteria defined in
a block.  The selection can happen in a destructive or a non-destructive
manner.  While the destructive operations will modify the array they
were called on, the non-destructive methods usually return a new array
with the selected elements, but leave the original array unchanged.

### Non-destructive Selection

    arr = [1, 2, 3, 4, 5, 6]
    arr.select {|a| a > 3}       #=> [4, 5, 6]
    arr.reject {|a| a < 3}       #=> [3, 4, 5, 6]
    arr.drop_while {|a| a < 4}   #=> [4, 5, 6]
    arr                          #=> [1, 2, 3, 4, 5, 6]

### Destructive Selection

#select! and #reject! are the corresponding destructive methods to
#select and #reject

Similar to #select vs. #reject, #delete_if and #keep_if have the exact
opposite result when supplied with the same block:

    arr.delete_if {|a| a < 4}   #=> [4, 5, 6]
    arr                         #=> [4, 5, 6]

    arr = [1, 2, 3, 4, 5, 6]
    arr.keep_if {|a| a < 4}   #=> [1, 2, 3]
    arr                       #=> [1, 2, 3]

## What's Here

First, what's elsewhere. Class Array:

*   Inherits from [class
    Object](Object.html#class-Object-label-What-27s+Here).
*   Includes [module
    Enumerable](Enumerable.html#module-Enumerable-label-What-27s+Here),
    which provides dozens of additional methods.


Here, class Array provides methods that are useful for:

*   [Creating an
    Array](#class-Array-label-Methods+for+Creating+an+Array)
*   [Querying](#class-Array-label-Methods+for+Querying)
*   [Comparing](#class-Array-label-Methods+for+Comparing)
*   [Fetching](#class-Array-label-Methods+for+Fetching)
*   [Assigning](#class-Array-label-Methods+for+Assigning)
*   [Deleting](#class-Array-label-Methods+for+Deleting)
*   [Combining](#class-Array-label-Methods+for+Combining)
*   [Iterating](#class-Array-label-Methods+for+Iterating)
*   [Converting](#class-Array-label-Methods+for+Converting)
*   [And more....](#class-Array-label-Other+Methods)


### Methods for Creating an Array

::[]
:   Returns a new array populated with given objects.
::new
:   Returns a new array.
::try_convert
:   Returns a new array created from a given object.


### Methods for Querying

#length, #size
:   Returns the count of elements.
#include?
:   Returns whether any element `==` a given object.
#empty?
:   Returns whether there are no elements.
#all?
:   Returns whether all elements meet a given criterion.
#any?
:   Returns whether any element meets a given criterion.
#none?
:   Returns whether no element `==` a given object.
#one?
:   Returns whether exactly one element `==` a given object.
#count
:   Returns the count of elements that meet a given criterion.
#find_index, #index
:   Returns the index of the first element that meets a given criterion.
#rindex
:   Returns the index of the last element that meets a given criterion.
#hash
:   Returns the integer hash code.


### Methods for Comparing
[#<=>](#method-i-3C-3D-3E)
:   Returns -1, 0, or 1 as `self` is less than, equal to, or greater
    than a given object.
[#==](#method-i-3D-3D)
:   Returns whether each element in `self` is `==` to the corresponding
    element in a given object.
#eql?
:   Returns whether each element in `self` is `eql?` to the
    corresponding element in a given object.


### Methods for Fetching

These methods do not modify `self`.

#[]
:   Returns one or more elements.
#fetch
:   Returns the element at a given offset.
#first
:   Returns one or more leading elements.
#last
:   Returns one or more trailing elements.
#max
:   Returns one or more maximum-valued elements, as determined by `<=>`
    or a given block.
#max
:   Returns one or more minimum-valued elements, as determined by `<=>`
    or a given block.
#minmax
:   Returns the minimum-valued and maximum-valued elements, as
    determined by `<=>` or a given block.
#assoc
:   Returns the first element that is an array whose first element `==`
    a given object.
#rassoc
:   Returns the first element that is an array whose second element `==`
    a given object.
#at
:   Returns the element at a given offset.
#values_at
:   Returns the elements at given offsets.
#dig
:   Returns the object in nested objects that is specified by a given
    index and additional arguments.
#drop
:   Returns trailing elements as determined by a given index.
#take
:   Returns leading elements as determined by a given index.
#drop_while
:   Returns trailing elements as determined by a given block.
#take_while
:   Returns leading elements as determined by a given block.
#slice
:   Returns consecutive elements as determined by a given argument.
#sort
:   Returns all elements in an order determined by `<=>` or a given
    block.
#reverse
:   Returns all elements in reverse order.
#compact
:   Returns an array containing all non-`nil` elements.
#select, #filter
:   Returns an array containing elements selected by a given block.
#uniq
:   Returns an array containing non-duplicate elements.
#rotate
:   Returns all elements with some rotated from one end to the other.
#bsearch
:   Returns an element selected via a binary search as determined by a
    given block.
#bsearch_index
:   Returns the index of an element selected via a binary search as
    determined by a given block.
#sample
:   Returns one or more random elements.
#shuffle
:   Returns elements in a random order.


### Methods for Assigning

These methods add, replace, or reorder elements in `self`.

#[]=
:   Assigns specified elements with a given object.
#push, #append, #<<
:   Appends trailing elements.
#unshift, #prepend
:   Prepends leading elements.
#insert
:   Inserts given objects at a given offset; does not replace elements.
#concat
:   Appends all elements from given arrays.
#fill
:   Replaces specified elements with specified objects.
#replace
:   Replaces the content of `self` with the content of a given array.
#reverse!
:   Replaces `self` with its elements reversed.
#rotate!
:   Replaces `self` with its elements rotated.
#shuffle!
:   Replaces `self` with its elements in random order.
#sort!
:   Replaces `self` with its elements sorted, as determined by `<=>` or
    a given block.
#sort_by!
:   Replaces `self` with its elements sorted, as determined by a given
    block.


### Methods for Deleting

Each of these methods removes elements from `self`:

#pop
:   Removes and returns the last element.
#shift
:   Removes and returns the first element.
#compact!
:   Removes all non-`nil` elements.
#delete
:   Removes elements equal to a given object.
#delete_at
:   Removes the element at a given offset.
#delete_if
:   Removes elements specified by a given block.
#keep_if
:   Removes elements not specified by a given block.
#reject!
:   Removes elements specified by a given block.
#select!, #filter!
:   Removes elements not specified by a given block.
#slice!
:   Removes and returns a sequence of elements.
#uniq!
:   Removes duplicates.


### Methods for Combining

[#&](#method-i-26)
:   Returns an array containing elements found both in `self` and a
    given array.
#intersection
:   Returns an array containing elements found both in `self` and in
    each given array.
#+
:   Returns an array containing all elements of `self` followed by all
    elements of a given array.
#-
:   Returns an array containiing all elements of `self` that are not
    found in a given array.
[#|](#method-i-7C)
:   Returns an array containing all elements of `self` and all elements
    of a given array, duplicates removed.
#union
:   Returns an array containing all elements of `self` and all elements
    of given arrays, duplicates removed.
#difference
:   Returns an array containing all elements of `self` that are not
    found in any of the given arrays..
#product
:   Returns or yields all combinations of elements from `self` and given
    arrays.


### Methods for Iterating

#each
:   Passes each element to a given block.
#reverse_each
:   Passes each element, in reverse order, to a given block.
#each_index
:   Passes each element index to a given block.
#cycle
:   Calls a given block with each element, then does so again, for a
    specified number of times, or forever.
#combination
:   Calls a given block with combinations of elements of `self`; a
    combination does not use the same element more than once.
#permutation
:   Calls a given block with permutations of elements of `self`; a
    permutation does not use the same element more than once.
#repeated_combination
:   Calls a given block with combinations of elements of `self`; a
    combination may use the same element more than once.
#repeated_permutation
:   Calls a given block with permutations of elements of `self`; a
    permutation may use the same element more than once.


### Methods for Converting

#map, #collect
:   Returns an array containing the block return-value for each element.
#map!, #collect!
:   Replaces each element with a block return-value.
#flatten
:   Returns an array that is a recursive flattening of `self`.
#flatten!
:   Replaces each nested array in `self` with the elements from that
    array.
#inspect, #to_s
:   Returns a new String containing the elements.
#join
:   Returns a newsString containing the elements joined by the field
    separator.
#to_a
:   Returns `self` or a new array containing all elements.
#to_ary
:   Returns `self`.
#to_h
:   Returns a new hash formed from the elements.
#transpose
:   Transposes `self`, which must be an array of arrays.
#zip
:   Returns a new array of arrays containing `self` and given arrays;
    follow the link for details.


### Other Methods

#*
:   Returns one of the following:
    *   With integer argument `n`, a new array that is the concatenation
        of `n` copies of `self`.
    *   With string argument `field_separator`, a new string that is
        equivalent to `join(field_separator)`.

#abbrev
:   Returns a hash of unambiguous abbreviations for elements.
#pack
:   Packs the elements into a binary sequence.
#sum
:   Returns a sum of elements according to either `+` or a given block.







for pack.c
---
# Class methods:

    []
    new
    try_convert

# Instance methods:

    &
    *
    +
    -
    <<
    <=>
    ==
    []
    []=
    abbrev
    all?
    any?
    append
    assoc
    at
    bsearch
    bsearch_index
    clear
    collect
    collect!
    combination
    compact
    compact!
    concat
    count
    cycle
    deconstruct
    delete
    delete_at
    delete_if
    difference
    dig
    drop
    drop_while
    each
    each_index
    empty?
    eql?
    fetch
    fill
    filter
    filter!
    find_index
    first
    flatten
    flatten!
    hash
    include?
    index
    initialize_copy
    insert
    inspect
    intersect?
    intersection
    join
    keep_if
    last
    length
    map
    map!
    max
    min
    minmax
    none?
    one?
    pack
    permutation
    pop
    prepend
    product
    push
    rassoc
    reject
    reject!
    repeated_combination
    repeated_permutation
    replace
    reverse
    reverse!
    reverse_each
    rindex
    rotate
    rotate!
    sample
    select
    select!
    shelljoin
    shift
    shuffle
    shuffle!
    size
    slice
    slice!
    sort
    sort!
    sort_by!
    sum
    take
    take_while
    to_a
    to_ary
    to_h
    to_s
    transpose
    union
    uniq
    uniq!
    unshift
    values_at
    zip
    |