# class Array

An Array is an ordered, integer-indexed collection of objects, called elements. Any object (even another array) may be an array element, and an array can contain objects of different types.

## 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 and only 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 and only 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.

Although the effective index into an array is always an integer, some methods (both within and outside of class Array) accept one or more non-integer arguments that are integer-convertible objects.

## Creating Arrays¶ ↑

You can create an Array object explicitly with:

- An array literal:

      [1, 'one', :one, [2, 'two', :two]]

- A array literal:

      %w[foo bar baz] # => ["foo", "bar", "baz"]
      %w[1 % *]       # => ["1", "%", "*"]

- A array literal:

      %i[foo bar baz] # => [:foo, :bar, :baz]
      %i[1 % *]       # => [:"1", :%, :*]

- Method `Kernel#Array`:

      Array(["a", "b"])             # => ["a", "b"]
      Array(1..5)                   # => [1, 2, 3, 4, 5]
      Array(key: :value)            # => [[:key, :value]]
      Array(nil)                    # => []
      Array(1)                      # => [1]
      Array({:a => "a", :b => "b"}) # => [[:a, "a"], [:b, "b"]]

- Method `Array.new`:

      Array.new               # => []
      Array.new(3)            # => [nil, nil, nil]
      Array.new(4) {Hash.new} # => [{}, {}, {}, {}]
      Array.new(3, true)      # => [true, true, true]

  Note that the last example above populates the array with references to the same object. This is recommended only in cases where that object is a natively immutable object such as a symbol, a numeric, `nil`, `true`, or `false`.

  Another way to create an array with various objects, using a block; this usage is safe for mutable objects such as hashes, strings or other arrays:

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

  Here is a way to create a multi-dimensional array:

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

A number of Ruby methods, both in the core and in the standard library, provide instance method `to_a`, which converts an object to an array.

- `ARGF#to_a`

- `Array#to_a`

- `Enumerable#to_a`

- `Hash#to_a`

- `MatchData#to_a`

- `NilClass#to_a`

- `OptionParser#to_a`

- `Range#to_a`

- `Set#to_a`

- `Struct#to_a`

- `Time#to_a`

- `Benchmark::Tms#to_a`

- `CSV::Table#to_a`

- `Enumerator::Lazy#to_a`

- Gem::List#to_a

- `Gem::NameTuple#to_a`

- `Gem::Platform#to_a`

- `Gem::RequestSet::Lockfile::Tokenizer#to_a`

- `Gem::SourceList#to_a`

- `OpenSSL::X509::Extension#to_a`

- `OpenSSL::X509::Name#to_a`

- Racc::ISet#to_a

- `Rinda::RingFinger#to_a`

- `Ripper::Lexer::Elem#to_a`

- `RubyVM::InstructionSequence#to_a`

- `YAML::DBM#to_a`

## 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.

- Includes module Enumerable, which provides dozens of additional methods.

Here, class Array provides methods that are useful for:

- Creating an Array

- Querying

- Comparing

- Fetching

- Assigning

- Deleting

- Combining

- Iterating

- Converting

- And more.…

### 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¶ ↑

- `<=>`: Returns -1, 0, or 1 * as `self` is less than, equal to, or greater than a given object.

- `==`: 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.

- `min`: 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 `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¶ ↑

- `&`: 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 containing all elements of `self` that are not found in a given array.

- `|`: 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.

### Public Class Methods

[](*args) click to toggle source

Returns a new array populated with the given objects.

    Array.[]( 1, 'a', /^A/)  # => [1, "a", /^A/]
    Array[ 1, 'a', /^A/ ]    # => [1, "a", /^A/]
    [ 1, 'a', /^A/ ]         # => [1, "a", /^A/]

    static VALUE
    rb_ary_s_create(int argc, VALUE *argv, VALUE klass)
    {
        VALUE ary = ary_new(klass, argc);
        if (argc > 0 && argv) {
            ary_memcpy(ary, 0, argc, argv);
            ARY_SET_LEN(ary, argc);
        }

        return ary;
    }

new → new_empty_array click to toggle source
new(array) → new_array
new(size) → new_array
new(size, default_value) → new_array
new(size) {|index| ... } → new_array

Returns a new Array.

With no block and no arguments, returns a new empty Array object.

With no block and a single Array argument `array`, returns a new Array formed from `array`:

    a = Array.new([:foo, 'bar', 2])
    a.class # => Array
    a # => [:foo, "bar", 2]

With no block and a single `Integer` argument `size`, returns a new Array of the given size whose elements are all `nil`:

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

With no block and arguments `size` and `default_value`, returns an Array of the given size; each element is that same `default_value`:

    a = Array.new(3, 'x')
    a # => ['x', 'x', 'x']

With a block and argument `size`, returns an Array of the given size; the block is called with each successive integer `index`; the element for that `index` is the return value from the block:

    a = Array.new(3) {|index| "Element #{index}" }
    a # => ["Element 0", "Element 1", "Element 2"]

Raises `ArgumentError` if `size` is negative.

With a block and no argument, or a single argument `0`, ignores the block and returns a new empty Array.

    static VALUE
    rb_ary_initialize(int argc, VALUE *argv, VALUE ary)
    {
        long len;
        VALUE size, val;

        rb_ary_modify(ary);
        if (argc == 0) {
            rb_ary_reset(ary);
            assert(ARY_EMBED_P(ary));
            assert(ARY_EMBED_LEN(ary) == 0);
            if (rb_block_given_p()) {
                rb_warning("given block not used");
            }
            return ary;
        }
        rb_scan_args(argc, argv, "02", &size, &val);
        if (argc == 1 && !FIXNUM_P(size)) {
            val = rb_check_array_type(size);
            if (!NIL_P(val)) {
                rb_ary_replace(ary, val);
                return ary;
            }
        }

        len = NUM2LONG(size);
        /* NUM2LONG() may call size.to_int, ary can be frozen, modified, etc */
        if (len < 0) {
            rb_raise(rb_eArgError, "negative array size");
        }
        if (len > ARY_MAX_SIZE) {
            rb_raise(rb_eArgError, "array size too big");
        }
        /* recheck after argument conversion */
        rb_ary_modify(ary);
        ary_resize_capa(ary, len);
        if (rb_block_given_p()) {
            long i;

            if (argc == 2) {
                rb_warn("block supersedes default value argument");
            }
            for (i=0; i<len; i++) {
                rb_ary_store(ary, i, rb_yield(LONG2NUM(i)));
                ARY_SET_LEN(ary, i + 1);
            }
        }
        else {
            ary_memfill(ary, 0, len, val);
            ARY_SET_LEN(ary, len);
        }
        return ary;
    }

try_convert(object) → object, new_array, or nil click to toggle source

If `object` is an Array object, returns `object`.

Otherwise if `object` responds to `:to_ary`, calls `object.to_ary` and returns the result.

Returns `nil` if `object` does not respond to `:to_ary`

Raises an exception unless `object.to_ary` returns an Array object.

    static VALUE
    rb_ary_s_try_convert(VALUE dummy, VALUE ary)
    {
        return rb_check_array_type(ary);
    }

### Public Instance Methods

array & other_array → new_array click to toggle source

Returns a new Array containing each element found in both `array` and Array `other_array`; duplicates are omitted; items are compared using `eql?` (items must also implement `hash` correctly):

    [0, 1, 2, 3] & [1, 2] # => [1, 2]
    [0, 1, 0, 1] & [0, 1] # => [0, 1]

Preserves order from `array`:

    [0, 1, 2] & [3, 2, 1, 0] # => [0, 1, 2]

Related: `Array#intersection`.

    static VALUE
    rb_ary_and(VALUE ary1, VALUE ary2)
    {
        VALUE hash, ary3, v;
        st_data_t vv;
        long i;

        ary2 = to_ary(ary2);
        ary3 = rb_ary_new();
        if (RARRAY_LEN(ary1) == 0 || RARRAY_LEN(ary2) == 0) return ary3;

        if (RARRAY_LEN(ary1) <= SMALL_ARRAY_LEN && RARRAY_LEN(ary2) <= SMALL_ARRAY_LEN) {
            for (i=0; i<RARRAY_LEN(ary1); i++) {
                v = RARRAY_AREF(ary1, i);
                if (!rb_ary_includes_by_eql(ary2, v)) continue;
                if (rb_ary_includes_by_eql(ary3, v)) continue;
                rb_ary_push(ary3, v);
            }
            return ary3;
        }

        hash = ary_make_hash(ary2);

        for (i=0; i<RARRAY_LEN(ary1); i++) {
            v = RARRAY_AREF(ary1, i);
            vv = (st_data_t)v;
            if (rb_hash_stlike_delete(hash, &vv, 0)) {
                rb_ary_push(ary3, v);
            }
        }

        return ary3;
    }

array * n → new_array click to toggle source
array * string_separator → new_string

When non-negative argument `Integer` `n` is given, returns a new Array built by concatenating the `n` copies of `self`:

    a = ['x', 'y']
    a * 3 # => ["x", "y", "x", "y", "x", "y"]

When `String` argument `string_separator` is given, equivalent to `array.join(string_separator)`:

    [0, [0, 1], {foo: 0}] * ', ' # => "0, 0, 1, {:foo=>0}"

    static VALUE
    rb_ary_times(VALUE ary, VALUE times)
    {
        VALUE ary2, tmp;
        const VALUE *ptr;
        long t, len;

        tmp = rb_check_string_type(times);
        if (!NIL_P(tmp)) {
            return rb_ary_join(ary, tmp);
        }

        len = NUM2LONG(times);
        if (len == 0) {
            ary2 = ary_new(rb_cArray, 0);
            goto out;
        }
        if (len < 0) {
            rb_raise(rb_eArgError, "negative argument");
        }
        if (ARY_MAX_SIZE/len < RARRAY_LEN(ary)) {
            rb_raise(rb_eArgError, "argument too big");
        }
        len *= RARRAY_LEN(ary);

        ary2 = ary_new(rb_cArray, len);
        ARY_SET_LEN(ary2, len);

        ptr = RARRAY_CONST_PTR(ary);
        t = RARRAY_LEN(ary);
        if (0 < t) {
            ary_memcpy(ary2, 0, t, ptr);
            while (t <= len/2) {
                ary_memcpy(ary2, t, t, RARRAY_CONST_PTR(ary2));
                t *= 2;
            }
            if (t < len) {
                ary_memcpy(ary2, t, len-t, RARRAY_CONST_PTR(ary2));
            }
        }
      out:
        return ary2;
    }

array + other_array → new_array click to toggle source

Returns a new Array containing all elements of `array` followed by all elements of `other_array`:

    a = [0, 1] + [2, 3]
    a # => [0, 1, 2, 3]

Related: `concat`.

    VALUE
    rb_ary_plus(VALUE x, VALUE y)
    {
        VALUE z;
        long len, xlen, ylen;

        y = to_ary(y);
        xlen = RARRAY_LEN(x);
        ylen = RARRAY_LEN(y);
        len = xlen + ylen;
        z = rb_ary_new2(len);

        ary_memcpy(z, 0, xlen, RARRAY_CONST_PTR(x));
        ary_memcpy(z, xlen, ylen, RARRAY_CONST_PTR(y));
        ARY_SET_LEN(z, len);
        return z;
    }

array - other_array → new_array click to toggle source

Returns a new Array containing only those elements from `array` that are not found in Array `other_array`; items are compared using `eql?`; the order from `array` is preserved:

    [0, 1, 1, 2, 1, 1, 3, 1, 1] - [1] # => [0, 2, 3]
    [0, 1, 2, 3] - [3, 0] # => [1, 2]
    [0, 1, 2] - [4] # => [0, 1, 2]

Related: `Array#difference`.

    VALUE
    rb_ary_diff(VALUE ary1, VALUE ary2)
    {
        VALUE ary3;
        VALUE hash;
        long i;

        ary2 = to_ary(ary2);
        if (RARRAY_LEN(ary2) == 0) { return ary_make_shared_copy(ary1); }
        ary3 = rb_ary_new();

        if (RARRAY_LEN(ary1) <= SMALL_ARRAY_LEN || RARRAY_LEN(ary2) <= SMALL_ARRAY_LEN) {
            for (i=0; i<RARRAY_LEN(ary1); i++) {
                VALUE elt = rb_ary_elt(ary1, i);
                if (rb_ary_includes_by_eql(ary2, elt)) continue;
                rb_ary_push(ary3, elt);
            }
            return ary3;
        }

        hash = ary_make_hash(ary2);
        for (i=0; i<RARRAY_LEN(ary1); i++) {
            if (rb_hash_stlike_lookup(hash, RARRAY_AREF(ary1, i), NULL)) continue;
            rb_ary_push(ary3, rb_ary_elt(ary1, i));
        }

        return ary3;
    }

array << object → self click to toggle source

Appends `object` to `self`; returns `self`:

    a = [:foo, 'bar', 2]
    a << :baz # => [:foo, "bar", 2, :baz]

Appends `object` as one element, even if it is another Array:

    a = [:foo, 'bar', 2]
    a1 = a << [3, 4]
    a1 # => [:foo, "bar", 2, [3, 4]]

    VALUE
    rb_ary_push(VALUE ary, VALUE item)
    {
        long idx = RARRAY_LEN((ary_verify(ary), ary));
        VALUE target_ary = ary_ensure_room_for_push(ary, 1);
        RARRAY_PTR_USE(ary, ptr, {
            RB_OBJ_WRITE(target_ary, &ptr[idx], item);
        });
        ARY_SET_LEN(ary, idx + 1);
        ary_verify(ary);
        return ary;
    }

array <=> other_array → -1, 0, or 1 click to toggle source

Returns -1, 0, or 1 as `self` is less than, equal to, or greater than `other_array`. For each index `i` in `self`, evaluates `result = self[i] <=> other_array[i]`.

Returns -1 if any result is -1:

    [0, 1, 2] <=> [0, 1, 3] # => -1

Returns 1 if any result is 1:

    [0, 1, 2] <=> [0, 1, 1] # => 1

When all results are zero:

- Returns -1 if `array` is smaller than `other_array`:

      [0, 1, 2] <=> [0, 1, 2, 3] # => -1

- Returns 1 if `array` is larger than `other_array`:

      [0, 1, 2] <=> [0, 1] # => 1

- Returns 0 if `array` and `other_array` are the same size:

      [0, 1, 2] <=> [0, 1, 2] # => 0

    VALUE
    rb_ary_cmp(VALUE ary1, VALUE ary2)
    {
        long len;
        VALUE v;

        ary2 = rb_check_array_type(ary2);
        if (NIL_P(ary2)) return Qnil;
        if (ary1 == ary2) return INT2FIX(0);
        v = rb_exec_recursive_paired(recursive_cmp, ary1, ary2, ary2);
        if (!UNDEF_P(v)) return v;
        len = RARRAY_LEN(ary1) - RARRAY_LEN(ary2);
        if (len == 0) return INT2FIX(0);
        if (len > 0) return INT2FIX(1);
        return INT2FIX(-1);
    }

array == other_array → true or false click to toggle source

Returns `true` if both `array.size == other_array.size` and for each index `i` in `array`, `array[i] == other_array[i]`:

    a0 = [:foo, 'bar', 2]
    a1 = [:foo, 'bar', 2.0]
    a1 == a0 # => true
    [] == [] # => true

Otherwise, returns `false`.

This method is different from method `Array#eql?`, which compares elements using `Object#eql?`.

    static VALUE
    rb_ary_equal(VALUE ary1, VALUE ary2)
    {
        if (ary1 == ary2) return Qtrue;
        if (!RB_TYPE_P(ary2, T_ARRAY)) {
            if (!rb_respond_to(ary2, idTo_ary)) {
                return Qfalse;
            }
            return rb_equal(ary2, ary1);
        }
        if (RARRAY_LEN(ary1) != RARRAY_LEN(ary2)) return Qfalse;
        if (RARRAY_CONST_PTR(ary1) == RARRAY_CONST_PTR(ary2)) return Qtrue;
        return rb_exec_recursive_paired(recursive_equal, ary1, ary2, ary2);
    }

array[index] → object or nil click to toggle source
array[start, length] → object or nil
array[range] → object or nil
array[aseq] → object or nil

Returns elements from `self`; does not modify `self`.

When a single `Integer` argument `index` is given, returns the element at offset `index`:

    a = [:foo, 'bar', 2]
    a[0] # => :foo
    a[2] # => 2
    a # => [:foo, "bar", 2]

If `index` is negative, counts relative to the end of `self`:

    a = [:foo, 'bar', 2]
    a[-1] # => 2
    a[-2] # => "bar"

If `index` is out of range, returns `nil`.

When two `Integer` arguments `start` and `length` are given, returns a new Array of size `length` containing successive elements beginning at offset `start`:

    a = [:foo, 'bar', 2]
    a[0, 2] # => [:foo, "bar"]
    a[1, 2] # => ["bar", 2]

If `start + length` is greater than `self.length`, returns all elements from offset `start` to the end:

    a = [:foo, 'bar', 2]
    a[0, 4] # => [:foo, "bar", 2]
    a[1, 3] # => ["bar", 2]
    a[2, 2] # => [2]

If `start == self.size` and `length >= 0`, returns a new empty Array.

If `length` is negative, returns `nil`.

When a single `Range` argument `range` is given, treats `range.min` as `start` above and `range.size` as `length` above:

    a = [:foo, 'bar', 2]
    a[0..1] # => [:foo, "bar"]
    a[1..2] # => ["bar", 2]

Special case: If `range.start == a.size`, returns a new empty Array.

If `range.end` is negative, calculates the end index from the end:

    a = [:foo, 'bar', 2]
    a[0..-1] # => [:foo, "bar", 2]
    a[0..-2] # => [:foo, "bar"]
    a[0..-3] # => [:foo]

If `range.start` is negative, calculates the start index from the end:

    a = [:foo, 'bar', 2]
    a[-1..2] # => [2]
    a[-2..2] # => ["bar", 2]
    a[-3..2] # => [:foo, "bar", 2]

If `range.start` is larger than the array size, returns `nil`.

    a = [:foo, 'bar', 2]
    a[4..1] # => nil
    a[4..0] # => nil
    a[4..-1] # => nil

When a single `Enumerator::ArithmeticSequence` argument `aseq` is given, returns an Array of elements corresponding to the indexes produced by the sequence.

    a = ['--', 'data1', '--', 'data2', '--', 'data3']
    a[(1..).step(2)] # => ["data1", "data2", "data3"]

Unlike slicing with range, if the start or the end of the arithmetic sequence is larger than array size, throws `RangeError`.

    a = ['--', 'data1', '--', 'data2', '--', 'data3']
    a[(1..11).step(2)]
    # RangeError (((1..11).step(2)) out of range)
    a[(7..).step(2)]
    # RangeError (((7..).step(2)) out of range)

If given a single argument, and its type is not one of the listed, tries to convert it to `Integer`, and raises if it is impossible:

    a = [:foo, 'bar', 2]
    # Raises TypeError (no implicit conversion of Symbol into Integer):
    a[:foo]

    VALUE
    rb_ary_aref(int argc, const VALUE *argv, VALUE ary)
    {
        rb_check_arity(argc, 1, 2);
        if (argc == 2) {
            return rb_ary_aref2(ary, argv[0], argv[1]);
        }
        return rb_ary_aref1(ary, argv[0]);
    }

