prev - up - next - index

# Array

  The elements of an array are arbitrary Ruby objects. Arrays are formed by placing comma separated list of expressions in square brackets like:

  >     [1, 2, 3]

## SuperClass:

  `Object`

## Included Modules:

  Enumerable

## Class Methods:

  `Array[item...]`

    Creates a newly created array with arguments as elements.

  `new([size[,val]])`

    Creates a newly created array with specified size. If size is not specified, returns an empty array. val is the initial value of the elements. The default initial value is nil.

## Methods:

  `self[nth]`

    Retrieves the nth item from an array. Index starts from zero. If index is the negative, counts backward from the end of the array. The index of the last element is -1. Returns `nil`, if the nth element is not exist in the array.

    See also `self[nth] = val`.

  `self[start..end]`

    Returns an array containing the objects from start to end, including both ends. If `...` is used (instead of `..`), then end is not included. if end is larger than the length of the array, it will be rounded to the length. If start is out of an array range , returns `nil`. And if start is larger than end with in array range, returns empty array (`[]`).

    See also `self[start..end] = val`.

  `self[start, length]`

    Returns an array containing length items from start. Returns `nil` if length is negative.

    See also `self[start, length] = val`.

  `self[nth] = val`

    Changes the nth element of the array into val. If nth is larger than array length, the array shall be extended automatically. Extended region shall be initialized by `nil`.

    See also `self[nth]`.

  `self[start..end] = val`

    Replace the items from start to end with val. If `...` is used (instead of `..`) then end is not included. If val is not an array, the type of val will be converted into the Array using `to_a` method.

    See also `self[start..end]`.

  `self[start, length] = val`

    Replace the length items from start with val. If val is not an array, the type of val will be converted into the Array using `to_a`.

    See also `self[start, length]`.

    Example:

    >     ary = [1, 2, 3, 4, 5]
    >     ary[0..2] = [0, 0] # Changed to [0, 0, 4, 5]
    >     ary[1, 0] = [7]    # Changed to [0, 7, 0, 4, 5]

  `self + other`

    The array concatenation.

  `self * times`

    The array repetition.

  `self - other`

    The array subtraction. Returns a new array contains elements of the original, except which belongs other also. Duplicate items will be removed.

  `self & other`

    Returns a new array which contains elements belong to both arrays. Duplicate items will be removed.

  `self | other`

    The array join. Returns a new array which contains elements belong to either self or other. Duplicate items will be removed.

  `self << obj`

    Append a new item with value obj to the end of the array. This method returns the array itself, so that can be chained like:

    >     array << obj1 << obj2

  `self <=> other`

    Returns -1, 0, or 1 depending on whether the left argument is less than, equal to, or greater than the right argument, comparing each elements by using `<=>`.

  `assoc(key)`

    Searches in the array of arrays, looking for the array whose first element equals (compared by `==`) to key.

    >     a = [[1,2],[2,4],[3,6]]
    >     a.assoc(2)		# => [2, 4]

  `clear`

    Makes the length of the array to zero.

  `concat(other)`

    Append a items in the other array to the end of the array.

  `compact`
  `compact!`

    Removes all `nil`s from the array.

    `compact!` returns nil, if it does not modify the array.

  `delete(val)`

    Delete the item which matches to val. If the block supplied, it will be evaluated when no item matches to val.

  `delete_at(pos)`

    Removes an element at the position specified by the argument pos. Returns the removed element.

  `delete_if {...}`
  `reject!{|x|...}`

    Removes elements, which evaluated result of the block is true.

  `clone`
  `dup`

    Returns a newly created array which has the same elements to the receiver. `clone` returns the complete copy of the original array including freeze status and instance variables. On the other hand, `dup` copies the array contents only.

  `each {...}`

    Iterates over each item of the array.

  `each_index {...}`

    Iterates over each index of the array elements, that is:

    >     (0...ary.size).each {}

  `empty?`

    Returns true if the array is empty.

  `fill(val)`
  `fill(val, start[, length])`
  `fill(val, start..end)`

    Fill range of the array with val. If no range specified, whole array will be filled with val.

  `filter{|item| ..}`

    Replaces each item with the value returned from the block.

  `flatten`
  `flatten!`

    Flattens the nested array. `flatten!` modifies the receiver, and returns `nil` if the array is not nested.

  `freeze`

    Prohibits modification of the array. Modification to the freezed array raises an exception.

  `frozen`

    Returns true if the array is frozen.

  `include?(val)`

    Returns true if the array contains val.

  `index(val)`

    Returns the index of the item which equals to val. If no item found, returns nil.

  `indexes(index_1,..., index_n)`
  `indices(index_1,..., index_n)`

    Returns an array contains items at each index specified by each argument.

  `join([sep])`

    Joins the elements in the array into a single string with fields separated by the value of sep, and returns the string. If sep is not supplied, the value of `$,` is used as the default.

  `length`
  `size`

    Returns length of the array.

  `nitems`

    Returns the number of non-nil items.

  `pack(template)`

    Packs the array into a binary structure, returning the string containing the structure. The `template` is a sequence of characters that give the order and type of values, as follows:

    > `a`
    >   ASCII string(null padded)
    > `A`
    >   ASCII string(space padded)
    > `b`
    >   bit string(ascending bit order)
    > `B`
    >   bit string(descending bit order)
    > `h`
    >   hex string(low nibble first)
    > `H`
    >   hex string(high nibble first)
    > `c`
    >   char
    > `C`
    >   unsigned char
    > `s`
    >   short
    > `S`
    >   unsigned short
    > `i`
    >   int
    > `I`
    >   unsigned int
    > `l`
    >   long
    > `L`
    >   unsigned long
    > `m`
    >   string encoded in base64
    > `n`
    >   short in "network" byte-order
    > `N`
    >   long in "network" byte-order
    > `v`
    >   short in "VAX" (little-endian) byte-order
    > `V`
    >   long in "VAX" (little-endian) byte-order
    > `f`
    >   single-precision float in the native format
    > `d`
    >   A double-precision float in the native format
    > `p`
    >   A pointer to a null-terminated string.
    > `P`
    >   A pointer to a structure (fixed-length string).
    > `u`
    >   uuencoded string
    > `x`
    >   null byte
    > `X`
    >   back up a byte
    > `@`
    >   moves to absolute position

  `pop`

    Pops and returns the last value of the array, shortening the array by one. If there is no element in the array, returns `nil`.

  `push(obj...)`

    Appends obj to the last of the array.

  `rassoc(value)`

    Searches in the array of arrays, looking for the array whose second element equals (compared by `==`) to value.

    >     a = [[1,2],[2,4],[3,6]]
    >     a.rassoc(2)		# => [1, 2]

  `replace(other)`

    Copis the content of other into the array.

  `reverse`

    Returns the array of the items in reverse order.

  `reverse!`

    Replaces the items in reverse order.

  `reverse_each {...}`

    Iterates over each item of the array in reverse order.

  `rindex(val)`

    Returns the index of the last item which equals to val. If no item matched, returns nil.

  `shift`

    Removes and returns the first element of the array, and moves other elements down. Returns `nil` for empty array.

  `sort`
  `sort {|a, b|...}`
  `sort!`
  `sort! {|a, b|...}`

    Sorts the array. If `sort` is called with the block, it evaluate the block with two parameters, and use the result to compare. Without the block, it compares elements with the operator `<=>`. `sort` returns a newly created sorted array, and `sort!` executes sort in place.

  `uniq`
  `uniq!`

    Removes duplicate items from the array.

    `uniq!` returns nil, if it does not modify the array.

  `unshift(obj)`

    Inserts obj to the front of the array.

prev - up - next - index

matz@netlab.co.jp