Also aliased as: slice
array[index] = object → object click to toggle source
array[start, length] = object → object
array[range] = object → object

Assigns elements in `self`; returns the given `object`.

When `Integer` argument `index` is given, assigns `object` to an element in `self`.

If `index` is non-negative, assigns `object` the element at offset `index`:

    a = [:foo, 'bar', 2]
    a[0] = 'foo' # => "foo"
    a # => ["foo", "bar", 2]

If `index` is greater than `self.length`, extends the array:

    a = [:foo, 'bar', 2]
    a[7] = 'foo' # => "foo"
    a # => [:foo, "bar", 2, nil, nil, nil, nil, "foo"]

If `index` is negative, counts backwards from the end of the array:

    a = [:foo, 'bar', 2]
    a[-1] = 'two' # => "two"
    a # => [:foo, "bar", "two"]

When `Integer` arguments `start` and `length` are given and `object` is not an Array, removes `length - 1` elements beginning at offset `start`, and assigns `object` at offset `start`:

    a = [:foo, 'bar', 2]
    a[0, 2] = 'foo' # => "foo"
    a # => ["foo", 2]

If `start` is negative, counts backwards from the end of the array:

    a = [:foo, 'bar', 2]
    a[-2, 2] = 'foo' # => "foo"
    a # => [:foo, "foo"]

If `start` is non-negative and outside the array (`>= self.size`), extends the array with `nil`, assigns `object` at offset `start`, and ignores `length`:

    a = [:foo, 'bar', 2]
    a[6, 50] = 'foo' # => "foo"
    a # => [:foo, "bar", 2, nil, nil, nil, "foo"]

If `length` is zero, shifts elements at and following offset `start` and assigns `object` at offset `start`:

    a = [:foo, 'bar', 2]
    a[1, 0] = 'foo' # => "foo"
    a # => [:foo, "foo", "bar", 2]

If `length` is too large for the existing array, does not extend the array:

    a = [:foo, 'bar', 2]
    a[1, 5] = 'foo' # => "foo"
    a # => [:foo, "foo"]

When `Range` argument `range` is given and `object` is an Array, removes `length - 1` elements beginning at offset `start`, and assigns `object` at offset `start`:

    a = [:foo, 'bar', 2]
    a[0..1] = 'foo' # => "foo"
    a # => ["foo", 2]

if `range.begin` is negative, counts backwards from the end of the array:

    a = [:foo, 'bar', 2]
    a[-2..2] = 'foo' # => "foo"
    a # => [:foo, "foo"]

If the array length is less than `range.begin`, assigns `object` at offset `range.begin`, and ignores `length`:

    a = [:foo, 'bar', 2]
    a[6..50] = 'foo' # => "foo"
    a # => [:foo, "bar", 2, nil, nil, nil, "foo"]

If `range.end` is zero, shifts elements at and following offset `start` and assigns `object` at offset `start`:

    a = [:foo, 'bar', 2]
    a[1..0] = 'foo' # => "foo"
    a # => [:foo, "foo", "bar", 2]

If `range.end` is negative, assigns `object` at offset `start`, retains `range.end.abs -1` elements past that, and removes those beyond:

    a = [:foo, 'bar', 2]
    a[1..-1] = 'foo' # => "foo"
    a # => [:foo, "foo"]
    a = [:foo, 'bar', 2]
    a[1..-2] = 'foo' # => "foo"
    a # => [:foo, "foo", 2]
    a = [:foo, 'bar', 2]
    a[1..-3] = 'foo' # => "foo"
    a # => [:foo, "foo", "bar", 2]
    a = [:foo, 'bar', 2]

If `range.end` is too large for the existing array, replaces array elements, but does not extend the array with `nil` values:

    a = [:foo, 'bar', 2]
    a[1..5] = 'foo' # => "foo"
    a # => [:foo, "foo"]

    static VALUE
    rb_ary_aset(int argc, VALUE *argv, VALUE ary)
    {
        long offset, beg, len;

        rb_check_arity(argc, 2, 3);
        rb_ary_modify_check(ary);
        if (argc == 3) {
            beg = NUM2LONG(argv[0]);
            len = NUM2LONG(argv[1]);
            return ary_aset_by_rb_ary_splice(ary, beg, len, argv[2]);
        }
        if (FIXNUM_P(argv[0])) {
            offset = FIX2LONG(argv[0]);
            return ary_aset_by_rb_ary_store(ary, offset, argv[1]);
        }
        if (rb_range_beg_len(argv[0], &beg, &len, RARRAY_LEN(ary), 1)) {
            /* check if idx is Range */
            return ary_aset_by_rb_ary_splice(ary, beg, len, argv[1]);
        }

        offset = NUM2LONG(argv[0]);
        return ary_aset_by_rb_ary_store(ary, offset, argv[1]);
    }

abbrev(pattern = nil) click to toggle source

Calculates the set of unambiguous abbreviations for the strings in `self`.

    require 'abbrev'
    %w{ car cone }.abbrev
    #=> {"car"=>"car", "ca"=>"car", "cone"=>"cone", "con"=>"cone", "co"=>"cone"}

The optional `pattern` parameter is a pattern or a string. Only input strings that match the pattern or start with the string are included in the output hash.

    %w{ fast boat day }.abbrev(/^.a/)
    #=> {"fast"=>"fast", "fas"=>"fast", "fa"=>"fast", "day"=>"day", "da"=>"day"}

    Abbrev.abbrev(%w{car box cone}, "ca")
    #=> {"car"=>"car", "ca"=>"car"}

See also `Abbrev.abbrev`

    # File lib/abbrev.rb, line 130
    def abbrev(pattern = nil)
      Abbrev::abbrev(self, pattern)
    end

all? → true or false click to toggle source
all? {|element| ... } → true or false
all?(obj) → true or false

Returns `true` if all elements of `self` meet a given criterion.

If `self` has no element, returns `true` and argument or block are not used.

With no block given and no argument, returns `true` if `self` contains only truthy elements, `false` otherwise:

    [0, 1, :foo].all? # => true
    [0, nil, 2].all? # => false
    [].all? # => true

With a block given and no argument, calls the block with each element in `self`; returns `true` if the block returns only truthy values, `false` otherwise:

    [0, 1, 2].all? { |element| element < 3 } # => true
    [0, 1, 2].all? { |element| element < 2 } # => false

If argument `obj` is given, returns `true` if `obj.===` every element, `false` otherwise:

    ['food', 'fool', 'foot'].all?(/foo/) # => true
    ['food', 'drink'].all?(/bar/) # => false
    [].all?(/foo/) # => true
    [0, 0, 0].all?(0) # => true
    [0, 1, 2].all?(1) # => false

Related: `Enumerable#all?`

    static VALUE
    rb_ary_all_p(int argc, VALUE *argv, VALUE ary)
    {
        long i, len = RARRAY_LEN(ary);

        rb_check_arity(argc, 0, 1);
        if (!len) return Qtrue;
        if (argc) {
            if (rb_block_given_p()) {
                rb_warn("given block not used");
            }
            for (i = 0; i < RARRAY_LEN(ary); ++i) {
                if (!RTEST(rb_funcall(argv[0], idEqq, 1, RARRAY_AREF(ary, i)))) return Qfalse;
            }
        }
        else if (!rb_block_given_p()) {
            for (i = 0; i < len; ++i) {
                if (!RTEST(RARRAY_AREF(ary, i))) return Qfalse;
            }
        }
        else {
            for (i = 0; i < RARRAY_LEN(ary); ++i) {
                if (!RTEST(rb_yield(RARRAY_AREF(ary, i)))) return Qfalse;
            }
        }
        return Qtrue;
    }

any? → true or false click to toggle source
any? {|element| ... } → true or false
any?(obj) → true or false

Returns `true` if any element of `self` meets a given criterion.

If `self` has no element, returns `false` and argument or block are not used.

With no block given and no argument, returns `true` if `self` has any truthy element, `false` otherwise:

    [nil, 0, false].any? # => true
    [nil, false].any? # => false
    [].any? # => false

With a block given and no argument, calls the block with each element in `self`; returns `true` if the block returns any truthy value, `false` otherwise:

    [0, 1, 2].any? {|element| element > 1 } # => true
    [0, 1, 2].any? {|element| element > 2 } # => false

If argument `obj` is given, returns `true` if `obj`.`===` any element, `false` otherwise:

    ['food', 'drink'].any?(/foo/) # => true
    ['food', 'drink'].any?(/bar/) # => false
    [].any?(/foo/) # => false
    [0, 1, 2].any?(1) # => true
    [0, 1, 2].any?(3) # => false

Related: `Enumerable#any?`

    static VALUE
    rb_ary_any_p(int argc, VALUE *argv, VALUE ary)
    {
        long i, len = RARRAY_LEN(ary);

        rb_check_arity(argc, 0, 1);
        if (!len) return Qfalse;
        if (argc) {
            if (rb_block_given_p()) {
                rb_warn("given block not used");
            }
            for (i = 0; i < RARRAY_LEN(ary); ++i) {
                if (RTEST(rb_funcall(argv[0], idEqq, 1, RARRAY_AREF(ary, i)))) return Qtrue;
            }
        }
        else if (!rb_block_given_p()) {
            for (i = 0; i < len; ++i) {
                if (RTEST(RARRAY_AREF(ary, i))) return Qtrue;
            }
        }
        else {
            for (i = 0; i < RARRAY_LEN(ary); ++i) {
                if (RTEST(rb_yield(RARRAY_AREF(ary, i)))) return Qtrue;
            }
        }
        return Qfalse;
    }

append
Alias for: push
assoc(obj) → found_array or nil click to toggle source

Returns the first element in `self` that is an Array whose first element `==` `obj`:

    a = [{foo: 0}, [2, 4], [4, 5, 6], [4, 5]]
    a.assoc(4) # => [4, 5, 6]

Returns `nil` if no such element is found.

Related: `rassoc`.

    VALUE
    rb_ary_assoc(VALUE ary, VALUE key)
    {
        long i;
        VALUE v;

        for (i = 0; i < RARRAY_LEN(ary); ++i) {
            v = rb_check_array_type(RARRAY_AREF(ary, i));
            if (!NIL_P(v) && RARRAY_LEN(v) > 0 &&
                rb_equal(RARRAY_AREF(v, 0), key))
                return v;
        }
        return Qnil;
    }

at(index) → object click to toggle source

Returns the element at `Integer` offset `index`; does not modify `self`.

    a = [:foo, 'bar', 2]
    a.at(0) # => :foo
    a.at(2) # => 2

    VALUE
    rb_ary_at(VALUE ary, VALUE pos)
    {
        return rb_ary_entry(ary, NUM2LONG(pos));
    }

bsearch {|element| ... } → object click to toggle source
bsearch → new_enumerator

Returns an element from `self` selected by a binary search.

See Binary Searching.

    static VALUE
    rb_ary_bsearch(VALUE ary)
    {
        VALUE index_result = rb_ary_bsearch_index(ary);

        if (FIXNUM_P(index_result)) {
            return rb_ary_entry(ary, FIX2LONG(index_result));
        }
        return index_result;
    }

bsearch_index {|element| ... } → integer or nil click to toggle source
bsearch_index → new_enumerator

Searches `self` as described at method `bsearch`, but returns the index of the found element instead of the element itself.

    static VALUE
    rb_ary_bsearch_index(VALUE ary)
    {
        long low = 0, high = RARRAY_LEN(ary), mid;
        int smaller = 0, satisfied = 0;
        VALUE v, val;

        RETURN_ENUMERATOR(ary, 0, 0);
        while (low < high) {
            mid = low + ((high - low) / 2);
            val = rb_ary_entry(ary, mid);
            v = rb_yield(val);
            if (FIXNUM_P(v)) {
                if (v == INT2FIX(0)) return INT2FIX(mid);
                smaller = (SIGNED_VALUE)v < 0; /* Fixnum preserves its sign-bit */
            }
            else if (v == Qtrue) {
                satisfied = 1;
                smaller = 1;
            }
            else if (!RTEST(v)) {
                smaller = 0;
            }
            else if (rb_obj_is_kind_of(v, rb_cNumeric)) {
                const VALUE zero = INT2FIX(0);
                switch (rb_cmpint(rb_funcallv(v, id_cmp, 1, &zero), v, zero)) {
                  case 0: return INT2FIX(mid);
                  case 1: smaller = 0; break;
                  case -1: smaller = 1;
                }
            }
            else {
                rb_raise(rb_eTypeError, "wrong argument type %"PRIsVALUE
                         " (must be numeric, true, false or nil)",
                         rb_obj_class(v));
            }
            if (smaller) {
                high = mid;
            }
            else {
                low = mid + 1;
            }
        }
        if (!satisfied) return Qnil;
        return INT2FIX(low);
    }

clear → self click to toggle source

Removes all elements from `self`:

    a = [:foo, 'bar', 2]
    a.clear # => []

    VALUE
    rb_ary_clear(VALUE ary)
    {
        rb_ary_modify_check(ary);
        if (ARY_SHARED_P(ary)) {
            if (!ARY_EMBED_P(ary)) {
                rb_ary_unshare(ary);
                FL_SET_EMBED(ary);
                ARY_SET_EMBED_LEN(ary, 0);
            }
        }
        else {
            ARY_SET_LEN(ary, 0);
            if (ARY_DEFAULT_SIZE * 2 < ARY_CAPA(ary)) {
                ary_resize_capa(ary, ARY_DEFAULT_SIZE * 2);
            }
        }
        ary_verify(ary);
        return ary;
    }

collect
Also aliased as: map
collect!
Also aliased as: map!
combination(n) {|element| ... } → self click to toggle source
combination(n) → new_enumerator

Calls the block, if given, with combinations of elements of `self`; returns `self`. The order of combinations is indeterminate.

When a block and an in-range positive `Integer` argument `n` (`0 < n <= self.size`) are given, calls the block with all `n`-tuple combinations of `self`.

Example:

    a = [0, 1, 2]
    a.combination(2) {|combination| p combination }

Output:

    [0, 1]
    [0, 2]
    [1, 2]

Another example:

    a = [0, 1, 2]
    a.combination(3) {|combination| p combination }

Output:

    [0, 1, 2]

When `n` is zero, calls the block once with a new empty Array:

    a = [0, 1, 2]
    a1 = a.combination(0) {|combination| p combination }

Output:

    []

When `n` is out of range (negative or larger than `self.size`), does not call the block:

    a = [0, 1, 2]
    a.combination(-1) {|combination| fail 'Cannot happen' }
    a.combination(4) {|combination| fail 'Cannot happen' }

Returns a new `Enumerator` if no block given:

    a = [0, 1, 2]
    a.combination(2) # => #<Enumerator: [0, 1, 2]:combination(2)>

    static VALUE
    rb_ary_combination(VALUE ary, VALUE num)
    {
        long i, n, len;

        n = NUM2LONG(num);
        RETURN_SIZED_ENUMERATOR(ary, 1, &num, rb_ary_combination_size);
        len = RARRAY_LEN(ary);
        if (n < 0 || len < n) {
            /* yield nothing */
        }
        else if (n == 0) {
            rb_yield(rb_ary_new2(0));
        }
        else if (n == 1) {
            for (i = 0; i < RARRAY_LEN(ary); i++) {
                rb_yield(rb_ary_new3(1, RARRAY_AREF(ary, i)));
            }
        }
        else {
            VALUE ary0 = ary_make_shared_copy(ary); /* private defensive copy of ary */
            volatile VALUE t0;
            long *stack = ALLOCV_N(long, t0, n+1);

            RBASIC_CLEAR_CLASS(ary0);
            combinate0(len, n, stack, ary0);
            ALLOCV_END(t0);
            RBASIC_SET_CLASS_RAW(ary0, rb_cArray);
        }
        return ary;
    }

compact → new_array click to toggle source

Returns a new Array containing all non-`nil` elements from `self`:

    a = [nil, 0, nil, 1, nil, 2, nil]
    a.compact # => [0, 1, 2]

    static VALUE
    rb_ary_compact(VALUE ary)
    {
        ary = rb_ary_dup(ary);
        rb_ary_compact_bang(ary);
        return ary;
    }

compact! → self or nil click to toggle source

Removes all `nil` elements from `self`.

Returns `self` if any elements removed, otherwise `nil`.

    static VALUE
    rb_ary_compact_bang(VALUE ary)
    {
        VALUE *p, *t, *end;
        long n;

        rb_ary_modify(ary);
        p = t = (VALUE *)RARRAY_CONST_PTR(ary); /* WB: no new reference */
        end = p + RARRAY_LEN(ary);

        while (t < end) {
            if (NIL_P(*t)) t++;
            else *p++ = *t++;
        }
        n = p - RARRAY_CONST_PTR(ary);
        if (RARRAY_LEN(ary) == n) {
            return Qnil;
        }
        ary_resize_smaller(ary, n);

        return ary;
    }

concat(*other_arrays) → self click to toggle source

Adds to `array` all elements from each Array in `other_arrays`; returns `self`:

    a = [0, 1]
    a.concat([2, 3], [4, 5]) # => [0, 1, 2, 3, 4, 5]

    static VALUE
    rb_ary_concat_multi(int argc, VALUE *argv, VALUE ary)
    {
        rb_ary_modify_check(ary);

        if (argc == 1) {
            rb_ary_concat(ary, argv[0]);
        }
        else if (argc > 1) {
            int i;
            VALUE args = rb_ary_hidden_new(argc);
            for (i = 0; i < argc; i++) {
                rb_ary_concat(args, argv[i]);
            }
            ary_append(ary, args);
        }

        ary_verify(ary);
        return ary;
    }

count → an_integer click to toggle source
count(obj) → an_integer
count {|element| ... } → an_integer

Returns a count of specified elements.

With no argument and no block, returns the count of all elements:

    [0, 1, 2].count # => 3
    [].count # => 0

With argument `obj`, returns the count of elements `==` to `obj`:

    [0, 1, 2, 0.0].count(0) # => 2
    [0, 1, 2].count(3) # => 0

With no argument and a block given, calls the block with each element; returns the count of elements for which the block returns a truthy value:

    [0, 1, 2, 3].count {|element| element > 1} # => 2

With argument `obj` and a block given, issues a warning, ignores the block, and returns the count of elements `==` to `obj`.

    static VALUE
    rb_ary_count(int argc, VALUE *argv, VALUE ary)
    {
        long i, n = 0;

        if (rb_check_arity(argc, 0, 1) == 0) {
            VALUE v;

            if (!rb_block_given_p())
                return LONG2NUM(RARRAY_LEN(ary));

            for (i = 0; i < RARRAY_LEN(ary); i++) {
                v = RARRAY_AREF(ary, i);
                if (RTEST(rb_yield(v))) n++;
            }
        }
        else {
            VALUE obj = argv[0];

            if (rb_block_given_p()) {
                rb_warn("given block not used");
            }
            for (i = 0; i < RARRAY_LEN(ary); i++) {
                if (rb_equal(RARRAY_AREF(ary, i), obj)) n++;
            }
        }

        return LONG2NUM(n);
    }

cycle {|element| ... } → nil click to toggle source
cycle(count) {|element| ... } → nil
cycle → new_enumerator
cycle(count) → new_enumerator

When called with positive `Integer` argument `count` and a block, calls the block with each element, then does so again, until it has done so `count` times; returns `nil`:

    output = []
    [0, 1].cycle(2) {|element| output.push(element) } # => nil
    output # => [0, 1, 0, 1]

If `count` is zero or negative, does not call the block:

    [0, 1].cycle(0) {|element| fail 'Cannot happen' } # => nil
    [0, 1].cycle(-1) {|element| fail 'Cannot happen' } # => nil

When a block is given, and argument is omitted or `nil`, cycles forever:

    # Prints 0 and 1 forever.
    [0, 1].cycle {|element| puts element }
    [0, 1].cycle(nil) {|element| puts element }

When no block is given, returns a new Enumerator:

    [0, 1].cycle(2) # => #<Enumerator: [0, 1]:cycle(2)>
    [0, 1].cycle # => # => #<Enumerator: [0, 1]:cycle>
    [0, 1].cycle.first(5) # => [0, 1, 0, 1, 0]

    static VALUE
    rb_ary_cycle(int argc, VALUE *argv, VALUE ary)
    {
        long n, i;

        rb_check_arity(argc, 0, 1);

        RETURN_SIZED_ENUMERATOR(ary, argc, argv, rb_ary_cycle_size);
        if (argc == 0 || NIL_P(argv[0])) {
            n = -1;
        }
        else {
            n = NUM2LONG(argv[0]);
            if (n <= 0) return Qnil;
        }

        while (RARRAY_LEN(ary) > 0 && (n < 0 || 0 < n--)) {
            for (i=0; i<RARRAY_LEN(ary); i++) {
                rb_yield(RARRAY_AREF(ary, i));
            }
        }
        return Qnil;
    }

delete(obj) → deleted_object click to toggle source
delete(obj) {|nosuch| ... } → deleted_object or block_return

Removes zero or more elements from `self`.

When no block is given, removes from `self` each element `ele` such that `ele == obj`; returns the last deleted element:

    s1 = 'bar'; s2 = 'bar'
    a = [:foo, s1, 2, s2]
    a.delete('bar') # => "bar"
    a # => [:foo, 2]

Returns `nil` if no elements removed.

When a block is given, removes from `self` each element `ele` such that `ele == obj`.

If any such elements are found, ignores the block and returns the last deleted element:

    s1 = 'bar'; s2 = 'bar'
    a = [:foo, s1, 2, s2]
    deleted_obj = a.delete('bar') {|obj| fail 'Cannot happen' }
    a # => [:foo, 2]

If no such elements are found, returns the block’s return value:

    a = [:foo, 'bar', 2]
    a.delete(:nosuch) {|obj| "#{obj} not found" } # => "nosuch not found"

    VALUE
    rb_ary_delete(VALUE ary, VALUE item)
    {
        VALUE v = item;
        long i1, i2;

        for (i1 = i2 = 0; i1 < RARRAY_LEN(ary); i1++) {
            VALUE e = RARRAY_AREF(ary, i1);

            if (rb_equal(e, item)) {
                v = e;
                continue;
            }
            if (i1 != i2) {
                rb_ary_store(ary, i2, e);
            }
            i2++;
        }
        if (RARRAY_LEN(ary) == i2) {
            if (rb_block_given_p()) {
                return rb_yield(item);
            }
            return Qnil;
        }

        ary_resize_smaller(ary, i2);

        ary_verify(ary);
        return v;
    }

delete_at(index) → deleted_object or nil click to toggle source

Deletes an element from `self`, per the given `Integer` `index`.

When `index` is non-negative, deletes the element at offset `index`:

    a = [:foo, 'bar', 2]
    a.delete_at(1) # => "bar"
    a # => [:foo, 2]

If index is too large, returns `nil`.

When `index` is negative, counts backward from the end of the array:

    a = [:foo, 'bar', 2]
    a.delete_at(-2) # => "bar"
    a # => [:foo, 2]

If `index` is too small (far from zero), returns nil.

    static VALUE
    rb_ary_delete_at_m(VALUE ary, VALUE pos)
    {
        return rb_ary_delete_at(ary, NUM2LONG(pos));
    }

delete_if {|element| ... } → self click to toggle source
delete_if → Enumerator

Removes each element in `self` for which the block returns a truthy value; returns `self`:

    a = [:foo, 'bar', 2, 'bat']
    a.delete_if {|element| element.to_s.start_with?('b') } # => [:foo, 2]

Returns a new `Enumerator` if no block given:

    a = [:foo, 'bar', 2]
    a.delete_if # => #<Enumerator: [:foo, "bar", 2]:delete_if>

    static VALUE
    rb_ary_delete_if(VALUE ary)
    {
        ary_verify(ary);
        RETURN_SIZED_ENUMERATOR(ary, 0, 0, ary_enum_length);
        ary_reject_bang(ary);
        return ary;
    }

difference(*other_arrays) → new_array click to toggle source

Returns a new Array containing only those elements from `self` that are not found in any of the Arrays `other_arrays`; items are compared using `eql?`; order from `self` is preserved:

    [0, 1, 1, 2, 1, 1, 3, 1, 1].difference([1]) # => [0, 2, 3]
    [0, 1, 2, 3].difference([3, 0], [1, 3]) # => [2]
    [0, 1, 2].difference([4]) # => [0, 1, 2]

Returns a copy of `self` if no arguments given.

Related: `Array#-`.

    static VALUE
    rb_ary_difference_multi(int argc, VALUE *argv, VALUE ary)
    {
        VALUE ary_diff;
        long i, length;
        volatile VALUE t0;
        bool *is_hash = ALLOCV_N(bool, t0, argc);
        ary_diff = rb_ary_new();
        length = RARRAY_LEN(ary);

        for (i = 0; i < argc; i++) {
            argv[i] = to_ary(argv[i]);
            is_hash[i] = (length > SMALL_ARRAY_LEN && RARRAY_LEN(argv[i]) > SMALL_ARRAY_LEN);
            if (is_hash[i]) argv[i] = ary_make_hash(argv[i]);
        }

        for (i = 0; i < RARRAY_LEN(ary); i++) {
            int j;
            VALUE elt = rb_ary_elt(ary, i);
            for (j = 0; j < argc; j++) {
                if (is_hash[j]) {
                    if (rb_hash_stlike_lookup(argv[j], RARRAY_AREF(ary, i), NULL))
                        break;
                }
                else {
                    if (rb_ary_includes_by_eql(argv[j], elt)) break;
                }
            }
            if (j == argc) rb_ary_push(ary_diff, elt);
        }

        ALLOCV_END(t0);

        return ary_diff;
    }

dig(index, *identifiers) → object click to toggle source

Finds and returns the object in nested objects that is specified by `index` and `identifiers`. The nested objects may be instances of various classes. See Dig Methods.

Examples:

    a = [:foo, [:bar, :baz, [:bat, :bam]]]
    a.dig(1) # => [:bar, :baz, [:bat, :bam]]
    a.dig(1, 2) # => [:bat, :bam]
    a.dig(1, 2, 0) # => :bat
    a.dig(1, 2, 3) # => nil

    static VALUE
    rb_ary_dig(int argc, VALUE *argv, VALUE self)
    {
        rb_check_arity(argc, 1, UNLIMITED_ARGUMENTS);
        self = rb_ary_at(self, *argv);
        if (!--argc) return self;
        ++argv;
        return rb_obj_dig(argc, argv, self, Qnil);
    }

drop(n) → new_array click to toggle source

Returns a new Array containing all but the first `n` element of `self`, where `n` is a non-negative `Integer`; does not modify `self`.

Examples:

    a = [0, 1, 2, 3, 4, 5]
    a.drop(0) # => [0, 1, 2, 3, 4, 5]
    a.drop(1) # => [1, 2, 3, 4, 5]
    a.drop(2) # => [2, 3, 4, 5]

    static VALUE
    rb_ary_drop(VALUE ary, VALUE n)
    {
        VALUE result;
        long pos = NUM2LONG(n);
        if (pos < 0) {
            rb_raise(rb_eArgError, "attempt to drop negative size");
        }

        result = rb_ary_subseq(ary, pos, RARRAY_LEN(ary));
        if (NIL_P(result)) result = rb_ary_new();
        return result;
    }

drop_while {|element| ... } → new_array click to toggle source
drop_while → new_enumerator

Returns a new Array containing zero or more trailing elements of `self`; does not modify `self`.

With a block given, calls the block with each successive element of `self`; stops if the block returns `false` or `nil`; returns a new Array omitting those elements for which the block returned a truthy value:

    a = [0, 1, 2, 3, 4, 5]
    a.drop_while {|element| element < 3 } # => [3, 4, 5]

With no block given, returns a new Enumerator:

    [0, 1].drop_while # => # => #<Enumerator: [0, 1]:drop_while>

    static VALUE
    rb_ary_drop_while(VALUE ary)
    {
        long i;

        RETURN_ENUMERATOR(ary, 0, 0);
        for (i = 0; i < RARRAY_LEN(ary); i++) {
            if (!RTEST(rb_yield(RARRAY_AREF(ary, i)))) break;
        }
        return rb_ary_drop(ary, LONG2FIX(i));
    }

each {|element| ... } → self click to toggle source
each → Enumerator

Iterates over array elements.

When a block given, passes each successive array element to the block; returns `self`:

    a = [:foo, 'bar', 2]
    a.each {|element|  puts "#{element.class} #{element}" }

Output:

    Symbol foo
    String bar
    Integer 2

Allows the array to be modified during iteration:

    a = [:foo, 'bar', 2]
    a.each {|element| puts element; a.clear if element.to_s.start_with?('b') }

Output:

    foo
    bar

When no block given, returns a new Enumerator:

    a = [:foo, 'bar', 2]

    e = a.each
    e # => #<Enumerator: [:foo, "bar", 2]:each>
    a1 = e.each {|element|  puts "#{element.class} #{element}" }

Output:

    Symbol foo
    String bar
    Integer 2

Related: `each_index`, `reverse_each`.

    VALUE
    rb_ary_each(VALUE ary)
    {
        long i;
        ary_verify(ary);
        RETURN_SIZED_ENUMERATOR(ary, 0, 0, ary_enum_length);
        for (i=0; i<RARRAY_LEN(ary); i++) {
            rb_yield(RARRAY_AREF(ary, i));
        }
        return ary;
    }

each_index {|index| ... } → self click to toggle source
each_index → Enumerator

Iterates over array indexes.

When a block given, passes each successive array index to the block; returns `self`:

    a = [:foo, 'bar', 2]
    a.each_index {|index|  puts "#{index} #{a[index]}" }

Output:

    0 foo
    1 bar
    2 2

Allows the array to be modified during iteration:

    a = [:foo, 'bar', 2]
    a.each_index {|index| puts index; a.clear if index > 0 }

Output:

    0
    1

When no block given, returns a new Enumerator:

    a = [:foo, 'bar', 2]
    e = a.each_index
    e # => #<Enumerator: [:foo, "bar", 2]:each_index>
    a1 = e.each {|index|  puts "#{index} #{a[index]}"}

Output:

    0 foo
    1 bar
    2 2

Related: `each`, `reverse_each`.

    static VALUE
    rb_ary_each_index(VALUE ary)
    {
        long i;
        RETURN_SIZED_ENUMERATOR(ary, 0, 0, ary_enum_length);

        for (i=0; i<RARRAY_LEN(ary); i++) {
            rb_yield(LONG2NUM(i));
        }
        return ary;
    }

empty? → true or false click to toggle source

Returns `true` if the count of elements in `self` is zero, `false` otherwise.

    static VALUE
    rb_ary_empty_p(VALUE ary)
    {
        return RBOOL(RARRAY_LEN(ary) == 0);
    }

eql? other_array → true or false click to toggle source

Returns `true` if `self` and `other_array` are the same size, and if, for each index `i` in `self`, `self[i].eql? other_array[i]`:

    a0 = [:foo, 'bar', 2]
    a1 = [:foo, 'bar', 2]
    a1.eql?(a0) # => true

Otherwise, returns `false`.

This method is different from method `Array#==`, which compares using method `Object#==`.

    static VALUE
    rb_ary_eql(VALUE ary1, VALUE ary2)
    {
        if (ary1 == ary2) return Qtrue;
        if (!RB_TYPE_P(ary2, T_ARRAY)) return Qfalse;
        if (RARRAY_LEN(ary1) != RARRAY_LEN(ary2)) return Qfalse;
        if (RARRAY_CONST_PTR(ary1) == RARRAY_CONST_PTR(ary2)) return Qtrue;
        return rb_exec_recursive_paired(recursive_eql, ary1, ary2, ary2);
    }

fetch(index) → element click to toggle source
fetch(index, default_value) → element
fetch(index) {|index| ... } → element

Returns the element at offset `index`.

With the single `Integer` argument `index`, returns the element at offset `index`:

    a = [:foo, 'bar', 2]
    a.fetch(1) # => "bar"

If `index` is negative, counts from the end of the array:

    a = [:foo, 'bar', 2]
    a.fetch(-1) # => 2
    a.fetch(-2) # => "bar"

With arguments `index` and `default_value`, returns the element at offset `index` if index is in range, otherwise returns `default_value`:

    a = [:foo, 'bar', 2]
    a.fetch(1, nil) # => "bar"

With argument `index` and a block, returns the element at offset `index` if index is in range (and the block is not called); otherwise calls the block with index and returns its return value:

    a = [:foo, 'bar', 2]
    a.fetch(1) {|index| raise 'Cannot happen' } # => "bar"
    a.fetch(50) {|index| "Value for #{index}" } # => "Value for 50"

    static VALUE
    rb_ary_fetch(int argc, VALUE *argv, VALUE ary)
    {
        VALUE pos, ifnone;
        long block_given;
        long idx;

        rb_scan_args(argc, argv, "11", &pos, &ifnone);
        block_given = rb_block_given_p();
        if (block_given && argc == 2) {
            rb_warn("block supersedes default value argument");
        }
        idx = NUM2LONG(pos);

        if (idx < 0) {
            idx +=  RARRAY_LEN(ary);
        }
        if (idx < 0 || RARRAY_LEN(ary) <= idx) {
            if (block_given) return rb_yield(pos);
            if (argc == 1) {
                rb_raise(rb_eIndexError, "index %ld outside of array bounds: %ld...%ld",
                            idx - (idx < 0 ? RARRAY_LEN(ary) : 0), -RARRAY_LEN(ary), RARRAY_LEN(ary));
            }
            return ifnone;
        }
        return RARRAY_AREF(ary, idx);
    }

fill(obj) → self click to toggle source
fill(obj, start) → self
fill(obj, start, length) → self
fill(obj, range) → self
fill {|index| ... } → self
fill(start) {|index| ... } → self
fill(start, length) {|index| ... } → self
fill(range) {|index| ... } → self

Replaces specified elements in `self` with specified objects; returns `self`.

With argument `obj` and no block given, replaces all elements with that one object:

    a = ['a', 'b', 'c', 'd']
    a # => ["a", "b", "c", "d"]
    a.fill(:X) # => [:X, :X, :X, :X]

With arguments `obj` and `Integer` `start`, and no block given, replaces elements based on the given start.

If `start` is in range (`0 <= start < array.size`), replaces all elements from offset `start` through the end:

    a = ['a', 'b', 'c', 'd']
    a.fill(:X, 2) # => ["a", "b", :X, :X]

If `start` is too large (`start >= array.size`), does nothing:

    a = ['a', 'b', 'c', 'd']
    a.fill(:X, 4) # => ["a", "b", "c", "d"]
    a = ['a', 'b', 'c', 'd']
    a.fill(:X, 5) # => ["a", "b", "c", "d"]

If `start` is negative, counts from the end (starting index is `start + array.size`):

    a = ['a', 'b', 'c', 'd']
    a.fill(:X, -2) # => ["a", "b", :X, :X]

If `start` is too small (less than and far from zero), replaces all elements:

    a = ['a', 'b', 'c', 'd']
    a.fill(:X, -6) # => [:X, :X, :X, :X]
    a = ['a', 'b', 'c', 'd']
    a.fill(:X, -50) # => [:X, :X, :X, :X]

With arguments `obj`, `Integer` `start`, and `Integer` `length`, and no block given, replaces elements based on the given `start` and `length`.

If `start` is in range, replaces `length` elements beginning at offset `start`:

    a = ['a', 'b', 'c', 'd']
    a.fill(:X, 1, 1) # => ["a", :X, "c", "d"]

If `start` is negative, counts from the end:

    a = ['a', 'b', 'c', 'd']
    a.fill(:X, -2, 1) # => ["a", "b", :X, "d"]

If `start` is large (`start >= array.size`), extends `self` with `nil`:

    a = ['a', 'b', 'c', 'd']
    a.fill(:X, 5, 0) # => ["a", "b", "c", "d", nil]
    a = ['a', 'b', 'c', 'd']
    a.fill(:X, 5, 2) # => ["a", "b", "c", "d", nil, :X, :X]

If `length` is zero or negative, replaces no elements:

    a = ['a', 'b', 'c', 'd']
    a.fill(:X, 1, 0) # => ["a", "b", "c", "d"]
    a.fill(:X, 1, -1) # => ["a", "b", "c", "d"]

With arguments `obj` and `Range` `range`, and no block given, replaces elements based on the given range.

If the range is positive and ascending (`0 < range.begin <= range.end`), replaces elements from `range.begin` to `range.end`:

    a = ['a', 'b', 'c', 'd']
    a.fill(:X, (1..1)) # => ["a", :X, "c", "d"]

If `range.first` is negative, replaces no elements:

    a = ['a', 'b', 'c', 'd']
    a.fill(:X, (-1..1)) # => ["a", "b", "c", "d"]

If `range.last` is negative, counts from the end:

    a = ['a', 'b', 'c', 'd']
    a.fill(:X, (0..-2)) # => [:X, :X, :X, "d"]
    a = ['a', 'b', 'c', 'd']
    a.fill(:X, (1..-2)) # => ["a", :X, :X, "d"]

If `range.last` and `range.last` are both negative, both count from the end of the array:

    a = ['a', 'b', 'c', 'd']
    a.fill(:X, (-1..-1)) # => ["a", "b", "c", :X]
    a = ['a', 'b', 'c', 'd']
    a.fill(:X, (-2..-2)) # => ["a", "b", :X, "d"]

With no arguments and a block given, calls the block with each index; replaces the corresponding element with the block’s return value:

    a = ['a', 'b', 'c', 'd']
    a.fill { |index| "new_#{index}" } # => ["new_0", "new_1", "new_2", "new_3"]

With argument `start` and a block given, calls the block with each index from offset `start` to the end; replaces the corresponding element with the block’s return value.

If start is in range (`0 <= start < array.size`), replaces from offset `start` to the end:

    a = ['a', 'b', 'c', 'd']
    a.fill(1) { |index| "new_#{index}" } # => ["a", "new_1", "new_2", "new_3"]

If `start` is too large(`start >= array.size`), does nothing:

    a = ['a', 'b', 'c', 'd']
    a.fill(4) { |index| fail 'Cannot happen' } # => ["a", "b", "c", "d"]
    a = ['a', 'b', 'c', 'd']
    a.fill(4) { |index| fail 'Cannot happen' } # => ["a", "b", "c", "d"]

If `start` is negative, counts from the end:

    a = ['a', 'b', 'c', 'd']
    a.fill(-2) { |index| "new_#{index}" } # => ["a", "b", "new_2", "new_3"]

If start is too small (`start <= -array.size`, replaces all elements:

    a = ['a', 'b', 'c', 'd']
    a.fill(-6) { |index| "new_#{index}" } # => ["new_0", "new_1", "new_2", "new_3"]
    a = ['a', 'b', 'c', 'd']
    a.fill(-50) { |index| "new_#{index}" } # => ["new_0", "new_1", "new_2", "new_3"]

With arguments `start` and `length`, and a block given, calls the block for each index specified by start length; replaces the corresponding element with the block’s return value.

If `start` is in range, replaces `length` elements beginning at offset `start`:

    a = ['a', 'b', 'c', 'd']
    a.fill(1, 1) { |index| "new_#{index}" } # => ["a", "new_1", "c", "d"]

If start is negative, counts from the end:

    a = ['a', 'b', 'c', 'd']
    a.fill(-2, 1) { |index| "new_#{index}" } # => ["a", "b", "new_2", "d"]

If `start` is large (`start >= array.size`), extends `self` with `nil`:

    a = ['a', 'b', 'c', 'd']
    a.fill(5, 0) { |index| "new_#{index}" } # => ["a", "b", "c", "d", nil]
    a = ['a', 'b', 'c', 'd']
    a.fill(5, 2) { |index| "new_#{index}" } # => ["a", "b", "c", "d", nil, "new_5", "new_6"]

If `length` is zero or less, replaces no elements:

    a = ['a', 'b', 'c', 'd']
    a.fill(1, 0) { |index| "new_#{index}" } # => ["a", "b", "c", "d"]
    a.fill(1, -1) { |index| "new_#{index}" } # => ["a", "b", "c", "d"]

With arguments `obj` and `range`, and a block given, calls the block with each index in the given range; replaces the corresponding element with the block’s return value.

If the range is positive and ascending (`range 0 < range.begin <= range.end`, replaces elements from `range.begin` to `range.end`:

    a = ['a', 'b', 'c', 'd']
    a.fill(1..1) { |index| "new_#{index}" } # => ["a", "new_1", "c", "d"]

If `range.first` is negative, does nothing:

    a = ['a', 'b', 'c', 'd']
    a.fill(-1..1) { |index| fail 'Cannot happen' } # => ["a", "b", "c", "d"]

If `range.last` is negative, counts from the end:

    a = ['a', 'b', 'c', 'd']
    a.fill(0..-2) { |index| "new_#{index}" } # => ["new_0", "new_1", "new_2", "d"]
    a = ['a', 'b', 'c', 'd']
    a.fill(1..-2) { |index| "new_#{index}" } # => ["a", "new_1", "new_2", "d"]

If `range.first` and `range.last` are both negative, both count from the end:

    a = ['a', 'b', 'c', 'd']
    a.fill(-1..-1) { |index| "new_#{index}" } # => ["a", "b", "c", "new_3"]
    a = ['a', 'b', 'c', 'd']
    a.fill(-2..-2) { |index| "new_#{index}" } # => ["a", "b", "new_2", "d"]

    static VALUE
    rb_ary_fill(int argc, VALUE *argv, VALUE ary)
    {
        VALUE item = Qundef, arg1, arg2;
        long beg = 0, end = 0, len = 0;

        if (rb_block_given_p()) {
            rb_scan_args(argc, argv, "02", &arg1, &arg2);
            argc += 1;              /* hackish */
        }
        else {
            rb_scan_args(argc, argv, "12", &item, &arg1, &arg2);
        }
        switch (argc) {
          case 1:
            beg = 0;
            len = RARRAY_LEN(ary);
            break;
          case 2:
            if (rb_range_beg_len(arg1, &beg, &len, RARRAY_LEN(ary), 1)) {
                break;
            }
            /* fall through */
          case 3:
            beg = NIL_P(arg1) ? 0 : NUM2LONG(arg1);
            if (beg < 0) {
                beg = RARRAY_LEN(ary) + beg;
                if (beg < 0) beg = 0;
            }
            len = NIL_P(arg2) ? RARRAY_LEN(ary) - beg : NUM2LONG(arg2);
            break;
        }
        rb_ary_modify(ary);
        if (len < 0) {
            return ary;
        }
        if (beg >= ARY_MAX_SIZE || len > ARY_MAX_SIZE - beg) {
            rb_raise(rb_eArgError, "argument too big");
        }
        end = beg + len;
        if (RARRAY_LEN(ary) < end) {
            if (end >= ARY_CAPA(ary)) {
                ary_resize_capa(ary, end);
            }
            ary_mem_clear(ary, RARRAY_LEN(ary), end - RARRAY_LEN(ary));
            ARY_SET_LEN(ary, end);
        }

        if (UNDEF_P(item)) {
            VALUE v;
            long i;

            for (i=beg; i<end; i++) {
                v = rb_yield(LONG2NUM(i));
                if (i>=RARRAY_LEN(ary)) break;
                ARY_SET(ary, i, v);
            }
        }
        else {
            ary_memfill(ary, beg, len, item);
        }
        return ary;
    }

filter
Alias for: select
filter!
Alias for: select!
find_index
Also aliased as: index
first → object or nil click to toggle source
first(n) → new_array

Returns elements from `self`; does not modify `self`.

When no argument is given, returns the first element:

    a = [:foo, 'bar', 2]
    a.first # => :foo
    a # => [:foo, "bar", 2]

If `self` is empty, returns `nil`.

When non-negative `Integer` argument `n` is given, returns the first `n` elements in a new Array:

    a = [:foo, 'bar', 2]
    a.first(2) # => [:foo, "bar"]

If `n >= array.size`, returns all elements:

    a = [:foo, 'bar', 2]
    a.first(50) # => [:foo, "bar", 2]

If `n == 0` returns an new empty Array:

    a = [:foo, 'bar', 2]
    a.first(0) # []

Related: `last`.

    # File array.rb, line 101
    def first n = unspecified = true
      if Primitive.mandatory_only?
        Primitive.attr! :leaf
        Primitive.cexpr! %q{ ary_first(self) }
      else
        if unspecified
          Primitive.cexpr! %q{ ary_first(self) }
        else
          Primitive.cexpr! %q{  ary_take_first_or_last_n(self, NUM2LONG(n), ARY_TAKE_FIRST) }
        end
      end
    end

flatten → new_array click to toggle source
flatten(level) → new_array

Returns a new Array that is a recursive flattening of `self`:

- Each non-Array element is unchanged.

- Each Array is replaced by its individual elements.

With non-negative `Integer` argument `level`, flattens recursively through `level` levels:

    a = [ 0, [ 1, [2, 3], 4 ], 5 ]
    a.flatten(0) # => [0, [1, [2, 3], 4], 5]
    a = [ 0, [ 1, [2, 3], 4 ], 5 ]
    a.flatten(1) # => [0, 1, [2, 3], 4, 5]
    a = [ 0, [ 1, [2, 3], 4 ], 5 ]
    a.flatten(2) # => [0, 1, 2, 3, 4, 5]
    a = [ 0, [ 1, [2, 3], 4 ], 5 ]
    a.flatten(3) # => [0, 1, 2, 3, 4, 5]

With no argument, a `nil` argument, or with negative argument `level`, flattens all levels:

    a = [ 0, [ 1, [2, 3], 4 ], 5 ]
    a.flatten # => [0, 1, 2, 3, 4, 5]
    [0, 1, 2].flatten # => [0, 1, 2]
    a = [ 0, [ 1, [2, 3], 4 ], 5 ]
    a.flatten(-1) # => [0, 1, 2, 3, 4, 5]
    a = [ 0, [ 1, [2, 3], 4 ], 5 ]
    a.flatten(-2) # => [0, 1, 2, 3, 4, 5]
    [0, 1, 2].flatten(-1) # => [0, 1, 2]

    static VALUE
    rb_ary_flatten(int argc, VALUE *argv, VALUE ary)
    {
        int level = -1;
        VALUE result;

        if (rb_check_arity(argc, 0, 1) && !NIL_P(argv[0])) {
            level = NUM2INT(argv[0]);
            if (level == 0) return ary_make_shared_copy(ary);
        }

        result = flatten(ary, level);
        if (result == ary) {
            result = ary_make_shared_copy(ary);
        }

        return result;
    }

flatten! → self or nil click to toggle source
flatten!(level) → self or nil

Replaces each nested Array in `self` with the elements from that Array; returns `self` if any changes, `nil` otherwise.

With non-negative `Integer` argument `level`, flattens recursively through `level` levels:

    a = [ 0, [ 1, [2, 3], 4 ], 5 ]
    a.flatten!(1) # => [0, 1, [2, 3], 4, 5]
    a = [ 0, [ 1, [2, 3], 4 ], 5 ]
    a.flatten!(2) # => [0, 1, 2, 3, 4, 5]
    a = [ 0, [ 1, [2, 3], 4 ], 5 ]
    a.flatten!(3) # => [0, 1, 2, 3, 4, 5]
    [0, 1, 2].flatten!(1) # => nil

With no argument, a `nil` argument, or with negative argument `level`, flattens all levels:

    a = [ 0, [ 1, [2, 3], 4 ], 5 ]
    a.flatten! # => [0, 1, 2, 3, 4, 5]
    [0, 1, 2].flatten! # => nil
    a = [ 0, [ 1, [2, 3], 4 ], 5 ]
    a.flatten!(-1) # => [0, 1, 2, 3, 4, 5]
    a = [ 0, [ 1, [2, 3], 4 ], 5 ]
    a.flatten!(-2) # => [0, 1, 2, 3, 4, 5]
    [0, 1, 2].flatten!(-1) # => nil

    static VALUE
    rb_ary_flatten_bang(int argc, VALUE *argv, VALUE ary)
    {
        int mod = 0, level = -1;
        VALUE result, lv;

        lv = (rb_check_arity(argc, 0, 1) ? argv[0] : Qnil);
        rb_ary_modify_check(ary);
        if (!NIL_P(lv)) level = NUM2INT(lv);
        if (level == 0) return Qnil;

        result = flatten(ary, level);
        if (result == ary) {
            return Qnil;
        }
        if (!(mod = ARY_EMBED_P(result))) rb_obj_freeze(result);
        rb_ary_replace(ary, result);
        if (mod) ARY_SET_EMBED_LEN(result, 0);

        return ary;
    }

hash → integer click to toggle source

Returns the integer hash value for `self`.

Two arrays with the same content will have the same hash code (and will compare using eql?):

    [0, 1, 2].hash == [0, 1, 2].hash # => true
    [0, 1, 2].hash == [0, 1, 3].hash # => false

    static VALUE
    rb_ary_hash(VALUE ary)
    {
        return rb_ary_hash_values(RARRAY_LEN(ary), RARRAY_CONST_PTR(ary));
    }

include?(obj) → true or false click to toggle source

Returns `true` if for some index `i` in `self`, `obj == self[i]`; otherwise `false`:

    [0, 1, 2].include?(2) # => true
    [0, 1, 2].include?(3) # => false

    VALUE
    rb_ary_includes(VALUE ary, VALUE item)
    {
        long i;
        VALUE e;

        for (i=0; i<RARRAY_LEN(ary); i++) {
            e = RARRAY_AREF(ary, i);
            if (rb_equal(e, item)) {
                return Qtrue;
            }
        }
        return Qfalse;
    }

index(object) → integer or nil
index {|element| ... } → integer or nil
index → new_enumerator

Returns the index of a specified element.

When argument `object` is given but no block, returns the index of the first element `element` for which `object == element`:

    a = [:foo, 'bar', 2, 'bar']
    a.index('bar') # => 1

Returns `nil` if no such element found.

When both argument `object` and a block are given, calls the block with each successive element; returns the index of the first element for which the block returns a truthy value:

    a = [:foo, 'bar', 2, 'bar']
    a.index {|element| element == 'bar' } # => 1

Returns `nil` if the block never returns a truthy value.

When neither an argument nor a block is given, returns a new Enumerator:

    a = [:foo, 'bar', 2]
    e = a.index
    e # => #<Enumerator: [:foo, "bar", 2]:index>
    e.each {|element| element == 'bar' } # => 1

Related: `rindex`.

Alias for: find_index
initialize_copy
Also aliased as: replace
insert(index, *objects) → self click to toggle source

Inserts given `objects` before or after the element at `Integer` index `offset`; returns `self`.

When `index` is non-negative, inserts all given `objects` before the element at offset `index`:

    a = [:foo, 'bar', 2]
    a.insert(1, :bat, :bam) # => [:foo, :bat, :bam, "bar", 2]

Extends the array if `index` is beyond the array (`index >= self.size`):

    a = [:foo, 'bar', 2]
    a.insert(5, :bat, :bam)
    a # => [:foo, "bar", 2, nil, nil, :bat, :bam]

Does nothing if no objects given:

    a = [:foo, 'bar', 2]
    a.insert(1)
    a.insert(50)
    a.insert(-50)
    a # => [:foo, "bar", 2]

When `index` is negative, inserts all given `objects` after the element at offset `index+self.size`:

    a = [:foo, 'bar', 2]
    a.insert(-2, :bat, :bam)
    a # => [:foo, "bar", :bat, :bam, 2]

    static VALUE
    rb_ary_insert(int argc, VALUE *argv, VALUE ary)
    {
        long pos;

        rb_check_arity(argc, 1, UNLIMITED_ARGUMENTS);
        rb_ary_modify_check(ary);
        pos = NUM2LONG(argv[0]);
        if (argc == 1) return ary;
        if (pos == -1) {
            pos = RARRAY_LEN(ary);
        }
        else if (pos < 0) {
            long minpos = -RARRAY_LEN(ary) - 1;
            if (pos < minpos) {
                rb_raise(rb_eIndexError, "index %ld too small for array; minimum: %ld",
                         pos, minpos);
            }
            pos++;
        }
        rb_ary_splice(ary, pos, 0, argv + 1, argc - 1);
        return ary;
    }

inspect → new_string click to toggle source

Returns the new `String` formed by calling method `#inspect` on each array element:

    a = [:foo, 'bar', 2]
    a.inspect # => "[:foo, \"bar\", 2]"

    static VALUE
    rb_ary_inspect(VALUE ary)
    {
        if (RARRAY_LEN(ary) == 0) return rb_usascii_str_new2("[]");
        return rb_exec_recursive(inspect_ary, ary, 0);
    }

Also aliased as: to_s
intersect?(other_ary) → true or false click to toggle source

Returns `true` if the array and `other_ary` have at least one element in common, otherwise returns `false`:

    a = [ 1, 2, 3 ]
    b = [ 3, 4, 5 ]
    c = [ 5, 6, 7 ]
    a.intersect?(b)   #=> true
    a.intersect?(c)   #=> false

`Array` elements are compared using `eql?` (items must also implement `hash` correctly).

    static VALUE
    rb_ary_intersect_p(VALUE ary1, VALUE ary2)
    {
        VALUE hash, v, result, shorter, longer;
        st_data_t vv;
        long i;

        ary2 = to_ary(ary2);
        if (RARRAY_LEN(ary1) == 0 || RARRAY_LEN(ary2) == 0) return Qfalse;

        if (RARRAY_LEN(ary1) <= SMALL_ARRAY_LEN && RARRAY_LEN(ary2) <= SMALL_ARRAY_LEN) {
            for (i=0; i<RARRAY_LEN(ary1); i++) {
                v = RARRAY_AREF(ary1, i);
                if (rb_ary_includes_by_eql(ary2, v)) return Qtrue;
            }
            return Qfalse;
        }

        shorter = ary1;
        longer = ary2;
        if (RARRAY_LEN(ary1) > RARRAY_LEN(ary2)) {
            longer = ary1;
            shorter = ary2;
        }

        hash = ary_make_hash(shorter);
        result = Qfalse;

        for (i=0; i<RARRAY_LEN(longer); i++) {
            v = RARRAY_AREF(longer, i);
            vv = (st_data_t)v;
            if (rb_hash_stlike_lookup(hash, vv, 0)) {
                result = Qtrue;
                break;
            }
        }

        return result;
    }

intersection(*other_arrays) → new_array click to toggle source

Returns a new Array containing each element found both in `self` and in all of the given Arrays `other_arrays`; duplicates are omitted; items are compared using `eql?` (items must also implement `hash` correctly):

    [0, 1, 2, 3].intersection([0, 1, 2], [0, 1, 3]) # => [0, 1]
    [0, 0, 1, 1, 2, 3].intersection([0, 1, 2], [0, 1, 3]) # => [0, 1]

Preserves order from `self`:

    [0, 1, 2].intersection([2, 1, 0]) # => [0, 1, 2]

Returns a copy of `self` if no arguments given.

Related: `Array#&`.

    static VALUE
    rb_ary_intersection_multi(int argc, VALUE *argv, VALUE ary)
    {
        VALUE result = rb_ary_dup(ary);
        int i;

        for (i = 0; i < argc; i++) {
            result = rb_ary_and(result, argv[i]);
        }

        return result;
    }

join →new_string click to toggle source
join(separator = $,) → new_string

Returns the new `String` formed by joining the array elements after conversion. For each element `element`:

- Uses `element.to_s` if `element` is not a `kind_of?(Array)`.

- Uses recursive `element.join(separator)` if `element` is a `kind_of?(Array)`.

With no argument, joins using the output field separator, `$,`:

    a = [:foo, 'bar', 2]
    $, # => nil
    a.join # => "foobar2"

With string argument `separator`, joins using that separator:

    a = [:foo, 'bar', 2]
    a.join("\n") # => "foo\nbar\n2"

Joins recursively for nested Arrays:

    a = [:foo, [:bar, [:baz, :bat]]]
    a.join # => "foobarbazbat"

    static VALUE
    rb_ary_join_m(int argc, VALUE *argv, VALUE ary)
    {
        VALUE sep;

        if (rb_check_arity(argc, 0, 1) == 0 || NIL_P(sep = argv[0])) {
            sep = rb_output_fs;
            if (!NIL_P(sep)) {
                rb_category_warn(RB_WARN_CATEGORY_DEPRECATED, "$, is set to non-nil value");
            }
        }

        return rb_ary_join(ary, sep);
    }

keep_if {|element| ... } → self click to toggle source
keep_if → new_enumeration

Retains those elements for which the block returns a truthy value; deletes all other elements; returns `self`:

    a = [:foo, 'bar', 2, :bam]
    a.keep_if {|element| element.to_s.start_with?('b') } # => ["bar", :bam]

Returns a new `Enumerator` if no block given:

    a = [:foo, 'bar', 2, :bam]
    a.keep_if # => #<Enumerator: [:foo, "bar", 2, :bam]:keep_if>

    static VALUE
    rb_ary_keep_if(VALUE ary)
    {
        RETURN_SIZED_ENUMERATOR(ary, 0, 0, ary_enum_length);
        rb_ary_select_bang(ary);
        return ary;
    }

last → object or nil click to toggle source
last(n) → new_array

Returns elements from `self`; `self` is not modified.

When no argument is given, returns the last element:

    a = [:foo, 'bar', 2]
    a.last # => 2
    a # => [:foo, "bar", 2]

If `self` is empty, returns `nil`.

When non-negative `Integer` argument `n` is given, returns the last `n` elements in a new Array:

    a = [:foo, 'bar', 2]
    a.last(2) # => ["bar", 2]

If `n >= array.size`, returns all elements:

    a = [:foo, 'bar', 2]
    a.last(50) # => [:foo, "bar", 2]

If `n == 0`, returns an new empty Array:

    a = [:foo, 'bar', 2]
    a.last(0) # []

Related: `first`.

    # File array.rb, line 145
    def last n = unspecified = true
      if Primitive.mandatory_only?
        Primitive.attr! :leaf
        Primitive.cexpr! %q{ ary_last(self) }
      else
        if unspecified
          Primitive.cexpr! %q{ ary_last(self) }
        else
          Primitive.cexpr! %q{ ary_take_first_or_last_n(self, NUM2LONG(n), ARY_TAKE_LAST) }
        end
      end
    end

length → an_integer click to toggle source

Returns the count of elements in `self`.

    static VALUE
    rb_ary_length(VALUE ary)
    {
        long len = RARRAY_LEN(ary);
        return LONG2NUM(len);
    }

Also aliased as: size
map {|element| ... } → new_array
map → new_enumerator

Calls the block, if given, with each element of `self`; returns a new Array whose elements are the return values from the block:

    a = [:foo, 'bar', 2]
    a1 = a.map {|element| element.class }
    a1 # => [Symbol, String, Integer]

Returns a new `Enumerator` if no block given:

    a = [:foo, 'bar', 2]
    a1 = a.map
    a1 # => #<Enumerator: [:foo, "bar", 2]:map>

Alias for: collect
map! {|element| ... } → self
map! → new_enumerator

Calls the block, if given, with each element; replaces the element with the block’s return value:

    a = [:foo, 'bar', 2]
    a.map! { |element| element.class } # => [Symbol, String, Integer]

Returns a new `Enumerator` if no block given:

    a = [:foo, 'bar', 2]
    a1 = a.map!
    a1 # => #<Enumerator: [:foo, "bar", 2]:map!>

Alias for: collect!
max → element click to toggle source
max {|a, b| ... } → element
max(n) → new_array
max(n) {|a, b| ... } → new_array

Returns one of the following:

- The maximum-valued element from `self`.

- A new Array of maximum-valued elements selected from `self`.

When no block is given, each element in `self` must respond to method `<=>` with an `Integer`.

With no argument and no block, returns the element in `self` having the maximum value per method `<=>`:

    [0, 1, 2].max # => 2

With an argument `Integer` `n` and no block, returns a new Array with at most `n` elements, in descending order per method `<=>`:

    [0, 1, 2, 3].max(3) # => [3, 2, 1]
    [0, 1, 2, 3].max(6) # => [3, 2, 1, 0]

When a block is given, the block must return an `Integer`.

With a block and no argument, calls the block `self.size-1` times to compare elements; returns the element having the maximum value per the block:

    ['0', '00', '000'].max {|a, b| a.size <=> b.size } # => "000"

With an argument `n` and a block, returns a new Array with at most `n` elements, in descending order per the block:

    ['0', '00', '000'].max(2) {|a, b| a.size <=> b.size } # => ["000", "00"]

    static VALUE
    rb_ary_max(int argc, VALUE *argv, VALUE ary)
    {
        VALUE result = Qundef, v;
        VALUE num;
        long i;

        if (rb_check_arity(argc, 0, 1) && !NIL_P(num = argv[0]))
           return rb_nmin_run(ary, num, 0, 1, 1);

        const long n = RARRAY_LEN(ary);
        if (rb_block_given_p()) {
            for (i = 0; i < RARRAY_LEN(ary); i++) {
               v = RARRAY_AREF(ary, i);
               if (UNDEF_P(result) || rb_cmpint(rb_yield_values(2, v, result), v, result) > 0) {
                   result = v;
               }
            }
        }
        else if (n > 0) {
            result = RARRAY_AREF(ary, 0);
            if (n > 1) {
                if (FIXNUM_P(result) && CMP_OPTIMIZABLE(INTEGER)) {
                    return ary_max_opt_fixnum(ary, 1, result);
                }
                else if (STRING_P(result) && CMP_OPTIMIZABLE(STRING)) {
                    return ary_max_opt_string(ary, 1, result);
                }
                else if (RB_FLOAT_TYPE_P(result) && CMP_OPTIMIZABLE(FLOAT)) {
                    return ary_max_opt_float(ary, 1, result);
                }
                else {
                    return ary_max_generic(ary, 1, result);
                }
            }
        }
        if (UNDEF_P(result)) return Qnil;
        return result;
    }

min → element click to toggle source
min { |a, b| ... } → element
min(n) → new_array
min(n) { |a, b| ... } → new_array

Returns one of the following:

- The minimum-valued element from `self`.

- A new Array of minimum-valued elements selected from `self`.

When no block is given, each element in `self` must respond to method `<=>` with an `Integer`.

With no argument and no block, returns the element in `self` having the minimum value per method `<=>`:

    [0, 1, 2].min # => 0

With `Integer` argument `n` and no block, returns a new Array with at most `n` elements, in ascending order per method `<=>`:

    [0, 1, 2, 3].min(3) # => [0, 1, 2]
    [0, 1, 2, 3].min(6) # => [0, 1, 2, 3]

When a block is given, the block must return an `Integer`.

With a block and no argument, calls the block `self.size-1` times to compare elements; returns the element having the minimum value per the block:

    ['0', '00', '000'].min { |a, b| a.size <=> b.size } # => "0"

With an argument `n` and a block, returns a new Array with at most `n` elements, in ascending order per the block:

    ['0', '00', '000'].min(2) {|a, b| a.size <=> b.size } # => ["0", "00"]

    static VALUE
    rb_ary_min(int argc, VALUE *argv, VALUE ary)
    {
        VALUE result = Qundef, v;
        VALUE num;
        long i;

        if (rb_check_arity(argc, 0, 1) && !NIL_P(num = argv[0]))
           return rb_nmin_run(ary, num, 0, 0, 1);

        const long n = RARRAY_LEN(ary);
        if (rb_block_given_p()) {
            for (i = 0; i < RARRAY_LEN(ary); i++) {
               v = RARRAY_AREF(ary, i);
               if (UNDEF_P(result) || rb_cmpint(rb_yield_values(2, v, result), v, result) < 0) {
                   result = v;
               }
            }
        }
        else if (n > 0) {
            result = RARRAY_AREF(ary, 0);
            if (n > 1) {
                if (FIXNUM_P(result) && CMP_OPTIMIZABLE(INTEGER)) {
                    return ary_min_opt_fixnum(ary, 1, result);
                }
                else if (STRING_P(result) && CMP_OPTIMIZABLE(STRING)) {
                    return ary_min_opt_string(ary, 1, result);
                }
                else if (RB_FLOAT_TYPE_P(result) && CMP_OPTIMIZABLE(FLOAT)) {
                    return ary_min_opt_float(ary, 1, result);
                }
                else {
                    return ary_min_generic(ary, 1, result);
                }
            }
        }
        if (UNDEF_P(result)) return Qnil;
        return result;
    }

minmax → [min_val, max_val] click to toggle source
minmax {|a, b| ... } → [min_val, max_val]

Returns a new 2-element Array containing the minimum and maximum values from `self`, either per method `<=>` or per a given block:.

When no block is given, each element in `self` must respond to method `<=>` with an `Integer`; returns a new 2-element Array containing the minimum and maximum values from `self`, per method `<=>`:

    [0, 1, 2].minmax # => [0, 2]

When a block is given, the block must return an `Integer`; the block is called `self.size-1` times to compare elements; returns a new 2-element Array containing the minimum and maximum values from `self`, per the block:

    ['0', '00', '000'].minmax {|a, b| a.size <=> b.size } # => ["0", "000"]

    static VALUE
    rb_ary_minmax(VALUE ary)
    {
        if (rb_block_given_p()) {
            return rb_call_super(0, NULL);
        }
        return rb_assoc_new(rb_ary_min(0, 0, ary), rb_ary_max(0, 0, ary));
    }

none? → true or false click to toggle source
none? {|element| ... } → true or false
none?(obj) → true or false

Returns `true` if no element of `self` meet a given criterion.

With no block given and no argument, returns `true` if `self` has no truthy elements, `false` otherwise:

    [nil, false].none? # => true
    [nil, 0, false].none? # => false
    [].none? # => true

With a block given and no argument, calls the block with each element in `self`; returns `true` if the block returns no truthy value, `false` otherwise:

    [0, 1, 2].none? {|element| element > 3 } # => true
    [0, 1, 2].none? {|element| element > 1 } # => false

If argument `obj` is given, returns `true` if `obj.===` no element, `false` otherwise:

    ['food', 'drink'].none?(/bar/) # => true
    ['food', 'drink'].none?(/foo/) # => false
    [].none?(/foo/) # => true
    [0, 1, 2].none?(3) # => true
    [0, 1, 2].none?(1) # => false

Related: `Enumerable#none?`

    static VALUE
    rb_ary_none_p(int argc, VALUE *argv, VALUE ary)
    {
        long i, len = RARRAY_LEN(ary);

        rb_check_arity(argc, 0, 1);
        if (!len) return Qtrue;
        if (argc) {
            if (rb_block_given_p()) {
                rb_warn("given block not used");
            }
            for (i = 0; i < RARRAY_LEN(ary); ++i) {
                if (RTEST(rb_funcall(argv[0], idEqq, 1, RARRAY_AREF(ary, i)))) return Qfalse;
            }
        }
        else if (!rb_block_given_p()) {
            for (i = 0; i < len; ++i) {
                if (RTEST(RARRAY_AREF(ary, i))) return Qfalse;
            }
        }
        else {
            for (i = 0; i < RARRAY_LEN(ary); ++i) {
                if (RTEST(rb_yield(RARRAY_AREF(ary, i)))) return Qfalse;
            }
        }
        return Qtrue;
    }

one? → true or false click to toggle source
one? {|element| ... } → true or false
one?(obj) → true or false

Returns `true` if exactly one element of `self` meets a given criterion.

With no block given and no argument, returns `true` if `self` has exactly one truthy element, `false` otherwise:

    [nil, 0].one? # => true
    [0, 0].one? # => false
    [nil, nil].one? # => false
    [].one? # => false

With a block given and no argument, calls the block with each element in `self`; returns `true` if the block a truthy value for exactly one element, `false` otherwise:

    [0, 1, 2].one? {|element| element > 0 } # => false
    [0, 1, 2].one? {|element| element > 1 } # => true
    [0, 1, 2].one? {|element| element > 2 } # => false

If argument `obj` is given, returns `true` if `obj.===` exactly one element, `false` otherwise:

    [0, 1, 2].one?(0) # => true
    [0, 0, 1].one?(0) # => false
    [1, 1, 2].one?(0) # => false
    ['food', 'drink'].one?(/bar/) # => false
    ['food', 'drink'].one?(/foo/) # => true
    [].one?(/foo/) # => false

Related: `Enumerable#one?`

    static VALUE
    rb_ary_one_p(int argc, VALUE *argv, VALUE ary)
    {
        long i, len = RARRAY_LEN(ary);
        VALUE result = Qfalse;

        rb_check_arity(argc, 0, 1);
        if (!len) return Qfalse;
        if (argc) {
            if (rb_block_given_p()) {
                rb_warn("given block not used");
            }
            for (i = 0; i < RARRAY_LEN(ary); ++i) {
                if (RTEST(rb_funcall(argv[0], idEqq, 1, RARRAY_AREF(ary, i)))) {
                    if (result) return Qfalse;
                    result = Qtrue;
                }
            }
        }
        else if (!rb_block_given_p()) {
            for (i = 0; i < len; ++i) {
                if (RTEST(RARRAY_AREF(ary, i))) {
                    if (result) return Qfalse;
                    result = Qtrue;
                }
            }
        }
        else {
            for (i = 0; i < RARRAY_LEN(ary); ++i) {
                if (RTEST(rb_yield(RARRAY_AREF(ary, i)))) {
                    if (result) return Qfalse;
                    result = Qtrue;
                }
            }
        }
        return result;
    }

pack(template, buffer: nil) → string click to toggle source

Formats each element in `self` into a binary string; returns that string. See Packed Data.

    # File pack.rb, line 7
    def pack(fmt, buffer: nil)
      Primitive.pack_pack(fmt, buffer)
    end

permutation {|element| ... } → self click to toggle source
permutation(n) {|element| ... } → self
permutation → new_enumerator
permutation(n) → new_enumerator

When invoked with a block, yield all permutations of elements of `self`; returns `self`. The order of permutations is indeterminate.

When a block and an in-range positive `Integer` argument `n` (`0 < n <= self.size`) are given, calls the block with all `n`-tuple permutations of `self`.

Example:

    a = [0, 1, 2]
    a.permutation(2) {|permutation| p permutation }

Output:

    [0, 1]
    [0, 2]
    [1, 0]
    [1, 2]
    [2, 0]
    [2, 1]

Another example:

    a = [0, 1, 2]
    a.permutation(3) {|permutation| p permutation }

Output:

    [0, 1, 2]
    [0, 2, 1]
    [1, 0, 2]
    [1, 2, 0]
    [2, 0, 1]
    [2, 1, 0]

When `n` is zero, calls the block once with a new empty Array:

    a = [0, 1, 2]
    a.permutation(0) {|permutation| p permutation }

Output:

    []

When `n` is out of range (negative or larger than `self.size`), does not call the block:

    a = [0, 1, 2]
    a.permutation(-1) {|permutation| fail 'Cannot happen' }
    a.permutation(4) {|permutation| fail 'Cannot happen' }

When a block given but no argument, behaves the same as `a.permutation(a.size)`:

    a = [0, 1, 2]
    a.permutation {|permutation| p permutation }

Output:

    [0, 1, 2]
    [0, 2, 1]
    [1, 0, 2]
    [1, 2, 0]
    [2, 0, 1]
    [2, 1, 0]

Returns a new `Enumerator` if no block given:

    a = [0, 1, 2]
    a.permutation # => #<Enumerator: [0, 1, 2]:permutation>
    a.permutation(2) # => #<Enumerator: [0, 1, 2]:permutation(2)>

    static VALUE
    rb_ary_permutation(int argc, VALUE *argv, VALUE ary)
    {
        long r, n, i;

        n = RARRAY_LEN(ary);                  /* Array length */
        RETURN_SIZED_ENUMERATOR(ary, argc, argv, rb_ary_permutation_size);   /* Return enumerator if no block */
        r = n;
        if (rb_check_arity(argc, 0, 1) && !NIL_P(argv[0]))
            r = NUM2LONG(argv[0]);            /* Permutation size from argument */

        if (r < 0 || n < r) {
            /* no permutations: yield nothing */
        }
        else if (r == 0) { /* exactly one permutation: the zero-length array */
            rb_yield(rb_ary_new2(0));
        }
        else if (r == 1) { /* this is a special, easy case */
            for (i = 0; i < RARRAY_LEN(ary); i++) {
                rb_yield(rb_ary_new3(1, RARRAY_AREF(ary, i)));
            }
        }
        else {             /* this is the general case */
            volatile VALUE t0;
            long *p = ALLOCV_N(long, t0, r+roomof(n, sizeof(long)));
            char *used = (char*)(p + r);
            VALUE ary0 = ary_make_shared_copy(ary); /* private defensive copy of ary */
            RBASIC_CLEAR_CLASS(ary0);

            MEMZERO(used, char, n); /* initialize array */

            permute0(n, r, p, used, ary0); /* compute and yield permutations */
            ALLOCV_END(t0);
            RBASIC_SET_CLASS_RAW(ary0, rb_cArray);
        }
        return ary;
    }

pop → object or nil click to toggle source
pop(n) → new_array

Removes and returns trailing elements.

When no argument is given and `self` is not empty, removes and returns the last element:

    a = [:foo, 'bar', 2]
    a.pop # => 2
    a # => [:foo, "bar"]

Returns `nil` if the array is empty.

When a non-negative `Integer` argument `n` is given and is in range,

removes and returns the last `n` elements in a new Array:

    a = [:foo, 'bar', 2]
    a.pop(2) # => ["bar", 2]

If `n` is positive and out of range, removes and returns all elements:

    a = [:foo, 'bar', 2]
    a.pop(50) # => [:foo, "bar", 2]

Related: `push`, `shift`, `unshift`.

    static VALUE
    rb_ary_pop_m(int argc, VALUE *argv, VALUE ary)
    {
        VALUE result;

        if (argc == 0) {
            return rb_ary_pop(ary);
        }

        rb_ary_modify_check(ary);
        result = ary_take_first_or_last(argc, argv, ary, ARY_TAKE_LAST);
        ARY_INCREASE_LEN(ary, -RARRAY_LEN(result));
        ary_verify(ary);
        return result;
    }

prepend
Alias for: unshift
product(*other_arrays) → new_array click to toggle source
product(*other_arrays) {|combination| ... } → self

Computes and returns or yields all combinations of elements from all the Arrays, including both `self` and `other_arrays`:

- The number of combinations is the product of the sizes of all the arrays, including both `self` and `other_arrays`.

- The order of the returned combinations is indeterminate.

When no block is given, returns the combinations as an Array of Arrays:

    a = [0, 1, 2]
    a1 = [3, 4]
    a2 = [5, 6]
    p = a.product(a1)
    p.size # => 6 # a.size * a1.size
    p # => [[0, 3], [0, 4], [1, 3], [1, 4], [2, 3], [2, 4]]
    p = a.product(a1, a2)
    p.size # => 12 # a.size * a1.size * a2.size
    p # => [[0, 3, 5], [0, 3, 6], [0, 4, 5], [0, 4, 6], [1, 3, 5], [1, 3, 6], [1, 4, 5], [1, 4, 6], [2, 3, 5], [2, 3, 6], [2, 4, 5], [2, 4, 6]]

If any argument is an empty Array, returns an empty Array.

If no argument is given, returns an Array of 1-element Arrays, each containing an element of `self`:

    a.product # => [[0], [1], [2]]

When a block is given, yields each combination as an Array; returns `self`:

    a.product(a1) {|combination| p combination }

Output:

    [0, 3]
    [0, 4]
    [1, 3]
    [1, 4]
    [2, 3]
    [2, 4]

If any argument is an empty Array, does not call the block:

    a.product(a1, a2, []) {|combination| fail 'Cannot happen' }

If no argument is given, yields each element of `self` as a 1-element Array:

    a.product {|combination| p combination }

Output:

    [0]
    [1]
    [2]

    static VALUE
    rb_ary_product(int argc, VALUE *argv, VALUE ary)
    {
        int n = argc+1;    /* How many arrays we're operating on */
        volatile VALUE t0 = rb_ary_hidden_new(n);
        volatile VALUE t1 = Qundef;
        VALUE *arrays = RARRAY_PTR(t0); /* The arrays we're computing the product of */
        int *counters = ALLOCV_N(int, t1, n); /* The current position in each one */
        VALUE result = Qnil;      /* The array we'll be returning, when no block given */
        long i,j;
        long resultlen = 1;

        RBASIC_CLEAR_CLASS(t0);

        /* initialize the arrays of arrays */
        ARY_SET_LEN(t0, n);
        arrays[0] = ary;
        for (i = 1; i < n; i++) arrays[i] = Qnil;
        for (i = 1; i < n; i++) arrays[i] = to_ary(argv[i-1]);

        /* initialize the counters for the arrays */
        for (i = 0; i < n; i++) counters[i] = 0;

        /* Otherwise, allocate and fill in an array of results */
        if (rb_block_given_p()) {
            /* Make defensive copies of arrays; exit if any is empty */
            for (i = 0; i < n; i++) {
                if (RARRAY_LEN(arrays[i]) == 0) goto done;
                arrays[i] = ary_make_shared_copy(arrays[i]);
            }
        }
        else {
            /* Compute the length of the result array; return [] if any is empty */
            for (i = 0; i < n; i++) {
                long k = RARRAY_LEN(arrays[i]);
                if (k == 0) {
                    result = rb_ary_new2(0);
                    goto done;
                }
                if (MUL_OVERFLOW_LONG_P(resultlen, k))
                    rb_raise(rb_eRangeError, "too big to product");
                resultlen *= k;
            }
            result = rb_ary_new2(resultlen);
        }
        for (;;) {
            int m;
            /* fill in one subarray */
            VALUE subarray = rb_ary_new2(n);
            for (j = 0; j < n; j++) {
                rb_ary_push(subarray, rb_ary_entry(arrays[j], counters[j]));
            }

            /* put it on the result array */
            if (NIL_P(result)) {
                FL_SET(t0, RARRAY_SHARED_ROOT_FLAG);
                rb_yield(subarray);
                if (!FL_TEST(t0, RARRAY_SHARED_ROOT_FLAG)) {
                    rb_raise(rb_eRuntimeError, "product reentered");
                }
                else {
                    FL_UNSET(t0, RARRAY_SHARED_ROOT_FLAG);
                }
            }
            else {
                rb_ary_push(result, subarray);
            }

            /*
             * Increment the last counter.  If it overflows, reset to 0
             * and increment the one before it.
             */
            m = n-1;
            counters[m]++;
            while (counters[m] == RARRAY_LEN(arrays[m])) {
                counters[m] = 0;
                /* If the first counter overflows, we are done */
                if (--m < 0) goto done;
                counters[m]++;
            }
        }

    done:
        ALLOCV_END(t1);

        return NIL_P(result) ? ary : result;
    }

push(*objects) → self click to toggle source

Appends trailing elements.

Appends each argument in `objects` to `self`; returns `self`:

    a = [:foo, 'bar', 2]
    a.push(:baz, :bat) # => [:foo, "bar", 2, :baz, :bat]

Appends each argument as one element, even if it is another Array:

    a = [:foo, 'bar', 2]
    a1 = a.push([:baz, :bat], [:bam, :bad])
    a1 # => [:foo, "bar", 2, [:baz, :bat], [:bam, :bad]]

Related: `pop`, `shift`, `unshift`.

    static VALUE
    rb_ary_push_m(int argc, VALUE *argv, VALUE ary)
    {
        return rb_ary_cat(ary, argv, argc);
    }

Also aliased as: append
rassoc(obj) → found_array or nil click to toggle source

Returns the first element in `self` that is an Array whose second element `==` `obj`:

    a = [{foo: 0}, [2, 4], [4, 5, 6], [4, 5]]
    a.rassoc(4) # => [2, 4]

Returns `nil` if no such element is found.

Related: `assoc`.

    VALUE
    rb_ary_rassoc(VALUE ary, VALUE value)
    {
        long i;
        VALUE v;

        for (i = 0; i < RARRAY_LEN(ary); ++i) {
            v = rb_check_array_type(RARRAY_AREF(ary, i));
            if (RB_TYPE_P(v, T_ARRAY) &&
                RARRAY_LEN(v) > 1 &&
                rb_equal(RARRAY_AREF(v, 1), value))
                return v;
        }
        return Qnil;
    }

reject {|element| ... } → new_array click to toggle source
reject → new_enumerator

Returns a new Array whose elements are all those from `self` for which the block returns `false` or `nil`:

    a = [:foo, 'bar', 2, 'bat']
    a1 = a.reject {|element| element.to_s.start_with?('b') }
    a1 # => [:foo, 2]

Returns a new `Enumerator` if no block given:

    a = [:foo, 'bar', 2]
    a.reject # => #<Enumerator: [:foo, "bar", 2]:reject>

    static VALUE
    rb_ary_reject(VALUE ary)
    {
        VALUE rejected_ary;

        RETURN_SIZED_ENUMERATOR(ary, 0, 0, ary_enum_length);
        rejected_ary = rb_ary_new();
        ary_reject(ary, rejected_ary);
        return rejected_ary;
    }

reject! {|element| ... } → self or nil click to toggle source
reject! → new_enumerator

Removes each element for which the block returns a truthy value.

Returns `self` if any elements removed:

    a = [:foo, 'bar', 2, 'bat']
    a.reject! {|element| element.to_s.start_with?('b') } # => [:foo, 2]

Returns `nil` if no elements removed.

Returns a new `Enumerator` if no block given:

    a = [:foo, 'bar', 2]
    a.reject! # => #<Enumerator: [:foo, "bar", 2]:reject!>

    static VALUE
    rb_ary_reject_bang(VALUE ary)
    {
        RETURN_SIZED_ENUMERATOR(ary, 0, 0, ary_enum_length);
        rb_ary_modify(ary);
        return ary_reject_bang(ary);
    }

repeated_combination(n) {|combination| ... } → self click to toggle source
repeated_combination(n) → new_enumerator

Calls the block with each repeated combination of length `n` of the elements of `self`; each combination is an Array; returns `self`. The order of the combinations is indeterminate.

When a block and a positive `Integer` argument `n` are given, calls the block with each `n`-tuple repeated combination of the elements of `self`. The number of combinations is `(n+1)(n+2)/2`.

`n` = 1:

    a = [0, 1, 2]
    a.repeated_combination(1) {|combination| p combination }

Output:

    [0]
    [1]
    [2]

`n` = 2:

    a.repeated_combination(2) {|combination| p combination }

Output:

    [0, 0]
    [0, 1]
    [0, 2]
    [1, 1]
    [1, 2]
    [2, 2]

If `n` is zero, calls the block once with an empty Array.

If `n` is negative, does not call the block:

    a.repeated_combination(-1) {|combination| fail 'Cannot happen' }

Returns a new `Enumerator` if no block given:

    a = [0, 1, 2]
    a.repeated_combination(2) # => #<Enumerator: [0, 1, 2]:combination(2)>

Using Enumerators, it’s convenient to show the combinations and counts for some values of `n`:

    e = a.repeated_combination(0)
    e.size # => 1
    e.to_a # => [[]]
    e = a.repeated_combination(1)
    e.size # => 3
    e.to_a # => [[0], [1], [2]]
    e = a.repeated_combination(2)
    e.size # => 6
    e.to_a # => [[0, 0], [0, 1], [0, 2], [1, 1], [1, 2], [2, 2]]

    static VALUE
    rb_ary_repeated_combination(VALUE ary, VALUE num)
    {
        long n, i, len;

        n = NUM2LONG(num);                 /* Combination size from argument */
        RETURN_SIZED_ENUMERATOR(ary, 1, &num, rb_ary_repeated_combination_size);   /* Return enumerator if no block */
        len = RARRAY_LEN(ary);
        if (n < 0) {
            /* yield nothing */
        }
        else if (n == 0) {
            rb_yield(rb_ary_new2(0));
        }
        else if (n == 1) {
            for (i = 0; i < RARRAY_LEN(ary); i++) {
                rb_yield(rb_ary_new3(1, RARRAY_AREF(ary, i)));
            }
        }
        else if (len == 0) {
            /* yield nothing */
        }
        else {
            volatile VALUE t0;
            long *p = ALLOCV_N(long, t0, n);
            VALUE ary0 = ary_make_shared_copy(ary); /* private defensive copy of ary */
            RBASIC_CLEAR_CLASS(ary0);

            rcombinate0(len, n, p, n, ary0); /* compute and yield repeated combinations */
            ALLOCV_END(t0);
            RBASIC_SET_CLASS_RAW(ary0, rb_cArray);
        }
        return ary;
    }

repeated_permutation(n) {|permutation| ... } → self click to toggle source
repeated_permutation(n) → new_enumerator

Calls the block with each repeated permutation of length `n` of the elements of `self`; each permutation is an Array; returns `self`. The order of the permutations is indeterminate.

When a block and a positive `Integer` argument `n` are given, calls the block with each `n`-tuple repeated permutation of the elements of `self`. The number of permutations is `self.size**n`.

`n` = 1:

    a = [0, 1, 2]
    a.repeated_permutation(1) {|permutation| p permutation }

Output:

    [0]
    [1]
    [2]

`n` = 2:

    a.repeated_permutation(2) {|permutation| p permutation }

Output:

    [0, 0]
    [0, 1]
    [0, 2]
    [1, 0]
    [1, 1]
    [1, 2]
    [2, 0]
    [2, 1]
    [2, 2]

If `n` is zero, calls the block once with an empty Array.

If `n` is negative, does not call the block:

    a.repeated_permutation(-1) {|permutation| fail 'Cannot happen' }

Returns a new `Enumerator` if no block given:

    a = [0, 1, 2]
    a.repeated_permutation(2) # => #<Enumerator: [0, 1, 2]:permutation(2)>

Using Enumerators, it’s convenient to show the permutations and counts for some values of `n`:

    e = a.repeated_permutation(0)
    e.size # => 1
    e.to_a # => [[]]
    e = a.repeated_permutation(1)
    e.size # => 3
    e.to_a # => [[0], [1], [2]]
    e = a.repeated_permutation(2)
    e.size # => 9
    e.to_a # => [[0, 0], [0, 1], [0, 2], [1, 0], [1, 1], [1, 2], [2, 0], [2, 1], [2, 2]]

    static VALUE
    rb_ary_repeated_permutation(VALUE ary, VALUE num)
    {
        long r, n, i;

        n = RARRAY_LEN(ary);                  /* Array length */
        RETURN_SIZED_ENUMERATOR(ary, 1, &num, rb_ary_repeated_permutation_size);      /* Return Enumerator if no block */
        r = NUM2LONG(num);                    /* Permutation size from argument */

        if (r < 0) {
            /* no permutations: yield nothing */
        }
        else if (r == 0) { /* exactly one permutation: the zero-length array */
            rb_yield(rb_ary_new2(0));
        }
        else if (r == 1) { /* this is a special, easy case */
            for (i = 0; i < RARRAY_LEN(ary); i++) {
                rb_yield(rb_ary_new3(1, RARRAY_AREF(ary, i)));
            }
        }
        else {             /* this is the general case */
            volatile VALUE t0;
            long *p = ALLOCV_N(long, t0, r);
            VALUE ary0 = ary_make_shared_copy(ary); /* private defensive copy of ary */
            RBASIC_CLEAR_CLASS(ary0);

            rpermute0(n, r, p, ary0); /* compute and yield repeated permutations */
            ALLOCV_END(t0);
            RBASIC_SET_CLASS_RAW(ary0, rb_cArray);
        }
        return ary;
    }

replace(other_array) → self

Replaces the content of `self` with the content of `other_array`; returns `self`:

    a = [:foo, 'bar', 2]
    a.replace(['foo', :bar, 3]) # => ["foo", :bar, 3]

Alias for: initialize_copy
reverse → new_array click to toggle source

Returns a new Array with the elements of `self` in reverse order:

    a = ['foo', 'bar', 'two']
    a1 = a.reverse
    a1 # => ["two", "bar", "foo"]

    static VALUE
    rb_ary_reverse_m(VALUE ary)
    {
        long len = RARRAY_LEN(ary);
        VALUE dup = rb_ary_new2(len);

        if (len > 0) {
            const VALUE *p1 = RARRAY_CONST_PTR(ary);
            VALUE *p2 = (VALUE *)RARRAY_CONST_PTR(dup) + len - 1;
            do *p2-- = *p1++; while (--len > 0);
        }
        ARY_SET_LEN(dup, RARRAY_LEN(ary));
        return dup;
    }

reverse! → self click to toggle source

Reverses `self` in place:

    a = ['foo', 'bar', 'two']
    a.reverse! # => ["two", "bar", "foo"]

    static VALUE
    rb_ary_reverse_bang(VALUE ary)
    {
        return rb_ary_reverse(ary);
    }

reverse_each {|element| ... } → self click to toggle source
reverse_each → Enumerator

Iterates backwards over array elements.

When a block given, passes, in reverse order, each element to the block; returns `self`:

    a = [:foo, 'bar', 2]
    a.reverse_each {|element|  puts "#{element.class} #{element}" }

Output:

    Integer 2
    String bar
    Symbol foo

Allows the array to be modified during iteration:

    a = [:foo, 'bar', 2]
    a.reverse_each {|element| puts element; a.clear if element.to_s.start_with?('b') }

Output:

    2
    bar

When no block given, returns a new Enumerator:

    a = [:foo, 'bar', 2]
    e = a.reverse_each
    e # => #<Enumerator: [:foo, "bar", 2]:reverse_each>
    a1 = e.each {|element|  puts "#{element.class} #{element}" }

Output:

    Integer 2
    String bar
    Symbol foo

Related: `each`, `each_index`.

    static VALUE
    rb_ary_reverse_each(VALUE ary)
    {
        long len;

        RETURN_SIZED_ENUMERATOR(ary, 0, 0, ary_enum_length);
        len = RARRAY_LEN(ary);
        while (len--) {
            long nlen;
            rb_yield(RARRAY_AREF(ary, len));
            nlen = RARRAY_LEN(ary);
            if (nlen < len) {
                len = nlen;
            }
        }
        return ary;
    }

rindex(object) → integer or nil click to toggle source
rindex {|element| ... } → integer or nil
rindex → new_enumerator

Returns the index of the last element for which `object == element`.

When argument `object` is given but no block, returns the index of the last such element found:

    a = [:foo, 'bar', 2, 'bar']
    a.rindex('bar') # => 3

Returns `nil` if no such object found.

When a block is given but no argument, calls the block with each successive element; returns the index of the last element for which the block returns a truthy value:

    a = [:foo, 'bar', 2, 'bar']
    a.rindex {|element| element == 'bar' } # => 3

Returns `nil` if the block never returns a truthy value.

When neither an argument nor a block is given, returns a new Enumerator:

    a = [:foo, 'bar', 2, 'bar']
    e = a.rindex
    e # => #<Enumerator: [:foo, "bar", 2, "bar"]:rindex>
    e.each {|element| element == 'bar' } # => 3

Related: `index`.

    static VALUE
    rb_ary_rindex(int argc, VALUE *argv, VALUE ary)
    {
        VALUE val;
        long i = RARRAY_LEN(ary), len;

        if (argc == 0) {
            RETURN_ENUMERATOR(ary, 0, 0);
            while (i--) {
                if (RTEST(rb_yield(RARRAY_AREF(ary, i))))
                    return LONG2NUM(i);
                if (i > (len = RARRAY_LEN(ary))) {
                    i = len;
                }
            }
            return Qnil;
        }
        rb_check_arity(argc, 0, 1);
        val = argv[0];
        if (rb_block_given_p())
            rb_warn("given block not used");
        while (i--) {
            VALUE e = RARRAY_AREF(ary, i);
            if (rb_equal(e, val)) {
                return LONG2NUM(i);
            }
            if (i > RARRAY_LEN(ary)) {
                break;
            }
        }
        return Qnil;
    }

rotate → new_array click to toggle source
rotate(count) → new_array

Returns a new Array formed from `self` with elements rotated from one end to the other.

When no argument given, returns a new Array that is like `self`, except that the first element has been rotated to the last position:

    a = [:foo, 'bar', 2, 'bar']
    a1 = a.rotate
    a1 # => ["bar", 2, "bar", :foo]

When given a non-negative `Integer` `count`, returns a new Array with `count` elements rotated from the beginning to the end:

    a = [:foo, 'bar', 2]
    a1 = a.rotate(2)
    a1 # => [2, :foo, "bar"]

If `count` is large, uses `count % array.size` as the count:

    a = [:foo, 'bar', 2]
    a1 = a.rotate(20)
    a1 # => [2, :foo, "bar"]

If `count` is zero, returns a copy of `self`, unmodified:

    a = [:foo, 'bar', 2]
    a1 = a.rotate(0)
    a1 # => [:foo, "bar", 2]

When given a negative `Integer` `count`, rotates in the opposite direction, from end to beginning:

    a = [:foo, 'bar', 2]
    a1 = a.rotate(-2)
    a1 # => ["bar", 2, :foo]

If `count` is small (far from zero), uses `count % array.size` as the count:

    a = [:foo, 'bar', 2]
    a1 = a.rotate(-5)
    a1 # => ["bar", 2, :foo]

    static VALUE
    rb_ary_rotate_m(int argc, VALUE *argv, VALUE ary)
    {
        VALUE rotated;
        const VALUE *ptr;
        long len;
        long cnt = (rb_check_arity(argc, 0, 1) ? NUM2LONG(argv[0]) : 1);

        len = RARRAY_LEN(ary);
        rotated = rb_ary_new2(len);
        if (len > 0) {
            cnt = rotate_count(cnt, len);
            ptr = RARRAY_CONST_PTR(ary);
            len -= cnt;
            ary_memcpy(rotated, 0, len, ptr + cnt);
            ary_memcpy(rotated, len, cnt, ptr);
        }
        ARY_SET_LEN(rotated, RARRAY_LEN(ary));
        return rotated;
    }

rotate! → self click to toggle source
rotate!(count) → self

Rotates `self` in place by moving elements from one end to the other; returns `self`.

When no argument given, rotates the first element to the last position:

    a = [:foo, 'bar', 2, 'bar']
    a.rotate! # => ["bar", 2, "bar", :foo]

When given a non-negative `Integer` `count`, rotates `count` elements from the beginning to the end:

    a = [:foo, 'bar', 2]
    a.rotate!(2)
    a # => [2, :foo, "bar"]

If `count` is large, uses `count % array.size` as the count:

    a = [:foo, 'bar', 2]
    a.rotate!(20)
    a # => [2, :foo, "bar"]

If `count` is zero, returns `self` unmodified:

    a = [:foo, 'bar', 2]
    a.rotate!(0)
    a # => [:foo, "bar", 2]

When given a negative `Integer` `count`, rotates in the opposite direction, from end to beginning:

    a = [:foo, 'bar', 2]
    a.rotate!(-2)
    a # => ["bar", 2, :foo]

If `count` is small (far from zero), uses `count % array.size` as the count:

    a = [:foo, 'bar', 2]
    a.rotate!(-5)
    a # => ["bar", 2, :foo]

    static VALUE
    rb_ary_rotate_bang(int argc, VALUE *argv, VALUE ary)
    {
        long n = (rb_check_arity(argc, 0, 1) ? NUM2LONG(argv[0]) : 1);
        rb_ary_rotate(ary, n);
        return ary;
    }

sample(random: Random) → object click to toggle source
sample(n, random: Random) → new_ary

Returns random elements from `self`.

When no arguments are given, returns a random element from `self`:

    a = [1, 2, 3, 4, 5, 6, 7, 8, 9, 10]
    a.sample # => 3
    a.sample # => 8

If `self` is empty, returns `nil`.

When argument `n` is given, returns a new Array containing `n` random elements from `self`:

    a.sample(3) # => [8, 9, 2]
    a.sample(6) # => [9, 6, 10, 3, 1, 4]

Returns no more than `a.size` elements (because no new duplicates are introduced):

    a.sample(a.size * 2) # => [6, 4, 1, 8, 5, 9, 10, 2, 3, 7]

But `self` may contain duplicates:

    a = [1, 1, 1, 2, 2, 3]
    a.sample(a.size * 2) # => [1, 1, 3, 2, 1, 2]

The argument `n` must be a non-negative numeric value. The order of the result array is unrelated to the order of `self`. Returns a new empty Array if `self` is empty.

The optional `random` argument will be used as the random number generator:

    a = [1, 2, 3, 4, 5, 6, 7, 8, 9, 10]
    a.sample(random: Random.new(1))     #=> 6
    a.sample(4, random: Random.new(1))  #=> [6, 10, 9, 2]

    # File array.rb, line 60
    def sample(n = (ary = false), random: Random)
      if Primitive.mandatory_only?
        # Primitive.cexpr! %{ rb_ary_sample(self, rb_cRandom, Qfalse, Qfalse) }
        Primitive.ary_sample0
      else
        # Primitive.cexpr! %{ rb_ary_sample(self, random, n, ary) }
        Primitive.ary_sample(random, n, ary)
      end
    end

select {|element| ... } → new_array click to toggle source
select → new_enumerator

Calls the block, if given, with each element of `self`; returns a new Array containing those elements of `self` for which the block returns a truthy value:

    a = [:foo, 'bar', 2, :bam]
    a1 = a.select {|element| element.to_s.start_with?('b') }
    a1 # => ["bar", :bam]

Returns a new `Enumerator` if no block given:

    a = [:foo, 'bar', 2, :bam]
    a.select # => #<Enumerator: [:foo, "bar", 2, :bam]:select>

    static VALUE
    rb_ary_select(VALUE ary)
    {
        VALUE result;
        long i;

        RETURN_SIZED_ENUMERATOR(ary, 0, 0, ary_enum_length);
        result = rb_ary_new2(RARRAY_LEN(ary));
        for (i = 0; i < RARRAY_LEN(ary); i++) {
            if (RTEST(rb_yield(RARRAY_AREF(ary, i)))) {
                rb_ary_push(result, rb_ary_elt(ary, i));
            }
        }
        return result;
    }

Also aliased as: filter
select! {|element| ... } → self or nil click to toggle source
select! → new_enumerator

Calls the block, if given with each element of `self`; removes from `self` those elements for which the block returns `false` or `nil`.

Returns `self` if any elements were removed:

    a = [:foo, 'bar', 2, :bam]
    a.select! {|element| element.to_s.start_with?('b') } # => ["bar", :bam]

Returns `nil` if no elements were removed.

Returns a new `Enumerator` if no block given:

    a = [:foo, 'bar', 2, :bam]
    a.select! # => #<Enumerator: [:foo, "bar", 2, :bam]:select!>

    static VALUE
    rb_ary_select_bang(VALUE ary)
    {
        struct select_bang_arg args;

        RETURN_SIZED_ENUMERATOR(ary, 0, 0, ary_enum_length);
        rb_ary_modify(ary);

        args.ary = ary;
        args.len[0] = args.len[1] = 0;
        return rb_ensure(select_bang_i, (VALUE)&args, select_bang_ensure, (VALUE)&args);
    }

Also aliased as: filter!
shelljoin → string click to toggle source

Builds a command line string from an argument list `array` joining all elements escaped for the Bourne shell and separated by a space.

See `Shellwords.shelljoin` for details.

    # File lib/shellwords.rb, line 239
    def shelljoin
      Shellwords.join(self)
    end

shift → object or nil click to toggle source
shift(n) → new_array

Removes and returns leading elements.

When no argument is given, removes and returns the first element:

    a = [:foo, 'bar', 2]
    a.shift # => :foo
    a # => ['bar', 2]

Returns `nil` if `self` is empty.

When positive `Integer` argument `n` is given, removes the first `n` elements; returns those elements in a new Array:

    a = [:foo, 'bar', 2]
    a.shift(2) # => [:foo, 'bar']
    a # => [2]

If `n` is as large as or larger than `self.length`, removes all elements; returns those elements in a new Array:

    a = [:foo, 'bar', 2]
    a.shift(3) # => [:foo, 'bar', 2]

If `n` is zero, returns a new empty Array; `self` is unmodified.

Related: `push`, `pop`, `unshift`.

    static VALUE
    rb_ary_shift_m(int argc, VALUE *argv, VALUE ary)
    {
        VALUE result;
        long n;

        if (argc == 0) {
            return rb_ary_shift(ary);
        }

        rb_ary_modify_check(ary);
        result = ary_take_first_or_last(argc, argv, ary, ARY_TAKE_FIRST);
        n = RARRAY_LEN(result);
        rb_ary_behead(ary,n);

        return result;
    }

shuffle(random: Random) → new_ary click to toggle source

Returns a new array with elements of `self` shuffled.

    a = [1, 2, 3] #=> [1, 2, 3]
    a.shuffle     #=> [2, 3, 1]
    a             #=> [1, 2, 3]

The optional `random` argument will be used as the random number generator:

    a.shuffle(random: Random.new(1))  #=> [1, 3, 2]

    # File array.rb, line 26
    def shuffle(random: Random)
      Primitive.rb_ary_shuffle(random)
    end

shuffle!(random: Random) → array click to toggle source

Shuffles the elements of `self` in place.

    a = [1, 2, 3] #=> [1, 2, 3]
    a.shuffle!    #=> [2, 3, 1]
    a             #=> [2, 3, 1]

The optional `random` argument will be used as the random number generator:

    a.shuffle!(random: Random.new(1))  #=> [1, 3, 2]

    # File array.rb, line 12
    def shuffle!(random: Random)
      Primitive.rb_ary_shuffle_bang(random)
    end

size
Alias for: length
slice(index) → object or nil
slice(start, length) → object or nil
slice(range) → object or nil
slice(aseq) → object or nil

Returns elements from `self`; does not modify `self`.

When a single `Integer` argument `index` is given, returns the element at offset `index`:

    a = [:foo, 'bar', 2]
    a[0] # => :foo
    a[2] # => 2
    a # => [:foo, "bar", 2]

If `index` is negative, counts relative to the end of `self`:

    a = [:foo, 'bar', 2]
    a[-1] # => 2
    a[-2] # => "bar"

If `index` is out of range, returns `nil`.

When two `Integer` arguments `start` and `length` are given, returns a new Array of size `length` containing successive elements beginning at offset `start`:

    a = [:foo, 'bar', 2]
    a[0, 2] # => [:foo, "bar"]
    a[1, 2] # => ["bar", 2]

If `start + length` is greater than `self.length`, returns all elements from offset `start` to the end:

    a = [:foo, 'bar', 2]
    a[0, 4] # => [:foo, "bar", 2]
    a[1, 3] # => ["bar", 2]
    a[2, 2] # => [2]

If `start == self.size` and `length >= 0`, returns a new empty Array.

If `length` is negative, returns `nil`.

When a single `Range` argument `range` is given, treats `range.min` as `start` above and `range.size` as `length` above:

    a = [:foo, 'bar', 2]
    a[0..1] # => [:foo, "bar"]
    a[1..2] # => ["bar", 2]

Special case: If `range.start == a.size`, returns a new empty Array.

If `range.end` is negative, calculates the end index from the end:

    a = [:foo, 'bar', 2]
    a[0..-1] # => [:foo, "bar", 2]
    a[0..-2] # => [:foo, "bar"]
    a[0..-3] # => [:foo]

If `range.start` is negative, calculates the start index from the end:

    a = [:foo, 'bar', 2]
    a[-1..2] # => [2]
    a[-2..2] # => ["bar", 2]
    a[-3..2] # => [:foo, "bar", 2]

If `range.start` is larger than the array size, returns `nil`.

    a = [:foo, 'bar', 2]
    a[4..1] # => nil
    a[4..0] # => nil
    a[4..-1] # => nil

When a single `Enumerator::ArithmeticSequence` argument `aseq` is given, returns an Array of elements corresponding to the indexes produced by the sequence.

    a = ['--', 'data1', '--', 'data2', '--', 'data3']
    a[(1..).step(2)] # => ["data1", "data2", "data3"]

Unlike slicing with range, if the start or the end of the arithmetic sequence is larger than array size, throws `RangeError`.

    a = ['--', 'data1', '--', 'data2', '--', 'data3']
    a[(1..11).step(2)]
    # RangeError (((1..11).step(2)) out of range)
    a[(7..).step(2)]
    # RangeError (((7..).step(2)) out of range)

If given a single argument, and its type is not one of the listed, tries to convert it to `Integer`, and raises if it is impossible:

    a = [:foo, 'bar', 2]
    # Raises TypeError (no implicit conversion of Symbol into Integer):
    a[:foo]

Alias for: []
slice!(n) → object or nil click to toggle source
slice!(start, length) → new_array or nil
slice!(range) → new_array or nil

Removes and returns elements from `self`.

When the only argument is an `Integer` `n`, removes and returns the nth element in `self`:

    a = [:foo, 'bar', 2]
    a.slice!(1) # => "bar"
    a # => [:foo, 2]

If `n` is negative, counts backwards from the end of `self`:

    a = [:foo, 'bar', 2]
    a.slice!(-1) # => 2
    a # => [:foo, "bar"]

If `n` is out of range, returns `nil`.

When the only arguments are Integers `start` and `length`, removes `length` elements from `self` beginning at offset `start`; returns the deleted objects in a new Array:

    a = [:foo, 'bar', 2]
    a.slice!(0, 2) # => [:foo, "bar"]
    a # => [2]

If `start + length` exceeds the array size, removes and returns all elements from offset `start` to the end:

    a = [:foo, 'bar', 2]
    a.slice!(1, 50) # => ["bar", 2]
    a # => [:foo]

If `start == a.size` and `length` is non-negative, returns a new empty Array.

If `length` is negative, returns `nil`.

When the only argument is a `Range` object `range`, treats `range.min` as `start` above and `range.size` as `length` above:

    a = [:foo, 'bar', 2]
    a.slice!(1..2) # => ["bar", 2]
    a # => [:foo]

If `range.start == a.size`, returns a new empty Array.

If `range.start` is larger than the array size, returns `nil`.

If `range.end` is negative, counts backwards from the end of the array:

    a = [:foo, 'bar', 2]
    a.slice!(0..-2) # => [:foo, "bar"]
    a # => [2]

If `range.start` is negative, calculates the start index backwards from the end of the array:

    a = [:foo, 'bar', 2]
    a.slice!(-2..2) # => ["bar", 2]
    a # => [:foo]

    static VALUE
    rb_ary_slice_bang(int argc, VALUE *argv, VALUE ary)
    {
        VALUE arg1;
        long pos, len;

        rb_ary_modify_check(ary);
        rb_check_arity(argc, 1, 2);
        arg1 = argv[0];

        if (argc == 2) {
            pos = NUM2LONG(argv[0]);
            len = NUM2LONG(argv[1]);
            return ary_slice_bang_by_rb_ary_splice(ary, pos, len);
        }

        if (!FIXNUM_P(arg1)) {
            switch (rb_range_beg_len(arg1, &pos, &len, RARRAY_LEN(ary), 0)) {
              case Qtrue:
                /* valid range */
                return ary_slice_bang_by_rb_ary_splice(ary, pos, len);
              case Qnil:
                /* invalid range */
                return Qnil;
              default:
                /* not a range */
                break;
            }
        }

        return rb_ary_delete_at(ary, NUM2LONG(arg1));
    }

sort → new_array click to toggle source
sort {|a, b| ... } → new_array

Returns a new Array whose elements are those from `self`, sorted.

With no block, compares elements using operator `<=>` (see `Comparable`):

    a = 'abcde'.split('').shuffle
    a # => ["e", "b", "d", "a", "c"]
    a1 = a.sort
    a1 # => ["a", "b", "c", "d", "e"]

With a block, calls the block with each element pair; for each element pair `a` and `b`, the block should return an integer:

- Negative when `b` is to follow `a`.

- Zero when `a` and `b` are equivalent.

- Positive when `a` is to follow `b`.

Example:

    a = 'abcde'.split('').shuffle
    a # => ["e", "b", "d", "a", "c"]
    a1 = a.sort {|a, b| a <=> b }
    a1 # => ["a", "b", "c", "d", "e"]
    a2 = a.sort {|a, b| b <=> a }
    a2 # => ["e", "d", "c", "b", "a"]

When the block returns zero, the order for `a` and `b` is indeterminate, and may be unstable:

    a = 'abcde'.split('').shuffle
    a # => ["e", "b", "d", "a", "c"]
    a1 = a.sort {|a, b| 0 }
    a1 # =>  ["c", "e", "b", "d", "a"]

Related: `Enumerable#sort_by`.

    VALUE
    rb_ary_sort(VALUE ary)
    {
        ary = rb_ary_dup(ary);
        rb_ary_sort_bang(ary);
        return ary;
    }

sort! → self click to toggle source
sort! {|a, b| ... } → self

Returns `self` with its elements sorted in place.

With no block, compares elements using operator `<=>` (see `Comparable`):

    a = 'abcde'.split('').shuffle
    a # => ["e", "b", "d", "a", "c"]
    a.sort!
    a # => ["a", "b", "c", "d", "e"]

With a block, calls the block with each element pair; for each element pair `a` and `b`, the block should return an integer:

- Negative when `b` is to follow `a`.

- Zero when `a` and `b` are equivalent.

- Positive when `a` is to follow `b`.

Example:

    a = 'abcde'.split('').shuffle
    a # => ["e", "b", "d", "a", "c"]
    a.sort! {|a, b| a <=> b }
    a # => ["a", "b", "c", "d", "e"]
    a.sort! {|a, b| b <=> a }
    a # => ["e", "d", "c", "b", "a"]

When the block returns zero, the order for `a` and `b` is indeterminate, and may be unstable:

    a = 'abcde'.split('').shuffle
    a # => ["e", "b", "d", "a", "c"]
    a.sort! {|a, b| 0 }
    a # => ["d", "e", "c", "a", "b"]

    VALUE
    rb_ary_sort_bang(VALUE ary)
    {
        rb_ary_modify(ary);
        assert(!ARY_SHARED_P(ary));
        if (RARRAY_LEN(ary) > 1) {
            VALUE tmp = ary_make_substitution(ary); /* only ary refers tmp */
            struct ary_sort_data data;
            long len = RARRAY_LEN(ary);
            RBASIC_CLEAR_CLASS(tmp);
            data.ary = tmp;
            data.receiver = ary;
            RARRAY_PTR_USE(tmp, ptr, {
                ruby_qsort(ptr, len, sizeof(VALUE),
                           rb_block_given_p()?sort_1:sort_2, &data);
            }); /* WB: no new reference */
            rb_ary_modify(ary);
            if (ARY_EMBED_P(tmp)) {
                if (ARY_SHARED_P(ary)) { /* ary might be destructively operated in the given block */
                    rb_ary_unshare(ary);
                    FL_SET_EMBED(ary);
                }
                ary_memcpy(ary, 0, ARY_EMBED_LEN(tmp), ARY_EMBED_PTR(tmp));
                ARY_SET_LEN(ary, ARY_EMBED_LEN(tmp));
            }
            else {
                if (!ARY_EMBED_P(ary) && ARY_HEAP_PTR(ary) == ARY_HEAP_PTR(tmp)) {
                    FL_UNSET_SHARED(ary);
                    ARY_SET_CAPA(ary, RARRAY_LEN(tmp));
                }
                else {
                    assert(!ARY_SHARED_P(tmp));
                    if (ARY_EMBED_P(ary)) {
                        FL_UNSET_EMBED(ary);
                    }
                    else if (ARY_SHARED_P(ary)) {
                        /* ary might be destructively operated in the given block */
                        rb_ary_unshare(ary);
                    }
                    else {
                        ary_heap_free(ary);
                    }
                    ARY_SET_PTR(ary, ARY_HEAP_PTR(tmp));
                    ARY_SET_HEAP_LEN(ary, len);
                    ARY_SET_CAPA(ary, ARY_HEAP_LEN(tmp));
                }
                /* tmp was lost ownership for the ptr */
                FL_UNSET(tmp, FL_FREEZE);
                FL_SET_EMBED(tmp);
                ARY_SET_EMBED_LEN(tmp, 0);
                FL_SET(tmp, FL_FREEZE);
            }
            /* tmp will be GC'ed. */
            RBASIC_SET_CLASS_RAW(tmp, rb_cArray); /* rb_cArray must be marked */
        }
        ary_verify(ary);
        return ary;
    }

sort_by! {|element| ... } → self click to toggle source
sort_by! → new_enumerator

Sorts the elements of `self` in place, using an ordering determined by the block; returns self.

Calls the block with each successive element; sorts elements based on the values returned from the block.

For duplicates returned by the block, the ordering is indeterminate, and may be unstable.

This example sorts strings based on their sizes:

    a = ['aaaa', 'bbb', 'cc', 'd']
    a.sort_by! {|element| element.size }
    a # => ["d", "cc", "bbb", "aaaa"]

Returns a new `Enumerator` if no block given:

    a = ['aaaa', 'bbb', 'cc', 'd']
    a.sort_by! # => #<Enumerator: ["aaaa", "bbb", "cc", "d"]:sort_by!>

    static VALUE
    rb_ary_sort_by_bang(VALUE ary)
    {
        VALUE sorted;

        RETURN_SIZED_ENUMERATOR(ary, 0, 0, ary_enum_length);
        rb_ary_modify(ary);
        sorted = rb_block_call(ary, rb_intern("sort_by"), 0, 0, sort_by_i, 0);
        rb_ary_replace(ary, sorted);
        return ary;
    }

sum(init = 0) → object click to toggle source
sum(init = 0) {|element| ... } → object

When no block is given, returns the object equivalent to:

    sum = init
    array.each {|element| sum += element }
    sum

For example, `[e1, e2, e3].sum` returns `init + e1 + e2 + e3`.

Examples:

    a = [0, 1, 2, 3]
    a.sum # => 6
    a.sum(100) # => 106

The elements need not be numeric, but must be `+`-compatible with each other and with `init`:

    a = ['abc', 'def', 'ghi']
    a.sum('jkl') # => "jklabcdefghi"

When a block is given, it is called with each element and the block’s return value (instead of the element itself) is used as the addend:

    a = ['zero', 1, :two]
    s = a.sum('Coerced and concatenated: ') {|element| element.to_s }
    s # => "Coerced and concatenated: zero1two"

Notes:

- `Array#join` and `Array#flatten` may be faster than `Array#sum` for an Array of Strings or an Array of Arrays.

- `Array#sum` method may not respect method redefinition of “+” methods such as `Integer#+`.

    static VALUE
    rb_ary_sum(int argc, VALUE *argv, VALUE ary)
    {
        VALUE e, v, r;
        long i, n;
        int block_given;

        v = (rb_check_arity(argc, 0, 1) ? argv[0] : LONG2FIX(0));

        block_given = rb_block_given_p();

        if (RARRAY_LEN(ary) == 0)
            return v;

        n = 0;
        r = Qundef;

        if (!FIXNUM_P(v) && !RB_BIGNUM_TYPE_P(v) && !RB_TYPE_P(v, T_RATIONAL)) {
            i = 0;
            goto init_is_a_value;
        }

        for (i = 0; i < RARRAY_LEN(ary); i++) {
            e = RARRAY_AREF(ary, i);
            if (block_given)
                e = rb_yield(e);
            if (FIXNUM_P(e)) {
                n += FIX2LONG(e); /* should not overflow long type */
                if (!FIXABLE(n)) {
                    v = rb_big_plus(LONG2NUM(n), v);
                    n = 0;
                }
            }
            else if (RB_BIGNUM_TYPE_P(e))
                v = rb_big_plus(e, v);
            else if (RB_TYPE_P(e, T_RATIONAL)) {
                if (UNDEF_P(r))
                    r = e;
                else
                    r = rb_rational_plus(r, e);
            }
            else
                goto not_exact;
        }
        v = finish_exact_sum(n, r, v, argc!=0);
        return v;

      not_exact:
        v = finish_exact_sum(n, r, v, i!=0);

        if (RB_FLOAT_TYPE_P(e)) {
            /*
             * Kahan-Babuska balancing compensated summation algorithm
             * See https://link.springer.com/article/10.1007/s00607-005-0139-x
             */
            double f, c;
            double x, t;

            f = NUM2DBL(v);
            c = 0.0;
            goto has_float_value;
            for (; i < RARRAY_LEN(ary); i++) {
                e = RARRAY_AREF(ary, i);
                if (block_given)
                    e = rb_yield(e);
                if (RB_FLOAT_TYPE_P(e))
                  has_float_value:
                    x = RFLOAT_VALUE(e);
                else if (FIXNUM_P(e))
                    x = FIX2LONG(e);
                else if (RB_BIGNUM_TYPE_P(e))
                    x = rb_big2dbl(e);
                else if (RB_TYPE_P(e, T_RATIONAL))
                    x = rb_num2dbl(e);
                else
                    goto not_float;

                if (isnan(f)) continue;
                if (isnan(x)) {
                    f = x;
                    continue;
                }
                if (isinf(x)) {
                    if (isinf(f) && signbit(x) != signbit(f))
                        f = NAN;
                    else
                        f = x;
                    continue;
                }
                if (isinf(f)) continue;

                t = f + x;
                if (fabs(f) >= fabs(x))
                    c += ((f - t) + x);
                else
                    c += ((x - t) + f);
                f = t;
            }
            f += c;
            return DBL2NUM(f);

          not_float:
            v = DBL2NUM(f);
        }

        goto has_some_value;
        init_is_a_value:
        for (; i < RARRAY_LEN(ary); i++) {
            e = RARRAY_AREF(ary, i);
            if (block_given)
                e = rb_yield(e);
          has_some_value:
            v = rb_funcall(v, idPLUS, 1, e);
        }
        return v;
    }

take(n) → new_array click to toggle source

Returns a new Array containing the first `n` element of `self`, where `n` is a non-negative `Integer`; does not modify `self`.

Examples:

    a = [0, 1, 2, 3, 4, 5]
    a.take(1) # => [0]
    a.take(2) # => [0, 1]
    a.take(50) # => [0, 1, 2, 3, 4, 5]
    a # => [0, 1, 2, 3, 4, 5]

    static VALUE
    rb_ary_take(VALUE obj, VALUE n)
    {
        long len = NUM2LONG(n);
        if (len < 0) {
            rb_raise(rb_eArgError, "attempt to take negative size");
        }
        return rb_ary_subseq(obj, 0, len);
    }

take_while {|element| ... } → new_array click to toggle source
take_while → new_enumerator

Returns a new Array containing zero or more leading elements of `self`; does not modify `self`.

With a block given, calls the block with each successive element of `self`; stops if the block returns `false` or `nil`; returns a new Array containing those elements for which the block returned a truthy value:

    a = [0, 1, 2, 3, 4, 5]
    a.take_while {|element| element < 3 } # => [0, 1, 2]
    a.take_while {|element| true } # => [0, 1, 2, 3, 4, 5]
    a # => [0, 1, 2, 3, 4, 5]

With no block given, returns a new Enumerator:

    [0, 1].take_while # => #<Enumerator: [0, 1]:take_while>

    static VALUE
    rb_ary_take_while(VALUE ary)
    {
        long i;

        RETURN_ENUMERATOR(ary, 0, 0);
        for (i = 0; i < RARRAY_LEN(ary); i++) {
            if (!RTEST(rb_yield(RARRAY_AREF(ary, i)))) break;
        }
        return rb_ary_take(ary, LONG2FIX(i));
    }

to_a → self or new_array click to toggle source

When `self` is an instance of Array, returns `self`:

    a = [:foo, 'bar', 2]
    a.to_a # => [:foo, "bar", 2]

Otherwise, returns a new Array containing the elements of `self`:

    class MyArray < Array; end
    a = MyArray.new(['foo', 'bar', 'two'])
    a.instance_of?(Array) # => false
    a.kind_of?(Array) # => true
    a1 = a.to_a
    a1 # => ["foo", "bar", "two"]
    a1.class # => Array # Not MyArray

    static VALUE
    rb_ary_to_a(VALUE ary)
    {
        if (rb_obj_class(ary) != rb_cArray) {
            VALUE dup = rb_ary_new2(RARRAY_LEN(ary));
            rb_ary_replace(dup, ary);
            return dup;
        }
        return ary;
    }

to_ary → self click to toggle source

Returns `self`.

    static VALUE
    rb_ary_to_ary_m(VALUE ary)
    {
        return ary;
    }

to_h → new_hash click to toggle source
to_h {|item| ... } → new_hash

Returns a new `Hash` formed from `self`.

When a block is given, calls the block with each array element; the block must return a 2-element Array whose two elements form a key-value pair in the returned Hash:

    a = ['foo', :bar, 1, [2, 3], {baz: 4}]
    h = a.to_h {|item| [item, item] }
    h # => {"foo"=>"foo", :bar=>:bar, 1=>1, [2, 3]=>[2, 3], {:baz=>4}=>{:baz=>4}}

When no block is given, `self` must be an Array of 2-element sub-arrays, each sub-array is formed into a key-value pair in the new Hash:

    [].to_h # => {}
    a = [['foo', 'zero'], ['bar', 'one'], ['baz', 'two']]
    h = a.to_h
    h # => {"foo"=>"zero", "bar"=>"one", "baz"=>"two"}

    static VALUE
    rb_ary_to_h(VALUE ary)
    {
        long i;
        VALUE hash = rb_hash_new_with_size(RARRAY_LEN(ary));
        int block_given = rb_block_given_p();

        for (i=0; i<RARRAY_LEN(ary); i++) {
            const VALUE e = rb_ary_elt(ary, i);
            const VALUE elt = block_given ? rb_yield_force_blockarg(e) : e;
            const VALUE key_value_pair = rb_check_array_type(elt);
            if (NIL_P(key_value_pair)) {
                rb_raise(rb_eTypeError, "wrong element type %"PRIsVALUE" at %ld (expected array)",
                         rb_obj_class(elt), i);
            }
            if (RARRAY_LEN(key_value_pair) != 2) {
                rb_raise(rb_eArgError, "wrong array length at %ld (expected 2, was %ld)",
                    i, RARRAY_LEN(key_value_pair));
            }
            rb_hash_aset(hash, RARRAY_AREF(key_value_pair, 0), RARRAY_AREF(key_value_pair, 1));
        }
        return hash;
    }

to_s
Alias for: inspect
transpose → new_array click to toggle source

Transposes the rows and columns in an Array of Arrays; the nested Arrays must all be the same size:

    a = [[:a0, :a1], [:b0, :b1], [:c0, :c1]]
    a.transpose # => [[:a0, :b0, :c0], [:a1, :b1, :c1]]

    static VALUE
    rb_ary_transpose(VALUE ary)
    {
        long elen = -1, alen, i, j;
        VALUE tmp, result = 0;

        alen = RARRAY_LEN(ary);
        if (alen == 0) return rb_ary_dup(ary);
        for (i=0; i<alen; i++) {
            tmp = to_ary(rb_ary_elt(ary, i));
            if (elen < 0) {         /* first element */
                elen = RARRAY_LEN(tmp);
                result = rb_ary_new2(elen);
                for (j=0; j<elen; j++) {
                    rb_ary_store(result, j, rb_ary_new2(alen));
                }
            }
            else if (elen != RARRAY_LEN(tmp)) {
                rb_raise(rb_eIndexError, "element size differs (%ld should be %ld)",
                         RARRAY_LEN(tmp), elen);
            }
            for (j=0; j<elen; j++) {
                rb_ary_store(rb_ary_elt(result, j), i, rb_ary_elt(tmp, j));
            }
        }
        return result;
    }

union(*other_arrays) → new_array click to toggle source

Returns a new Array that is the union of `self` and all given Arrays `other_arrays`; duplicates are removed; order is preserved; items are compared using `eql?`:

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

Returns a copy of `self` if no arguments given.

Related: `Array#|`.

    static VALUE
    rb_ary_union_multi(int argc, VALUE *argv, VALUE ary)
    {
        int i;
        long sum;
        VALUE hash;

        sum = RARRAY_LEN(ary);
        for (i = 0; i < argc; i++) {
            argv[i] = to_ary(argv[i]);
            sum += RARRAY_LEN(argv[i]);
        }

        if (sum <= SMALL_ARRAY_LEN) {
            VALUE ary_union = rb_ary_new();

            rb_ary_union(ary_union, ary);
            for (i = 0; i < argc; i++) rb_ary_union(ary_union, argv[i]);

            return ary_union;
        }

        hash = ary_make_hash(ary);
        for (i = 0; i < argc; i++) rb_ary_union_hash(hash, argv[i]);

        return rb_hash_values(hash);
    }

uniq → new_array click to toggle source
uniq {|element| ... } → new_array

Returns a new Array containing those elements from `self` that are not duplicates, the first occurrence always being retained.

With no block given, identifies and omits duplicates using method `eql?` to compare:

    a = [0, 0, 1, 1, 2, 2]
    a.uniq # => [0, 1, 2]

With a block given, calls the block for each element; identifies (using method `eql?`) and omits duplicate values, that is, those elements for which the block returns the same value:

    a = ['a', 'aa', 'aaa', 'b', 'bb', 'bbb']
    a.uniq {|element| element.size } # => ["a", "aa", "aaa"]

    static VALUE
    rb_ary_uniq(VALUE ary)
    {
        VALUE hash, uniq;

        if (RARRAY_LEN(ary) <= 1) {
            hash = 0;
            uniq = rb_ary_dup(ary);
        }
        else if (rb_block_given_p()) {
            hash = ary_make_hash_by(ary);
            uniq = rb_hash_values(hash);
        }
        else {
            hash = ary_make_hash(ary);
            uniq = rb_hash_values(hash);
        }

        return uniq;
    }

uniq! → self or nil click to toggle source
uniq! {|element| ... } → self or nil

Removes duplicate elements from `self`, the first occurrence always being retained; returns `self` if any elements removed, `nil` otherwise.

With no block given, identifies and removes elements using method `eql?` to compare.

Returns `self` if any elements removed:

    a = [0, 0, 1, 1, 2, 2]
    a.uniq! # => [0, 1, 2]

Returns `nil` if no elements removed.

With a block given, calls the block for each element; identifies (using method `eql?`) and removes elements for which the block returns duplicate values.

Returns `self` if any elements removed:

    a = ['a', 'aa', 'aaa', 'b', 'bb', 'bbb']
    a.uniq! {|element| element.size } # => ['a', 'aa', 'aaa']

Returns `nil` if no elements removed.

    static VALUE
    rb_ary_uniq_bang(VALUE ary)
    {
        VALUE hash;
        long hash_size;

        rb_ary_modify_check(ary);
        if (RARRAY_LEN(ary) <= 1)
            return Qnil;
        if (rb_block_given_p())
            hash = ary_make_hash_by(ary);
        else
            hash = ary_make_hash(ary);

        hash_size = RHASH_SIZE(hash);
        if (RARRAY_LEN(ary) == hash_size) {
            return Qnil;
        }
        rb_ary_modify_check(ary);
        ARY_SET_LEN(ary, 0);
        if (ARY_SHARED_P(ary) && !ARY_EMBED_P(ary)) {
            rb_ary_unshare(ary);
            FL_SET_EMBED(ary);
        }
        ary_resize_capa(ary, hash_size);
        rb_hash_foreach(hash, push_value, ary);

        return ary;
    }

unshift(*objects) → self click to toggle source

Prepends the given `objects` to `self`:

    a = [:foo, 'bar', 2]
    a.unshift(:bam, :bat) # => [:bam, :bat, :foo, "bar", 2]

Related: `push`, `pop`, `shift`.

    VALUE
    rb_ary_unshift_m(int argc, VALUE *argv, VALUE ary)
    {
        long len = RARRAY_LEN(ary);
        VALUE target_ary;

        if (argc == 0) {
            rb_ary_modify_check(ary);
            return ary;
        }

        target_ary = ary_ensure_room_for_unshift(ary, argc);
        ary_memcpy0(ary, 0, argc, argv, target_ary);
        ARY_SET_LEN(ary, len + argc);
        return ary;
    }

Also aliased as: prepend
values_at(*indexes) → new_array click to toggle source

Returns a new Array whose elements are the elements of `self` at the given `Integer` or `Range` `indexes`.

For each positive `index`, returns the element at offset `index`:

    a = [:foo, 'bar', 2]
    a.values_at(0, 2) # => [:foo, 2]
    a.values_at(0..1) # => [:foo, "bar"]

The given `indexes` may be in any order, and may repeat:

    a = [:foo, 'bar', 2]
    a.values_at(2, 0, 1, 0, 2) # => [2, :foo, "bar", :foo, 2]
    a.values_at(1, 0..2) # => ["bar", :foo, "bar", 2]

Assigns `nil` for an `index` that is too large:

    a = [:foo, 'bar', 2]
    a.values_at(0, 3, 1, 3) # => [:foo, nil, "bar", nil]

Returns a new empty Array if no arguments given.

For each negative `index`, counts backward from the end of the array:

    a = [:foo, 'bar', 2]
    a.values_at(-1, -3) # => [2, :foo]

Assigns `nil` for an `index` that is too small:

    a = [:foo, 'bar', 2]
    a.values_at(0, -5, 1, -6, 2) # => [:foo, nil, "bar", nil, 2]

The given `indexes` may have a mixture of signs:

    a = [:foo, 'bar', 2]
    a.values_at(0, -2, 1, -1) # => [:foo, "bar", "bar", 2]

    static VALUE
    rb_ary_values_at(int argc, VALUE *argv, VALUE ary)
    {
        long i, olen = RARRAY_LEN(ary);
        VALUE result = rb_ary_new_capa(argc);
        for (i = 0; i < argc; ++i) {
            append_values_at_single(result, ary, olen, argv[i]);
        }
        RB_GC_GUARD(ary);
        return result;
    }

zip(*other_arrays) → new_array click to toggle source
zip(*other_arrays) {|other_array| ... } → nil

When no block given, returns a new Array `new_array` of size `self.size` whose elements are Arrays.

Each nested array `new_array[n]` is of size `other_arrays.size+1`, and contains:

- The nth element of `self`.

- The nth element of each of the `other_arrays`.

If all `other_arrays` and `self` are the same size:

    a = [:a0, :a1, :a2, :a3]
    b = [:b0, :b1, :b2, :b3]
    c = [:c0, :c1, :c2, :c3]
    d = a.zip(b, c)
    d # => [[:a0, :b0, :c0], [:a1, :b1, :c1], [:a2, :b2, :c2], [:a3, :b3, :c3]]

If any array in `other_arrays` is smaller than `self`, fills to `self.size` with `nil`:

    a = [:a0, :a1, :a2, :a3]
    b = [:b0, :b1, :b2]
    c = [:c0, :c1]
    d = a.zip(b, c)
    d # => [[:a0, :b0, :c0], [:a1, :b1, :c1], [:a2, :b2, nil], [:a3, nil, nil]]

If any array in `other_arrays` is larger than `self`, its trailing elements are ignored:

    a = [:a0, :a1, :a2, :a3]
    b = [:b0, :b1, :b2, :b3, :b4]
    c = [:c0, :c1, :c2, :c3, :c4, :c5]
    d = a.zip(b, c)
    d # => [[:a0, :b0, :c0], [:a1, :b1, :c1], [:a2, :b2, :c2], [:a3, :b3, :c3]]

When a block is given, calls the block with each of the sub-arrays (formed as above); returns `nil`:

    a = [:a0, :a1, :a2, :a3]
    b = [:b0, :b1, :b2, :b3]
    c = [:c0, :c1, :c2, :c3]
    a.zip(b, c) {|sub_array| p sub_array} # => nil

Output:

    [:a0, :b0, :c0]
    [:a1, :b1, :c1]
    [:a2, :b2, :c2]
    [:a3, :b3, :c3]

    static VALUE
    rb_ary_zip(int argc, VALUE *argv, VALUE ary)
    {
        int i, j;
        long len = RARRAY_LEN(ary);
        VALUE result = Qnil;

        for (i=0; i<argc; i++) {
            argv[i] = take_items(argv[i], len);
        }

        if (rb_block_given_p()) {
            int arity = rb_block_arity();

            if (arity > 1) {
                VALUE work, *tmp;

                tmp = ALLOCV_N(VALUE, work, argc+1);

                for (i=0; i<RARRAY_LEN(ary); i++) {
                    tmp[0] = RARRAY_AREF(ary, i);
                    for (j=0; j<argc; j++) {
                        tmp[j+1] = rb_ary_elt(argv[j], i);
                    }
                    rb_yield_values2(argc+1, tmp);
                }

                if (work) ALLOCV_END(work);
            }
            else {
                for (i=0; i<RARRAY_LEN(ary); i++) {
                    VALUE tmp = rb_ary_new2(argc+1);

                    rb_ary_push(tmp, RARRAY_AREF(ary, i));
                    for (j=0; j<argc; j++) {
                        rb_ary_push(tmp, rb_ary_elt(argv[j], i));
                    }
                    rb_yield(tmp);
                }
            }
        }
        else {
            result = rb_ary_new_capa(len);

            for (i=0; i<len; i++) {
                VALUE tmp = rb_ary_new_capa(argc+1);

                rb_ary_push(tmp, RARRAY_AREF(ary, i));
                for (j=0; j<argc; j++) {
                    rb_ary_push(tmp, rb_ary_elt(argv[j], i));
                }
                rb_ary_push(result, tmp);
            }
        }

        return result;
    }

array | other_array → new_array click to toggle source

Returns the union of `array` and Array `other_array`; duplicates are removed; order is preserved; items are compared using `eql?`:

    [0, 1] | [2, 3] # => [0, 1, 2, 3]
    [0, 1, 1] | [2, 2, 3] # => [0, 1, 2, 3]
    [0, 1, 2] | [3, 2, 1, 0] # => [0, 1, 2, 3]

Related: `Array#union`.

    static VALUE
    rb_ary_or(VALUE ary1, VALUE ary2)
    {
        VALUE hash;

        ary2 = to_ary(ary2);
        if (RARRAY_LEN(ary1) + RARRAY_LEN(ary2) <= SMALL_ARRAY_LEN) {
            VALUE ary3 = rb_ary_new();
            rb_ary_union(ary3, ary1);
            rb_ary_union(ary3, ary2);
            return ary3;
        }

        hash = ary_make_hash(ary1);
        rb_ary_union_hash(hash, ary2);

        return rb_hash_values(hash);
    }