# class Array

Arrays are ordered, integer-indexed collections of any object.

`Array` indexing starts at 0, as in C or Java. A negative index is assumed to be relative to the end of the array—that is, an index of -1 indicates the last element of the array, -2 is the next to last element in the array, and so on.

## Creating Arrays¶ ↑

A new array can be created by using the literal constructor `[]`. Arrays can contain different types of objects. For example, the array below contains an `Integer`, a `String` and a Float:

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

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

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

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

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

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

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

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

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

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

## Example Usage¶ ↑

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

Some of the more common ones are illustrated below.

## Accessing Elements¶ ↑

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

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

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

    arr.at(0) #=> 1

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

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

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

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

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

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

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

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

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

## Obtaining Information about an `Array`¶ ↑

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

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

To check whether an array contains any elements at all

    browsers.empty? #=> false

To check whether a particular item is included in the array

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

## Adding Items to Arrays¶ ↑

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

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

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

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

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

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

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

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

## Removing Items from an `Array`¶ ↑

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

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

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

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

To delete an element at a particular index:

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

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

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

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

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

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

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

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

## Iterating over Arrays¶ ↑

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

Note that this operation leaves the array unchanged.

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

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

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

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

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

## Selecting Items from an `Array`¶ ↑

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

### Non-destructive Selection¶ ↑

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

### Destructive Selection¶ ↑

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

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

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

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

### 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(size=0, default=nil) click to toggle source
new(array)
new(size) {|index| block }

Returns a new array.

In the first form, if no arguments are sent, the new array will be empty. When a `size` and an optional `default` are sent, an array is created with `size` copies of `default`. Take notice that all elements will reference the same object `default`.

The second form creates a copy of the array passed as a parameter (the array is generated by calling `to_ary` on the parameter).

    first_array = ["Matz", "Guido"]

    second_array = Array.new(first_array) #=> ["Matz", "Guido"]

    first_array.equal? second_array       #=> false

In the last form, an array of the given size is created. Each element in this array is created by passing the element's index to the given block and storing the return value.

    Array.new(3) {|index| index ** 2}
    # => [0, 1, 4]

## Common gotchas¶ ↑

When sending the second parameter, the same object will be used as the value for all the array elements:

    a = Array.new(2, Hash.new)
    # => [{}, {}]

    a[0]['cat'] = 'feline'
    a # => [{"cat"=>"feline"}, {"cat"=>"feline"}]

    a[1]['cat'] = 'Felix'
    a # => [{"cat"=>"Felix"}, {"cat"=>"Felix"}]

Since all the `Array` elements store the same hash, changes to one of them will affect them all.

If multiple copies are what you want, you should use the block version which uses the result of that block each time an element of the array needs to be initialized:

    a = Array.new(2) {Hash.new}
    a[0]['cat'] = 'feline'
    a # => [{"cat"=>"feline"}, {}]

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

        rb_ary_modify(ary);
        if (argc == 0) {
            if (ARY_OWNS_HEAP_P(ary) && ARY_HEAP_PTR(ary) != NULL) {
                ary_heap_free(ary);
            }
            rb_ary_unshare_safe(ary);
            FL_SET_EMBED(ary);
            ARY_SET_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(obj) → array or nil click to toggle source

Tries to convert `obj` into an array, using `to_ary` method. Returns the converted array or `nil` if `obj` cannot be converted for any reason. This method can be used to check if an argument is an array.

    Array.try_convert([1])   #=> [1]
    Array.try_convert("1")   #=> nil

    if tmp = Array.try_convert(arg)
      # the argument is an array
    elsif tmp = String.try_convert(arg)
      # the argument is a string
    end

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

### Public Instance Methods

ary & other_ary → new_ary click to toggle source

`Set` Intersection — Returns a new array containing unique elements common to the two arrays. The order is preserved from the original array.

It compares elements using their `hash` and `eql?` methods for efficiency.

    [ 1, 1, 3, 5 ] & [ 3, 2, 1 ]                 #=> [ 1, 3 ]
    [ 'a', 'b', 'b', 'z' ] & [ 'a', 'b', 'c' ]   #=> [ 'a', 'b' ]

See also `Array#uniq`.

    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);
            }
        }
        ary_recycle_hash(hash);

        return ary3;
    }

ary * int → new_ary click to toggle source
ary * str → new_string

Repetition — With a `String` argument, equivalent to `ary.join(str)`.

Otherwise, returns a new array built by concatenating the `int` copies of `self`.

    [ 1, 2, 3 ] * 3    #=> [ 1, 2, 3, 1, 2, 3, 1, 2, 3 ]
    [ 1, 2, 3 ] * ","  #=> "1,2,3"

    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_obj_class(ary), 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_obj_class(ary), len);
        ARY_SET_LEN(ary2, len);

        ptr = RARRAY_CONST_PTR_TRANSIENT(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_TRANSIENT(ary2));
                t *= 2;
            }
            if (t < len) {
                ary_memcpy(ary2, t, len-t, RARRAY_CONST_PTR_TRANSIENT(ary2));
            }
        }
      out:
        OBJ_INFECT(ary2, ary);

        return ary2;
    }

ary + other_ary → new_ary click to toggle source

Concatenation — Returns a new array built by concatenating the two arrays together to produce a third array.

    [ 1, 2, 3 ] + [ 4, 5 ]    #=> [ 1, 2, 3, 4, 5 ]
    a = [ "a", "b", "c" ]
    c = a + [ "d", "e", "f" ]
    c                         #=> [ "a", "b", "c", "d", "e", "f" ]
    a                         #=> [ "a", "b", "c" ]

Note that

    x += y

is the same as

    x = x + y

This means that it produces a new array. As a consequence, repeated use of `+=` on arrays can be quite inefficient.

See also `Array#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_TRANSIENT(x));
        ary_memcpy(z, xlen, ylen, RARRAY_CONST_PTR_TRANSIENT(y));
        ARY_SET_LEN(z, len);
        return z;
    }

ary - other_ary → new_ary click to toggle source

`Array` Difference

Returns a new array that is a copy of the original array, removing any items that also appear in `other_ary`. The order is preserved from the original array.

It compares elements using their `hash` and `eql?` methods for efficiency.

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

If you need set-like behavior, see the library class `Set`.

See also `Array#difference`.

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

        ary2 = to_ary(ary2);
        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));
        }
        ary_recycle_hash(hash);
        return ary3;
    }

ary << obj → ary click to toggle source

Append—Pushes the given object on to the end of this array. This expression returns the array itself, so several appends may be chained together.

    a = [ 1, 2 ]
    a << "c" << "d" << [ 3, 4 ]
            #=>  [ 1, 2, "c", "d", [ 3, 4 ] ]
    a
            #=>  [ 1, 2, "c", "d", [ 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_TRANSIENT(ary, ptr, {
            RB_OBJ_WRITE(target_ary, &ptr[idx], item);
        });
        ARY_SET_LEN(ary, idx + 1);
        ary_verify(ary);
        return ary;
    }

ary <=> other_ary → -1, 0, +1 or nil click to toggle source

Comparison — Returns an integer (`-1`, `0`, or `+1`) if this array is less than, equal to, or greater than `other_ary`.

Each object in each array is compared (using the <=> operator).

Arrays are compared in an “element-wise” manner; the first element of `ary` is compared with the first one of `other_ary` using the <=> operator, then each of the second elements, etc… As soon as the result of any such comparison is non zero (i.e. the two corresponding elements are not equal), that result is returned for the whole array comparison.

If all the elements are equal, then the result is based on a comparison of the array lengths. Thus, two arrays are “equal” according to Array#<=> if, and only if, they have the same length and the value of each element is equal to the value of the corresponding element in the other array.

`nil` is returned if the `other_ary` is not an array or if the comparison of two elements returned `nil`.

    [ "a", "a", "c" ]    <=> [ "a", "b", "c" ]   #=> -1
    [ 1, 2, 3, 4, 5, 6 ] <=> [ 1, 2 ]            #=> +1
    [ 1, 2 ]             <=> [ 1, :two ]         #=> nil

    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 (v != Qundef) return v;
        len = RARRAY_LEN(ary1) - RARRAY_LEN(ary2);
        if (len == 0) return INT2FIX(0);
        if (len > 0) return INT2FIX(1);
        return INT2FIX(-1);
    }

ary == other_ary → bool click to toggle source

Equality — Two arrays are equal if they contain the same number of elements and if each element is equal to (according to Object#==) the corresponding element in `other_ary`.

    [ "a", "c" ]    == [ "a", "c", 7 ]     #=> false
    [ "a", "c", 7 ] == [ "a", "c", 7 ]     #=> true
    [ "a", "c", 7 ] == [ "a", "d", "f" ]   #=> false

    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_TRANSIENT(ary1) == RARRAY_CONST_PTR_TRANSIENT(ary2)) return Qtrue;
        return rb_exec_recursive_paired(recursive_equal, ary1, ary2, ary2);
    }

ary[index] → obj or nil click to toggle source
ary[start, length] → new_ary or nil
ary[range] → new_ary or nil
slice(index) → obj or nil
slice(start, length) → new_ary or nil
slice(range) → new_ary or nil

Element Reference — Returns the element at `index`, or returns a subarray starting at the `start` index and continuing for `length` elements, or returns a subarray specified by `range` of indices.

Negative indices count backward from the end of the array (-1 is the last element). For `start` and `range` cases the starting index is just before an element. Additionally, an empty array is returned when the starting index for an element range is at the end of the array.

Returns `nil` if the index (or starting index) are out of range.

    a = [ "a", "b", "c", "d", "e" ]
    a[2] +  a[0] + a[1]    #=> "cab"
    a[6]                   #=> nil
    a[1, 2]                #=> [ "b", "c" ]
    a[1..3]                #=> [ "b", "c", "d" ]
    a[4..7]                #=> [ "e" ]
    a[6..10]               #=> nil
    a[-3, 3]               #=> [ "c", "d", "e" ]
    # special cases
    a[5]                   #=> nil
    a[6, 1]                #=> nil
    a[5, 1]                #=> []
    a[5..10]               #=> []

    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]);
    }

ary[index] = obj → obj click to toggle source
ary[start, length] = obj or other_ary or nil → obj or other_ary or nil
ary[range] = obj or other_ary or nil → obj or other_ary or nil

Element Assignment — Sets the element at `index`, or replaces a subarray from the `start` index for `length` elements, or replaces a subarray specified by the `range` of indices.

If indices are greater than the current capacity of the array, the array grows automatically. Elements are inserted into the array at `start` if `length` is zero.

Negative indices will count backward from the end of the array. For `start` and `range` cases the starting index is just before an element.

An `IndexError` is raised if a negative index points past the beginning of the array.

See also `Array#push`, and `Array#unshift`.

    a = Array.new
    a[4] = "4";                 #=> [nil, nil, nil, nil, "4"]
    a[0, 3] = [ 'a', 'b', 'c' ] #=> ["a", "b", "c", nil, "4"]
    a[1..2] = [ 1, 2 ]          #=> ["a", 1, 2, nil, "4"]
    a[0, 2] = "?"               #=> ["?", 2, nil, "4"]
    a[0..2] = "A"               #=> ["A", "4"]
    a[-1]   = "Z"               #=> ["A", "Z"]
    a[1..-1] = nil              #=> ["A", nil]
    a[1..-1] = []               #=> ["A"]
    a[0, 0] = [ 1, 2 ]          #=> [1, 2, "A"]
    a[3, 0] = "B"               #=> [1, 2, "A", "B"]

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

        if (argc == 3) {
            rb_ary_modify_check(ary);
            beg = NUM2LONG(argv[0]);
            len = NUM2LONG(argv[1]);
            goto range;
        }
        rb_check_arity(argc, 2, 2);
        rb_ary_modify_check(ary);
        if (FIXNUM_P(argv[0])) {
            offset = FIX2LONG(argv[0]);
            goto fixnum;
        }
        if (rb_range_beg_len(argv[0], &beg, &len, RARRAY_LEN(ary), 1)) {
            /* check if idx is Range */
          range:
            rpl = rb_ary_to_ary(argv[argc-1]);
            rb_ary_splice(ary, beg, len, RARRAY_CONST_PTR_TRANSIENT(rpl), RARRAY_LEN(rpl));
            RB_GC_GUARD(rpl);
            return argv[argc-1];
        }

        offset = NUM2LONG(argv[0]);
    fixnum:
        rb_ary_store(ary, offset, argv[1]);
        return 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 129
    def abbrev(pattern = nil)
      Abbrev::abbrev(self, pattern)
    end

all? [{|obj| block} ] → true or false click to toggle source
all?(pattern) → true or false

See also `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? [{|obj| block} ] → true or false click to toggle source
any?(pattern) → true or false

See also `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(*args)
Alias for: push
assoc(obj) → element_ary or nil click to toggle source

Searches through an array whose elements are also arrays comparing `obj` with the first element of each contained array using `obj.==`.

Returns the first contained array that matches (that is, the first associated array), or `nil` if no match is found.

See also `Array#rassoc`

    s1 = [ "colors", "red", "blue", "green" ]
    s2 = [ "letters", "a", "b", "c" ]
    s3 = "foo"
    a  = [ s1, s2, s3 ]
    a.assoc("letters")  #=> [ "letters", "a", "b", "c" ]
    a.assoc("foo")      #=> nil

    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) → obj or nil click to toggle source

Returns the element at `index`. A negative index counts from the end of `self`. Returns `nil` if the index is out of range. See also `Array#[]`.

    a = [ "a", "b", "c", "d", "e" ]
    a.at(0)     #=> "a"
    a.at(-1)    #=> "e"

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

bsearch {|x| block } → elem click to toggle source

By using binary search, finds a value from this array which meets the given condition in O(log n) where n is the size of the array.

You can use this method in two modes: a find-minimum mode and a find-any mode. In either case, the elements of the array must be monotone (or sorted) with respect to the block.

In find-minimum mode (this is a good choice for typical use cases), the block must always return true or false, and there must be an index i (0 <= i <= ary.size) so that:

- the block returns false for any element whose index is less than i, and

- the block returns true for any element whose index is greater than or equal to i.

This method returns the i-th element. If i is equal to ary.size, it returns nil.

    ary = [0, 4, 7, 10, 12]
    ary.bsearch {|x| x >=   4 } #=> 4
    ary.bsearch {|x| x >=   6 } #=> 7
    ary.bsearch {|x| x >=  -1 } #=> 0
    ary.bsearch {|x| x >= 100 } #=> nil

In find-any mode (this behaves like libc's bsearch(3)), the block must always return a number, and there must be two indices i and j (0 <= i <= j <= ary.size) so that:

- the block returns a positive number for ary if 0 <= k < i,

- the block returns zero for ary if i <= k < j, and

- the block returns a negative number for ary if j <= k < ary.size.

Under this condition, this method returns any element whose index is within i…j. If i is equal to j (i.e., there is no element that satisfies the block), this method returns nil.

    ary = [0, 4, 7, 10, 12]
    # try to find v such that 4 <= v < 8
    ary.bsearch {|x| 1 - x / 4 } #=> 4 or 7
    # try to find v such that 8 <= v < 10
    ary.bsearch {|x| 4 - x / 2 } #=> nil

You must not mix the two modes at a time; the block must always return either true/false, or always return a number. It is undefined which value is actually picked up at each iteration.

    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 {|x| block } → int or nil click to toggle source

By using binary search, finds an index of a value from this array which meets the given condition in O(log n) where n is the size of the array.

It supports two modes, depending on the nature of the block. They are exactly the same as in the case of the `bsearch` method, with the only difference being that this method returns the index of the element instead of the element itself. For more details consult the documentation for `bsearch`.

    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 (v == Qfalse || v == Qnil) {
                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 = 1; break;
                  case -1: smaller = 0;
                }
            }
            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 → ary click to toggle source

Removes all elements from `self`.

    a = [ "a", "b", "c", "d", "e" ]
    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 {|item| block} → new_ary click to toggle source
collect → Enumerator

Invokes the given block once for each element of `self`.

Creates a new array containing the values returned by the block.

See also `Enumerable#collect`.

If no block is given, an `Enumerator` is returned instead.

    a = [ "a", "b", "c", "d" ]
    a.collect {|x| x + "!"}           #=> ["a!", "b!", "c!", "d!"]
    a.map.with_index {|x, i| x * i}   #=> ["", "b", "cc", "ddd"]
    a                                 #=> ["a", "b", "c", "d"]

    static VALUE
    rb_ary_collect(VALUE ary)
    {
        long i;
        VALUE collect;

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

collect! {|item| block } → ary click to toggle source
collect! → Enumerator

Invokes the given block once for each element of `self`, replacing the element with the value returned by the block.

See also `Enumerable#collect`.

If no block is given, an `Enumerator` is returned instead.

    a = [ "a", "b", "c", "d" ]
    a.map! {|x| x + "!" }
    a #=>  [ "a!", "b!", "c!", "d!" ]
    a.collect!.with_index {|x, i| x[0...i] }
    a #=>  ["", "b", "c!", "d!"]

    static VALUE
    rb_ary_collect_bang(VALUE ary)
    {
        long i;

        RETURN_SIZED_ENUMERATOR(ary, 0, 0, ary_enum_length);
        rb_ary_modify(ary);
        for (i = 0; i < RARRAY_LEN(ary); i++) {
            rb_ary_store(ary, i, rb_yield(RARRAY_AREF(ary, i)));
        }
        return ary;
    }

combination(n) {|c| block} → ary click to toggle source
combination(n) → Enumerator

When invoked with a block, yields all combinations of length `n` of elements from the array and then returns the array itself.

The implementation makes no guarantees about the order in which the combinations are yielded.

If no block is given, an `Enumerator` is returned instead.

Examples:

    a = [1, 2, 3, 4]
    a.combination(1).to_a  #=> [[1],[2],[3],[4]]
    a.combination(2).to_a  #=> [[1,2],[1,3],[1,4],[2,3],[2,4],[3,4]]
    a.combination(3).to_a  #=> [[1,2,3],[1,2,4],[1,3,4],[2,3,4]]
    a.combination(4).to_a  #=> [[1,2,3,4]]
    a.combination(0).to_a  #=> [[]] # one combination of length 0
    a.combination(5).to_a  #=> []   # no combinations of length 5

    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_ary click to toggle source

Returns a copy of `self` with all `nil` elements removed.

    [ "a", nil, "b", nil, "c", nil ].compact
                      #=> [ "a", "b", "c" ]

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

compact! → ary or nil click to toggle source

Removes `nil` elements from the array.

Returns `nil` if no changes were made, otherwise returns the array.

    [ "a", nil, "b", nil, "c" ].compact! #=> [ "a", "b", "c" ]
    [ "a", "b", "c" ].compact!           #=> 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_TRANSIENT(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_TRANSIENT(ary);
        if (RARRAY_LEN(ary) == n) {
            return Qnil;
        }
        ary_resize_smaller(ary, n);

        return ary;
    }

concat(other_ary1, other_ary2, ...) → ary click to toggle source

Appends the elements of `other_ary`s to `self`.

    [ "a", "b" ].concat( ["c", "d"])   #=> [ "a", "b", "c", "d" ]
    [ "a" ].concat( ["b"], ["c", "d"]) #=> [ "a", "b", "c", "d" ]
    [ "a" ].concat #=> [ "a" ]

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

    a = [ 1, 2 ]
    a.concat(a, a)                    #=> [1, 2, 1, 2, 1, 2]

See also `Array#+`.

    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_tmp_new(argc);
            for (i = 0; i < argc; i++) {
                rb_ary_concat(args, argv[i]);
            }
            ary_append(ary, args);
        }

        ary_verify(ary);
        return ary;
    }

count → int click to toggle source
count(obj) → int
count {|item| block} → int

Returns the number of elements.

If an argument is given, counts the number of elements which equal `obj` using `==`.

If a block is given, counts the number of elements for which the block returns a true value.

    ary = [1, 2, 4, 2]
    ary.count                  #=> 4
    ary.count(2)               #=> 2
    ary.count {|x| x%2 == 0}   #=> 3

    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(n=nil) {|obj| block} → nil click to toggle source
cycle(n=nil) → Enumerator

Calls the given block for each element `n` times or forever if `nil` is given.

Does nothing if a non-positive number is given or the array is empty.

Returns `nil` if the loop has finished without getting interrupted.

If no block is given, an `Enumerator` is returned instead.

    a = ["a", "b", "c"]
    a.cycle {|x| puts x}       # print, a, b, c, a, b, c,.. forever.
    a.cycle(2) {|x| puts x}    # print, a, b, c, a, b, c.

    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;
    }

dclone() click to toggle source

provides a unified `clone` operation, for `REXML::XPathParser` to use across multiple Object+ types

    # File lib/rexml/xpath_parser.rb, line 33
    def dclone
      klone = self.clone
      klone.clear
      self.each{|v| klone << v.dclone}
      klone
    end

delete(obj) → item or nil click to toggle source
delete(obj) {block} → item or result of block

Deletes all items from `self` that are equal to `obj`.

Returns the last deleted item, or `nil` if no matching item is found.

If the optional code block is given, the result of the block is returned if the item is not found. (To remove `nil` elements and get an informative return value, use `Array#compact!`)

    a = [ "a", "b", "b", "b", "c" ]
    a.delete("b")                   #=> "b"
    a                               #=> ["a", "c"]
    a.delete("z")                   #=> nil
    a.delete("z") {"not found"}     #=> "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) → obj or nil click to toggle source

Deletes the element at the specified `index`, returning that element, or `nil` if the `index` is out of range.

See also `Array#slice!`

    a = ["ant", "bat", "cat", "dog"]
    a.delete_at(2)    #=> "cat"
    a                 #=> ["ant", "bat", "dog"]
    a.delete_at(99)   #=> nil

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

delete_if {|item| block} → ary click to toggle source
delete_if → Enumerator

Deletes every element of `self` for which block evaluates to `true`.

The array is changed instantly every time the block is called, not after the iteration is over.

See also `Array#reject!`

If no block is given, an `Enumerator` is returned instead.

    scores = [ 97, 42, 75 ]
    scores.delete_if {|score| score < 80 }   #=> [97]

    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_ary1, other_ary2, ...) → ary click to toggle source

`Array` Difference

Returns a new array that is a copy of the receiver, removing any items that also appear in any of the arrays given as arguments. The order is preserved from the original array.

It compares elements using their `hash` and `eql?` methods for efficiency.

    [ 1, 1, 2, 2, 3, 3, 4, 5 ].difference([ 1, 2, 4 ])     #=> [ 3, 3, 5 ]
    [ 1, 'c', :s, 'yep' ].difference([ 1 ], [ 'a', 'c' ])  #=> [ :s, "yep" ]

If you need set-like behavior, see the library class `Set`.

See also `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(idx, ...) → object click to toggle source

Extracts the nested value specified by the sequence of idx objects by calling `dig` at each step, returning `nil` if any intermediate step is `nil`.

    a = [[1, [2, 3]]]

    a.dig(0, 1, 1)                    #=> 3
    a.dig(1, 2, 3)                    #=> nil
    a.dig(0, 0, 0)                    #=> TypeError: Integer does not have #dig method
    [42, {foo: :bar}].dig(1, :foo)    #=> :bar

    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_ary click to toggle source

Drops first `n` elements from `ary` and returns the rest of the elements in an array.

If a negative number is given, raises an `ArgumentError`.

See also `Array#take`

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

    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 (result == Qnil) result = rb_ary_new();
        return result;
    }

drop_while {|obj| block} → new_ary click to toggle source
drop_while → Enumerator

Drops elements up to, but not including, the first element for which the block returns `nil` or `false` and returns an array containing the remaining elements.

If no block is given, an `Enumerator` is returned instead.

See also `Array#take_while`

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

    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 {|item| block} → ary click to toggle source
each → Enumerator

Calls the given block once for each element in `self`, passing that element as a parameter. Returns the array itself.

If no block is given, an `Enumerator` is returned.

    a = [ "a", "b", "c" ]
    a.each {|x| print x, " -- " }

produces:

    a -- b -- c --

    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| block} → ary click to toggle source
each_index → Enumerator

Same as `Array#each`, but passes the `index` of the element instead of the element itself.

An `Enumerator` is returned if no block is given.

    a = [ "a", "b", "c" ]
    a.each_index {|x| print x, " -- " }

produces:

    0 -- 1 -- 2 --

    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 `self` contains no elements.

    [].empty?   #=> true

    static VALUE
    rb_ary_empty_p(VALUE ary)
    {
        if (RARRAY_LEN(ary) == 0)
            return Qtrue;
        return Qfalse;
    }

eql?(other) → true or false click to toggle source

Returns `true` if `self` and `other` are the same object, or are both arrays with the same content (according to `Object#eql?`).

    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_TRANSIENT(ary1) == RARRAY_CONST_PTR_TRANSIENT(ary2)) return Qtrue;
        return rb_exec_recursive_paired(recursive_eql, ary1, ary2, ary2);
    }

fetch(index) → obj click to toggle source
fetch(index, default) → obj
fetch(index) {|index| block} → obj

Tries to return the element at position `index`, but throws an `IndexError` exception if the referenced `index` lies outside of the array bounds. This error can be prevented by supplying a second argument, which will act as a `default` value.

Alternatively, if a block is given it will only be executed when an invalid `index` is referenced.

Negative values of `index` count from the end of the array.

    a = [ 11, 22, 33, 44 ]
    a.fetch(1)               #=> 22
    a.fetch(-1)              #=> 44
    a.fetch(4, 'cat')        #=> "cat"
    a.fetch(100) {|i| puts "#{i} is out of bounds"}
                             #=> "100 is out of bounds"

    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) → ary click to toggle source
fill(obj, start [, length]) → ary
fill(obj, range) → ary
fill {|index| block} → ary
fill(start [, length]) {|index| block} → ary
fill(range) {|index| block} → ary

The first three forms set the selected elements of `self` (which may be the entire array) to `obj`.

A `start` of `nil` is equivalent to zero.

A `length` of `nil` is equivalent to the length of the array.

The last three forms fill the array with the value of the given block, which is passed the absolute index of each element to be filled.

Negative values of `start` count from the end of the array, where `-1` is the last element.

    a = [ "a", "b", "c", "d" ]
    a.fill("x")              #=> ["x", "x", "x", "x"]
    a.fill("z", 2, 2)        #=> ["x", "x", "z", "z"]
    a.fill("y", 0..1)        #=> ["y", "y", "z", "z"]
    a.fill {|i| i*i}         #=> [0, 1, 4, 9]
    a.fill(-2) {|i| i*i*i}   #=> [0, 1, 8, 27]

    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 (item == Qundef) {
            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 {|item| block} → new_ary click to toggle source
filter → Enumerator

Returns a new array containing all elements of `ary` for which the given `block` returns a true value.

If no block is given, an `Enumerator` is returned instead.

    [1,2,3,4,5].select {|num| num.even? }     #=> [2, 4]

    a = %w[ a b c d e f ]
    a.select {|v| v =~ /[aeiou]/ }    #=> ["a", "e"]

See also `Enumerable#select`.

`Array#filter` is an alias for `Array#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;
    }

filter! {|item| block } → ary or nil click to toggle source
filter! → Enumerator

Invokes the given block passing in successive elements from `self`, deleting elements for which the block returns a `false` value.

The array may not be changed instantly every time the block is called.

If changes were made, it will return `self`, otherwise it returns `nil`.

If no block is given, an `Enumerator` is returned instead.

See also `Array#keep_if`.

`Array#filter!` is an alias for `Array#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);
    }

find_index(obj) → int or nil click to toggle source
find_index {|item| block} → int or nil
find_index → Enumerator

Returns the index of the first object in `ary` such that the object is `==` to `obj`.

If a block is given instead of an argument, returns the index of the first object for which the block returns `true`. Returns `nil` if no match is found.

See also `Array#rindex`.

An `Enumerator` is returned if neither a block nor argument is given.

    a = [ "a", "b", "c" ]
    a.index("b")              #=> 1
    a.index("z")              #=> nil
    a.index {|x| x == "b"}    #=> 1

    static VALUE
    rb_ary_index(int argc, VALUE *argv, VALUE ary)
    {
        VALUE val;
        long i;

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

first → obj or nil click to toggle source
first(n) → new_ary

Returns the first element, or the first `n` elements, of the array. If the array is empty, the first form returns `nil`, and the second form returns an empty array. See also `Array#last` for the opposite effect.

    a = [ "q", "r", "s", "t" ]
    a.first     #=> "q"
    a.first(2)  #=> ["q", "r"]

    static VALUE
    rb_ary_first(int argc, VALUE *argv, VALUE ary)
    {
        if (argc == 0) {
            if (RARRAY_LEN(ary) == 0) return Qnil;
            return RARRAY_AREF(ary, 0);
        }
        else {
            return ary_take_first_or_last(argc, argv, ary, ARY_TAKE_FIRST);
        }
    }

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

Returns a new array that is a one-dimensional flattening of `self` (recursively).

That is, for every element that is an array, extract its elements into the new array.

The optional `level` argument determines the level of recursion to flatten.

    s = [ 1, 2, 3 ]           #=> [1, 2, 3]
    t = [ 4, 5, 6, [7, 8] ]   #=> [4, 5, 6, [7, 8]]
    a = [ s, t, 9, 10 ]       #=> [[1, 2, 3], [4, 5, 6, [7, 8]], 9, 10]
    a.flatten                 #=> [1, 2, 3, 4, 5, 6, 7, 8, 9, 10]
    a = [ 1, 2, [3, [4, 5] ] ]
    a.flatten(1)              #=> [1, 2, 3, [4, 5]]

    static VALUE
    rb_ary_flatten(int argc, VALUE *argv, VALUE ary)
    {
        int mod = 0, 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, &mod);
        OBJ_INFECT(result, ary);

        return result;
    }

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

Flattens `self` in place.

Returns `nil` if no modifications were made (i.e., the array contains no subarrays.)

The optional `level` argument determines the level of recursion to flatten.

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

    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, &mod);
        if (mod == 0) {
            ary_discard(result);
            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

Compute a hash-code for this array.

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

See also Object#hash.

    static VALUE
    rb_ary_hash(VALUE ary)
    {
        long i;
        st_index_t h;
        VALUE n;

        h = rb_hash_start(RARRAY_LEN(ary));
        h = rb_hash_uint(h, (st_index_t)rb_ary_hash);
        for (i=0; i<RARRAY_LEN(ary); i++) {
            n = rb_hash(RARRAY_AREF(ary, i));
            h = rb_hash_uint(h, NUM2LONG(n));
        }
        h = rb_hash_end(h);
        return ST2FIX(h);
    }

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

Returns `true` if the given `object` is present in `self` (that is, if any element `==` `object`), otherwise returns `false`.

    a = [ "a", "b", "c" ]
    a.include?("b")   #=> true
    a.include?("z")   #=> 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(obj) → int or nil click to toggle source
index {|item| block} → int or nil
index → Enumerator

Returns the index of the first object in `ary` such that the object is `==` to `obj`.

If a block is given instead of an argument, returns the index of the first object for which the block returns `true`. Returns `nil` if no match is found.

See also `Array#rindex`.

An `Enumerator` is returned if neither a block nor argument is given.

    a = [ "a", "b", "c" ]
    a.index("b")              #=> 1
    a.index("z")              #=> nil
    a.index {|x| x == "b"}    #=> 1

    static VALUE
    rb_ary_index(int argc, VALUE *argv, VALUE ary)
    {
        VALUE val;
        long i;

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

initialize_copy(other_ary) → ary click to toggle source

Replaces the contents of `self` with the contents of `other_ary`, truncating or expanding if necessary.

    a = [ "a", "b", "c", "d", "e" ]
    a.replace([ "x", "y", "z" ])   #=> ["x", "y", "z"]
    a                              #=> ["x", "y", "z"]

    VALUE
    rb_ary_replace(VALUE copy, VALUE orig)
    {
        rb_ary_modify_check(copy);
        orig = to_ary(orig);
        if (copy == orig) return copy;

        if (RARRAY_LEN(orig) <= RARRAY_EMBED_LEN_MAX) {
            VALUE shared = 0;

            if (ARY_OWNS_HEAP_P(copy)) {
                ary_heap_free(copy);
            }
            else if (ARY_SHARED_P(copy)) {
                shared = ARY_SHARED(copy);
                FL_UNSET_SHARED(copy);
            }
            FL_SET_EMBED(copy);
            ary_memcpy(copy, 0, RARRAY_LEN(orig), RARRAY_CONST_PTR_TRANSIENT(orig));
            if (shared) {
                rb_ary_decrement_share(shared);
            }
            ARY_SET_LEN(copy, RARRAY_LEN(orig));
        }
        else {
            VALUE shared = ary_make_shared(orig);
            if (ARY_OWNS_HEAP_P(copy)) {
                ary_heap_free(copy);
            }
            else {
                rb_ary_unshare_safe(copy);
            }
            FL_UNSET_EMBED(copy);
            ARY_SET_PTR(copy, ARY_HEAP_PTR(orig));
            ARY_SET_LEN(copy, ARY_HEAP_LEN(orig));
            rb_ary_set_shared(copy, shared);
        }
        ary_verify(copy);
        return copy;
    }

insert(index, obj...) → ary click to toggle source

Inserts the given values before the element with the given `index`.

Negative indices count backwards from the end of the array, where `-1` is the last element. If a negative index is used, the given values will be inserted after that element, so using an index of `-1` will insert the values at the end of the array.

    a = %w{ a b c d }
    a.insert(2, 99)         #=> ["a", "b", 99, "c", "d"]
    a.insert(-2, 1, 2, 3)   #=> ["a", "b", 99, "c", 1, 2, 3, "d"]

    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 → string click to toggle source
to_s → string

Creates a string representation of `self`.

    [ "a", "b", "c" ].to_s     #=> "[\"a\", \"b\", \"c\"]"

    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
join(separator=$,) → str click to toggle source

Returns a string created by converting each element of the array to a string, separated by the given `separator`. If the `separator` is `nil`, it uses current `$,`. If both the `separator` and `$,` are `nil`, it uses an empty string.

    [ "a", "b", "c" ].join        #=> "abc"
    [ "a", "b", "c" ].join("-")   #=> "a-b-c"

For nested arrays, join is applied recursively:

    [ "a", [1, 2, [:x, :y]], "b" ].join("-")   #=> "a-1-2-x-y-b"

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

        if (rb_check_arity(argc, 0, 1) == 0) {
            sep = rb_output_fs;
        }
        else if (NIL_P(sep = argv[0])) {
            sep = rb_output_fs;
        }

        return rb_ary_join(ary, sep);
    }

keep_if {|item| block} → ary click to toggle source
keep_if → Enumerator

Deletes every element of `self` for which the given block evaluates to `false`, and returns `self`.

If no block is given, an `Enumerator` is returned instead.

    a = %w[ a b c d e f ]
    a.keep_if {|v| v =~ /[aeiou]/ }    #=> ["a", "e"]
    a                                  #=> ["a", "e"]

See also `Array#select!`.

    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 → obj or nil click to toggle source
last(n) → new_ary

Returns the last element(s) of `self`. If the array is empty, the first form returns `nil`.

See also `Array#first` for the opposite effect.

    a = [ "w", "x", "y", "z" ]
    a.last     #=> "z"
    a.last(2)  #=> ["y", "z"]

    VALUE
    rb_ary_last(int argc, const VALUE *argv, VALUE ary)
    {
        if (argc == 0) {
            long len = RARRAY_LEN(ary);
            if (len == 0) return Qnil;
            return RARRAY_AREF(ary, len-1);
        }
        else {
            return ary_take_first_or_last(argc, argv, ary, ARY_TAKE_LAST);
        }
    }

length → int click to toggle source

Returns the number of elements in `self`. May be zero.

    [ 1, 2, 3, 4, 5 ].length   #=> 5
    [].length                  #=> 0

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

Also aliased as: size
map {|item| block} → new_ary click to toggle source
map → Enumerator

Invokes the given block once for each element of `self`.

Creates a new array containing the values returned by the block.

See also `Enumerable#collect`.

If no block is given, an `Enumerator` is returned instead.

    a = [ "a", "b", "c", "d" ]
    a.collect {|x| x + "!"}           #=> ["a!", "b!", "c!", "d!"]
    a.map.with_index {|x, i| x * i}   #=> ["", "b", "cc", "ddd"]
    a                                 #=> ["a", "b", "c", "d"]

    static VALUE
    rb_ary_collect(VALUE ary)
    {
        long i;
        VALUE collect;

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

map! {|item| block } → ary click to toggle source
map! → Enumerator

Invokes the given block once for each element of `self`, replacing the element with the value returned by the block.

See also `Enumerable#collect`.

If no block is given, an `Enumerator` is returned instead.

    a = [ "a", "b", "c", "d" ]
    a.map! {|x| x + "!" }
    a #=>  [ "a!", "b!", "c!", "d!" ]
    a.collect!.with_index {|x, i| x[0...i] }
    a #=>  ["", "b", "c!", "d!"]

    static VALUE
    rb_ary_collect_bang(VALUE ary)
    {
        long i;

        RETURN_SIZED_ENUMERATOR(ary, 0, 0, ary_enum_length);
        rb_ary_modify(ary);
        for (i = 0; i < RARRAY_LEN(ary); i++) {
            rb_ary_store(ary, i, rb_yield(RARRAY_AREF(ary, i)));
        }
        return ary;
    }

max → obj click to toggle source
max {|a, b| block} → obj
max(n) → array
max(n) {|a, b| block} → array

Returns the object in ary with the maximum value. The first form assumes all objects implement `Comparable`; the second uses the block to return a <=> b.

    ary = %w(albatross dog horse)
    ary.max                                   #=> "horse"
    ary.max {|a, b| a.length <=> b.length}    #=> "albatross"

If the `n` argument is given, maximum `n` elements are returned as an array.

    ary = %w[albatross dog horse]
    ary.max(2)                                  #=> ["horse", "dog"]
    ary.max(2) {|a, b| a.length <=> b.length }  #=> ["albatross", "horse"]

    static VALUE
    rb_ary_max(int argc, VALUE *argv, VALUE ary)
    {
        struct cmp_opt_data cmp_opt = { 0, 0 };
        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);

        if (rb_block_given_p()) {
            for (i = 0; i < RARRAY_LEN(ary); i++) {
               v = RARRAY_AREF(ary, i);
               if (result == Qundef || rb_cmpint(rb_yield_values(2, v, result), v, result) > 0) {
                   result = v;
               }
            }
        }
        else {
            for (i = 0; i < RARRAY_LEN(ary); i++) {
               v = RARRAY_AREF(ary, i);
               if (result == Qundef || OPTIMIZED_CMP(v, result, cmp_opt) > 0) {
                   result = v;
               }
            }
        }
        if (result == Qundef) return Qnil;
        return result;
    }

min → obj click to toggle source
min {| a,b | block } → obj
min(n) → array
min(n) {| a,b | block } → array

Returns the object in ary with the minimum value. The first form assumes all objects implement `Comparable`; the second uses the block to return a <=> b.

    ary = %w(albatross dog horse)
    ary.min                                   #=> "albatross"
    ary.min {|a, b| a.length <=> b.length}    #=> "dog"

If the `n` argument is given, minimum `n` elements are returned as an array.

    ary = %w[albatross dog horse]
    ary.min(2)                                  #=> ["albatross", "dog"]
    ary.min(2) {|a, b| a.length <=> b.length }  #=> ["dog", "horse"]

    static VALUE
    rb_ary_min(int argc, VALUE *argv, VALUE ary)
    {
        struct cmp_opt_data cmp_opt = { 0, 0 };
        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);

        if (rb_block_given_p()) {
            for (i = 0; i < RARRAY_LEN(ary); i++) {
               v = RARRAY_AREF(ary, i);
               if (result == Qundef || rb_cmpint(rb_yield_values(2, v, result), v, result) < 0) {
                   result = v;
               }
            }
        }
        else {
            for (i = 0; i < RARRAY_LEN(ary); i++) {
               v = RARRAY_AREF(ary, i);
               if (result == Qundef || OPTIMIZED_CMP(v, result, cmp_opt) < 0) {
                   result = v;
               }
            }
        }
        if (result == Qundef) return Qnil;
        return result;
    }

none? [{|obj| block} ] → true or false click to toggle source
none?(pattern) → true or false

See also `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? [{|obj| block} ] → true or false click to toggle source
one?(pattern) → true or false

See also `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( aTemplateString ) → aBinaryString click to toggle source
pack( aTemplateString, buffer: aBufferString ) → aBufferString

Packs the contents of arr into a binary sequence according to the directives in aTemplateString (see the table below) Directives “A,'' “a,'' and “Z'' may be followed by a count, which gives the width of the resulting field. The remaining directives also may take a count, indicating the number of array elements to convert. If the count is an asterisk (“`*`''), all remaining array elements will be converted. Any of the directives “`sSiIlL`'' may be followed by an underscore (“`_`'') or exclamation mark (“`!`'') to use the underlying platform's native size for the specified type; otherwise, they use a platform-independent size. Spaces are ignored in the template string. See also `String#unpack`.

    a = [ "a", "b", "c" ]
    n = [ 65, 66, 67 ]
    a.pack("A3A3A3")   #=> "a  b  c  "
    a.pack("a3a3a3")   #=> "a\000\000b\000\000c\000\000"
    n.pack("ccc")      #=> "ABC"

If aBufferString is specified and its capacity is enough, `pack` uses it as the buffer and returns it. When the offset is specified by the beginning of aTemplateString, the result is filled after the offset. If original contents of aBufferString exists and it's longer than the offset, the rest of offsetOfBuffer are overwritten by the result. If it's shorter, the gap is filled with “`\0`''.

Note that “buffer:'' option does not guarantee not to allocate memory in `pack`. If the capacity of aBufferString is not enough, `pack` allocates memory.

Directives for `pack`.

    Integer       | Array   |
    Directive     | Element | Meaning
    ----------------------------------------------------------------------------
    C             | Integer | 8-bit unsigned (unsigned char)
    S             | Integer | 16-bit unsigned, native endian (uint16_t)
    L             | Integer | 32-bit unsigned, native endian (uint32_t)
    Q             | Integer | 64-bit unsigned, native endian (uint64_t)
    J             | Integer | pointer width unsigned, native endian (uintptr_t)
                  |         | (J is available since Ruby 2.3.)
                  |         |
    c             | Integer | 8-bit signed (signed char)
    s             | Integer | 16-bit signed, native endian (int16_t)
    l             | Integer | 32-bit signed, native endian (int32_t)
    q             | Integer | 64-bit signed, native endian (int64_t)
    j             | Integer | pointer width signed, native endian (intptr_t)
                  |         | (j is available since Ruby 2.3.)
                  |         |
    S_ S!         | Integer | unsigned short, native endian
    I I_ I!       | Integer | unsigned int, native endian
    L_ L!         | Integer | unsigned long, native endian
    Q_ Q!         | Integer | unsigned long long, native endian (ArgumentError
                  |         | if the platform has no long long type.)
                  |         | (Q_ and Q! is available since Ruby 2.1.)
    J!            | Integer | uintptr_t, native endian (same with J)
                  |         | (J! is available since Ruby 2.3.)
                  |         |
    s_ s!         | Integer | signed short, native endian
    i i_ i!       | Integer | signed int, native endian
    l_ l!         | Integer | signed long, native endian
    q_ q!         | Integer | signed long long, native endian (ArgumentError
                  |         | if the platform has no long long type.)
                  |         | (q_ and q! is available since Ruby 2.1.)
    j!            | Integer | intptr_t, native endian (same with j)
                  |         | (j! is available since Ruby 2.3.)
                  |         |
    S> s> S!> s!> | Integer | same as the directives without ">" except
    L> l> L!> l!> |         | big endian
    I!> i!>       |         | (available since Ruby 1.9.3)
    Q> q> Q!> q!> |         | "S>" is same as "n"
    J> j> J!> j!> |         | "L>" is same as "N"
                  |         |
    S< s< S!< s!< | Integer | same as the directives without "<" except
    L< l< L!< l!< |         | little endian
    I!< i!<       |         | (available since Ruby 1.9.3)
    Q< q< Q!< q!< |         | "S<" is same as "v"
    J< j< J!< j!< |         | "L<" is same as "V"
                  |         |
    n             | Integer | 16-bit unsigned, network (big-endian) byte order
    N             | Integer | 32-bit unsigned, network (big-endian) byte order
    v             | Integer | 16-bit unsigned, VAX (little-endian) byte order
    V             | Integer | 32-bit unsigned, VAX (little-endian) byte order
                  |         |
    U             | Integer | UTF-8 character
    w             | Integer | BER-compressed integer

    Float        | Array   |
    Directive    | Element | Meaning
    ---------------------------------------------------------------------------
    D d          | Float   | double-precision, native format
    F f          | Float   | single-precision, native format
    E            | Float   | double-precision, little-endian byte order
    e            | Float   | single-precision, little-endian byte order
    G            | Float   | double-precision, network (big-endian) byte order
    g            | Float   | single-precision, network (big-endian) byte order

    String       | Array   |
    Directive    | Element | Meaning
    ---------------------------------------------------------------------------
    A            | String  | arbitrary binary string (space padded, count is width)
    a            | String  | arbitrary binary string (null padded, count is width)
    Z            | String  | same as ``a'', except that null is added with *
    B            | String  | bit string (MSB first)
    b            | String  | bit string (LSB first)
    H            | String  | hex string (high nibble first)
    h            | String  | hex string (low nibble first)
    u            | String  | UU-encoded string
    M            | String  | quoted printable, MIME encoding (see also RFC2045)
                 |         | (text mode but input must use LF and output LF)
    m            | String  | base64 encoded string (see RFC 2045, count is width)
                 |         | (if count is 0, no line feed are added, see RFC 4648)
    P            | String  | pointer to a structure (fixed-length string)
    p            | String  | pointer to a null-terminated string

    Misc.        | Array   |
    Directive    | Element | Meaning
    ---------------------------------------------------------------------------
    @            | ---     | moves to absolute position
    X            | ---     | back up a byte
    x            | ---     | null byte

    static VALUE
    pack_pack(int argc, VALUE *argv, VALUE ary)
    {
        static const char nul10[] = "\0\0\0\0\0\0\0\0\0\0";
        static const char spc10[] = "          ";
        const char *p, *pend;
        VALUE fmt, opt = Qnil, res, from, associates = 0, buffer = 0;
        char type;
        long len, idx, plen;
        const char *ptr;
        int enc_info = 1;           /* 0 - BINARY, 1 - US-ASCII, 2 - UTF-8 */
    #ifdef NATINT_PACK
        int natint;         /* native integer */
    #endif
        int integer_size, bigendian_p;

        rb_scan_args(argc, argv, "10:", &fmt, &opt);

        StringValue(fmt);
        p = RSTRING_PTR(fmt);
        pend = p + RSTRING_LEN(fmt);
        if (!NIL_P(opt)) {
            static ID keyword_ids[1];
            if (!keyword_ids[0])
                CONST_ID(keyword_ids[0], "buffer");

            rb_get_kwargs(opt, keyword_ids, 0, 1, &buffer);

            if (buffer != Qundef && !RB_TYPE_P(buffer, T_STRING))
                rb_raise(rb_eTypeError, "buffer must be String, not %s", rb_obj_classname(buffer));
        }
        if (buffer)
            res = buffer;
        else
            res = rb_str_buf_new(0);

        idx = 0;

    #define TOO_FEW (rb_raise(rb_eArgError, toofew), 0)
    #define MORE_ITEM (idx < RARRAY_LEN(ary))
    #define THISFROM (MORE_ITEM ? RARRAY_AREF(ary, idx) : TOO_FEW)
    #define NEXTFROM (MORE_ITEM ? RARRAY_AREF(ary, idx++) : TOO_FEW)

        while (p < pend) {
            int explicit_endian = 0;
            if (RSTRING_PTR(fmt) + RSTRING_LEN(fmt) != pend) {
                rb_raise(rb_eRuntimeError, "format string modified");
            }
            type = *p++;           /* get data type */
    #ifdef NATINT_PACK
            natint = 0;
    #endif

            if (ISSPACE(type)) continue;
            if (type == '#') {
                while ((p < pend) && (*p != '\n')) {
                    p++;
                }
                continue;
            }

            {
              modifiers:
                switch (*p) {
                  case '_':
                  case '!':
                    if (strchr(natstr, type)) {
    #ifdef NATINT_PACK
                        natint = 1;
    #endif
                        p++;
                    }
                    else {
                        rb_raise(rb_eArgError, "'%c' allowed only after types %s", *p, natstr);
                    }
                    goto modifiers;

                  case '<':
                  case '>':
                    if (!strchr(endstr, type)) {
                        rb_raise(rb_eArgError, "'%c' allowed only after types %s", *p, endstr);
                    }
                    if (explicit_endian) {
                        rb_raise(rb_eRangeError, "Can't use both '<' and '>'");
                    }
                    explicit_endian = *p++;
                    goto modifiers;
                }
            }

            if (*p == '*') {       /* set data length */
                len = strchr("@Xxu", type) ? 0
                    : strchr("PMm", type) ? 1
                    : RARRAY_LEN(ary) - idx;
                p++;
            }
            else if (ISDIGIT(*p)) {
                errno = 0;
                len = STRTOUL(p, (char**)&p, 10);
                if (errno) {
                    rb_raise(rb_eRangeError, "pack length too big");
                }
            }
            else {
                len = 1;
            }

            switch (type) {
              case 'U':
                /* if encoding is US-ASCII, upgrade to UTF-8 */
                if (enc_info == 1) enc_info = 2;
                break;
              case 'm': case 'M': case 'u':
                /* keep US-ASCII (do nothing) */
                break;
              default:
                /* fall back to BINARY */
                enc_info = 0;
                break;
            }
            switch (type) {
              case 'A': case 'a': case 'Z':
              case 'B': case 'b':
              case 'H': case 'h':
                from = NEXTFROM;
                if (NIL_P(from)) {
                    ptr = "";
                    plen = 0;
                }
                else {
                    StringValue(from);
                    ptr = RSTRING_PTR(from);
                    plen = RSTRING_LEN(from);
                    OBJ_INFECT(res, from);
                }

                if (p[-1] == '*')
                    len = plen;

                switch (type) {
                  case 'a':                /* arbitrary binary string (null padded)  */
                  case 'A':         /* arbitrary binary string (ASCII space padded) */
                  case 'Z':         /* null terminated string  */
                    if (plen >= len) {
                        rb_str_buf_cat(res, ptr, len);
                        if (p[-1] == '*' && type == 'Z')
                            rb_str_buf_cat(res, nul10, 1);
                    }
                    else {
                        rb_str_buf_cat(res, ptr, plen);
                        len -= plen;
                        while (len >= 10) {
                            rb_str_buf_cat(res, (type == 'A')?spc10:nul10, 10);
                            len -= 10;
                        }
                        rb_str_buf_cat(res, (type == 'A')?spc10:nul10, len);
                    }
                    break;

    #define castchar(from) (char)((from) & 0xff)

                  case 'b':                /* bit string (ascending) */
                    {
                        int byte = 0;
                        long i, j = 0;

                        if (len > plen) {
                            j = (len - plen + 1)/2;
                            len = plen;
                        }
                        for (i=0; i++ < len; ptr++) {
                            if (*ptr & 1)
                                byte |= 128;
                            if (i & 7)
                                byte >>= 1;
                            else {
                                char c = castchar(byte);
                                rb_str_buf_cat(res, &c, 1);
                                byte = 0;
                            }
                        }
                        if (len & 7) {
                            char c;
                            byte >>= 7 - (len & 7);
                            c = castchar(byte);
                            rb_str_buf_cat(res, &c, 1);
                        }
                        len = j;
                        goto grow;
                    }
                    break;

                  case 'B':                /* bit string (descending) */
                    {
                        int byte = 0;
                        long i, j = 0;

                        if (len > plen) {
                            j = (len - plen + 1)/2;
                            len = plen;
                        }
                        for (i=0; i++ < len; ptr++) {
                            byte |= *ptr & 1;
                            if (i & 7)
                                byte <<= 1;
                            else {
                                char c = castchar(byte);
                                rb_str_buf_cat(res, &c, 1);
                                byte = 0;
                            }
                        }
                        if (len & 7) {
                            char c;
                            byte <<= 7 - (len & 7);
                            c = castchar(byte);
                            rb_str_buf_cat(res, &c, 1);
                        }
                        len = j;
                        goto grow;
                    }
                    break;

                  case 'h':                /* hex string (low nibble first) */
                    {
                        int byte = 0;
                        long i, j = 0;

                        if (len > plen) {
                            j = (len + 1) / 2 - (plen + 1) / 2;
                            len = plen;
                        }
                        for (i=0; i++ < len; ptr++) {
                            if (ISALPHA(*ptr))
                                byte |= (((*ptr & 15) + 9) & 15) << 4;
                            else
                                byte |= (*ptr & 15) << 4;
                            if (i & 1)
                                byte >>= 4;
                            else {
                                char c = castchar(byte);
                                rb_str_buf_cat(res, &c, 1);
                                byte = 0;
                            }
                        }
                        if (len & 1) {
                            char c = castchar(byte);
                            rb_str_buf_cat(res, &c, 1);
                        }
                        len = j;
                        goto grow;
                    }
                    break;

                  case 'H':                /* hex string (high nibble first) */
                    {
                        int byte = 0;
                        long i, j = 0;

                        if (len > plen) {
                            j = (len + 1) / 2 - (plen + 1) / 2;
                            len = plen;
                        }
                        for (i=0; i++ < len; ptr++) {
                            if (ISALPHA(*ptr))
                                byte |= ((*ptr & 15) + 9) & 15;
                            else
                                byte |= *ptr & 15;
                            if (i & 1)
                                byte <<= 4;
                            else {
                                char c = castchar(byte);
                                rb_str_buf_cat(res, &c, 1);
                                byte = 0;
                            }
                        }
                        if (len & 1) {
                            char c = castchar(byte);
                            rb_str_buf_cat(res, &c, 1);
                        }
                        len = j;
                        goto grow;
                    }
                    break;
                }
                break;

              case 'c':            /* signed char */
              case 'C':            /* unsigned char */
                integer_size = 1;
                bigendian_p = BIGENDIAN_P(); /* not effective */
                goto pack_integer;

              case 's':            /* s for int16_t, s! for signed short */
                integer_size = NATINT_LEN(short, 2);
                bigendian_p = BIGENDIAN_P();
                goto pack_integer;

              case 'S':            /* S for uint16_t, S! for unsigned short */
                integer_size = NATINT_LEN(short, 2);
                bigendian_p = BIGENDIAN_P();
                goto pack_integer;

              case 'i':            /* i and i! for signed int */
                integer_size = (int)sizeof(int);
                bigendian_p = BIGENDIAN_P();
                goto pack_integer;

              case 'I':            /* I and I! for unsigned int */
                integer_size = (int)sizeof(int);
                bigendian_p = BIGENDIAN_P();
                goto pack_integer;

              case 'l':            /* l for int32_t, l! for signed long */
                integer_size = NATINT_LEN(long, 4);
                bigendian_p = BIGENDIAN_P();
                goto pack_integer;

              case 'L':            /* L for uint32_t, L! for unsigned long */
                integer_size = NATINT_LEN(long, 4);
                bigendian_p = BIGENDIAN_P();
                goto pack_integer;

              case 'q':            /* q for int64_t, q! for signed long long */
                integer_size = NATINT_LEN_Q;
                bigendian_p = BIGENDIAN_P();
                goto pack_integer;

              case 'Q':            /* Q for uint64_t, Q! for unsigned long long */
                integer_size = NATINT_LEN_Q;
                bigendian_p = BIGENDIAN_P();
                goto pack_integer;

              case 'j':            /* j for intptr_t */
                integer_size = sizeof(intptr_t);
                bigendian_p = BIGENDIAN_P();
                goto pack_integer;

              case 'J':            /* J for uintptr_t */
                integer_size = sizeof(uintptr_t);
                bigendian_p = BIGENDIAN_P();
                goto pack_integer;

              case 'n':            /* 16 bit (2 bytes) integer (network byte-order)  */
                integer_size = 2;
                bigendian_p = 1;
                goto pack_integer;

              case 'N':            /* 32 bit (4 bytes) integer (network byte-order) */
                integer_size = 4;
                bigendian_p = 1;
                goto pack_integer;

              case 'v':            /* 16 bit (2 bytes) integer (VAX byte-order) */
                integer_size = 2;
                bigendian_p = 0;
                goto pack_integer;

              case 'V':            /* 32 bit (4 bytes) integer (VAX byte-order) */
                integer_size = 4;
                bigendian_p = 0;
                goto pack_integer;

              pack_integer:
                if (explicit_endian) {
                    bigendian_p = explicit_endian == '>';
                }
                if (integer_size > MAX_INTEGER_PACK_SIZE)
                    rb_bug("unexpected intger size for pack: %d", integer_size);
                while (len-- > 0) {
                    char intbuf[MAX_INTEGER_PACK_SIZE];

                    from = NEXTFROM;
                    rb_integer_pack(from, intbuf, integer_size, 1, 0,
                        INTEGER_PACK_2COMP |
                        (bigendian_p ? INTEGER_PACK_BIG_ENDIAN : INTEGER_PACK_LITTLE_ENDIAN));
                    rb_str_buf_cat(res, intbuf, integer_size);
                }
                break;

              case 'f':            /* single precision float in native format */
              case 'F':            /* ditto */
                while (len-- > 0) {
                    float f;

                    from = NEXTFROM;
                    f = VALUE_to_float(from);
                    rb_str_buf_cat(res, (char*)&f, sizeof(float));
                }
                break;

              case 'e':            /* single precision float in VAX byte-order */
                while (len-- > 0) {
                    FLOAT_CONVWITH(tmp);

                    from = NEXTFROM;
                    tmp.f = VALUE_to_float(from);
                    HTOVF(tmp);
                    rb_str_buf_cat(res, tmp.buf, sizeof(float));
                }
                break;

              case 'E':            /* double precision float in VAX byte-order */
                while (len-- > 0) {
                    DOUBLE_CONVWITH(tmp);
                    from = NEXTFROM;
                    tmp.d = RFLOAT_VALUE(rb_to_float(from));
                    HTOVD(tmp);
                    rb_str_buf_cat(res, tmp.buf, sizeof(double));
                }
                break;

              case 'd':            /* double precision float in native format */
              case 'D':            /* ditto */
                while (len-- > 0) {
                    double d;

                    from = NEXTFROM;
                    d = RFLOAT_VALUE(rb_to_float(from));
                    rb_str_buf_cat(res, (char*)&d, sizeof(double));
                }
                break;

              case 'g':            /* single precision float in network byte-order */
                while (len-- > 0) {
                    FLOAT_CONVWITH(tmp);
                    from = NEXTFROM;
                    tmp.f = VALUE_to_float(from);
                    HTONF(tmp);
                    rb_str_buf_cat(res, tmp.buf, sizeof(float));
                }
                break;

              case 'G':            /* double precision float in network byte-order */
                while (len-- > 0) {
                    DOUBLE_CONVWITH(tmp);

                    from = NEXTFROM;
                    tmp.d = RFLOAT_VALUE(rb_to_float(from));
                    HTOND(tmp);
                    rb_str_buf_cat(res, tmp.buf, sizeof(double));
                }
                break;

              case 'x':            /* null byte */
              grow:
                while (len >= 10) {
                    rb_str_buf_cat(res, nul10, 10);
                    len -= 10;
                }
                rb_str_buf_cat(res, nul10, len);
                break;

              case 'X':            /* back up byte */
              shrink:
                plen = RSTRING_LEN(res);
                if (plen < len)
                    rb_raise(rb_eArgError, "X outside of string");
                rb_str_set_len(res, plen - len);
                break;

              case '@':            /* null fill to absolute position */
                len -= RSTRING_LEN(res);
                if (len > 0) goto grow;
                len = -len;
                if (len > 0) goto shrink;
                break;

              case '%':
                rb_raise(rb_eArgError, "%% is not supported");
                break;

              case 'U':            /* Unicode character */
                while (len-- > 0) {
                    SIGNED_VALUE l;
                    char buf[8];
                    int le;

                    from = NEXTFROM;
                    from = rb_to_int(from);
                    l = NUM2LONG(from);
                    if (l < 0) {
                        rb_raise(rb_eRangeError, "pack(U): value out of range");
                    }
                    le = rb_uv_to_utf8(buf, l);
                    rb_str_buf_cat(res, (char*)buf, le);
                }
                break;

              case 'u':            /* uuencoded string */
              case 'm':            /* base64 encoded string */
                from = NEXTFROM;
                StringValue(from);
                ptr = RSTRING_PTR(from);
                plen = RSTRING_LEN(from);
                OBJ_INFECT(res, from);

                if (len == 0 && type == 'm') {
                    encodes(res, ptr, plen, type, 0);
                    ptr += plen;
                    break;
                }
                if (len <= 2)
                    len = 45;
                else if (len > 63 && type == 'u')
                    len = 63;
                else
                    len = len / 3 * 3;
                while (plen > 0) {
                    long todo;

                    if (plen > len)
                        todo = len;
                    else
                        todo = plen;
                    encodes(res, ptr, todo, type, 1);
                    plen -= todo;
                    ptr += todo;
                }
                break;

              case 'M':            /* quoted-printable encoded string */
                from = rb_obj_as_string(NEXTFROM);
                OBJ_INFECT(res, from);
                if (len <= 1)
                    len = 72;
                qpencode(res, from, len);
                break;

              case 'P':            /* pointer to packed byte string */
                from = THISFROM;
                if (!NIL_P(from)) {
                    StringValue(from);
                    if (RSTRING_LEN(from) < len) {
                        rb_raise(rb_eArgError, "too short buffer for P(%ld for %ld)",
                                 RSTRING_LEN(from), len);
                    }
                }
                len = 1;
                /* FALL THROUGH */
              case 'p':            /* pointer to string */
                while (len-- > 0) {
                    char *t;
                    from = NEXTFROM;
                    if (NIL_P(from)) {
                        t = 0;
                    }
                    else {
                        t = StringValuePtr(from);
                        OBJ_INFECT(res, from);
                        rb_obj_taint(from);
                    }
                    if (!associates) {
                        associates = rb_ary_new();
                    }
                    rb_ary_push(associates, from);
                    rb_str_buf_cat(res, (char*)&t, sizeof(char*));
                }
                break;

              case 'w':            /* BER compressed integer  */
                while (len-- > 0) {
                    VALUE buf = rb_str_new(0, 0);
                    size_t numbytes;
                    int sign;
                    char *cp;

                    from = NEXTFROM;
                    from = rb_to_int(from);
                    numbytes = rb_absint_numwords(from, 7, NULL);
                    if (numbytes == 0)
                        numbytes = 1;
                    buf = rb_str_new(NULL, numbytes);

                    sign = rb_integer_pack(from, RSTRING_PTR(buf), RSTRING_LEN(buf), 1, 1, INTEGER_PACK_BIG_ENDIAN);

                    if (sign < 0)
                        rb_raise(rb_eArgError, "can't compress negative numbers");
                    if (sign == 2)
                        rb_bug("buffer size problem?");

                    cp = RSTRING_PTR(buf);
                    while (1 < numbytes) {
                        *cp |= 0x80;
                        cp++;
                        numbytes--;
                    }

                    rb_str_buf_cat(res, RSTRING_PTR(buf), RSTRING_LEN(buf));
                }
                break;

              default: {
                unknown_directive("pack", type, fmt);
                break;
              }
            }
        }

        if (associates) {
            str_associate(res, associates);
        }
        OBJ_INFECT(res, fmt);
        switch (enc_info) {
          case 1:
            ENCODING_CODERANGE_SET(res, rb_usascii_encindex(), ENC_CODERANGE_7BIT);
            break;
          case 2:
            rb_enc_set_index(res, rb_utf8_encindex());
            break;
          default:
            /* do nothing, keep ASCII-8BIT */
            break;
        }
        return res;
    }

permutation {|p| block} → ary click to toggle source
permutation → Enumerator
permutation(n) {|p| block} → ary
permutation(n) → Enumerator

When invoked with a block, yield all permutations of length `n` of the elements of the array, then return the array itself.

If `n` is not specified, yield all permutations of all elements.

The implementation makes no guarantees about the order in which the permutations are yielded.

If no block is given, an `Enumerator` is returned instead.

Examples:

    a = [1, 2, 3]
    a.permutation.to_a    #=> [[1,2,3],[1,3,2],[2,1,3],[2,3,1],[3,1,2],[3,2,1]]
    a.permutation(1).to_a #=> [[1],[2],[3]]
    a.permutation(2).to_a #=> [[1,2],[1,3],[2,1],[2,3],[3,1],[3,2]]
    a.permutation(3).to_a #=> [[1,2,3],[1,3,2],[2,1,3],[2,3,1],[3,1,2],[3,2,1]]
    a.permutation(0).to_a #=> [[]] # one permutation of length 0
    a.permutation(4).to_a #=> []   # no permutations of length 4

    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 → obj or nil click to toggle source
pop(n) → new_ary

Removes the last element from `self` and returns it, or `nil` if the array is empty.

If a number `n` is given, returns an array of the last `n` elements (or less) just like `array.slice!(-n, n)` does. See also `Array#push` for the opposite effect.

    a = [ "a", "b", "c", "d" ]
    a.pop     #=> "d"
    a.pop(2)  #=> ["b", "c"]
    a         #=> ["a"]

    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(*args)
Alias for: unshift
product(other_ary, ...) → new_ary click to toggle source
product(other_ary, ...) {|p| block} → ary

Returns an array of all combinations of elements from all arrays.

The length of the returned array is the product of the length of `self` and the argument arrays.

If given a block, `product` will yield all combinations and return `self` instead.

    [1,2,3].product([4,5])     #=> [[1,4],[1,5],[2,4],[2,5],[3,4],[3,5]]
    [1,2].product([1,2])       #=> [[1,1],[1,2],[2,1],[2,2]]
    [1,2].product([3,4],[5,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]]
    [1,2].product()            #=> [[1],[2]]
    [1,2].product([])          #=> []

    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 = tmpary(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, FL_USER5);
                rb_yield(subarray);
                if (! FL_TEST(t0, FL_USER5)) {
                    rb_raise(rb_eRuntimeError, "product reentered");
                }
                else {
                    FL_UNSET(t0, FL_USER5);
                }
            }
            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:
        tmpary_discard(t0);
        ALLOCV_END(t1);

        return NIL_P(result) ? ary : result;
    }

push(obj, ...) → ary click to toggle source
append(obj, ...) → ary

Append — Pushes the given object(s) on to the end of this array. This expression returns the array itself, so several appends may be chained together. See also `Array#pop` for the opposite effect.

    a = [ "a", "b", "c" ]
    a.push("d", "e", "f")
            #=> ["a", "b", "c", "d", "e", "f"]
    [1, 2, 3].push(4).push(5)
            #=> [1, 2, 3, 4, 5]

    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) → element_ary or nil click to toggle source

Searches through the array whose elements are also arrays.

Compares `obj` with the second element of each contained array using `obj.==`.

Returns the first contained array that matches `obj`.

See also `Array#assoc`.

    a = [ [ 1, "one"], [2, "two"], [3, "three"], ["ii", "two"] ]
    a.rassoc("two")    #=> [2, "two"]
    a.rassoc("four")   #=> nil

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

        for (i = 0; i < RARRAY_LEN(ary); ++i) {
            v = 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 {|item| block } → new_ary click to toggle source
reject → Enumerator

Returns a new array containing the items in `self` for which the given block is not `true`. The ordering of non-rejected elements is maintained.

See also `Array#delete_if`

If no block is given, an `Enumerator` is returned instead.

    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! {|item| block} → ary or nil click to toggle source
reject! → Enumerator

Deletes every element of `self` for which the block evaluates to `true`, if no changes were made returns `nil`.

The array may not be changed instantly every time the block is called.

See also `Enumerable#reject` and `Array#delete_if`.

If no block is given, an `Enumerator` is returned instead.

    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) {|c| block} → ary click to toggle source
repeated_combination(n) → Enumerator

When invoked with a block, yields all repeated combinations of length `n` of elements from the array and then returns the array itself.

The implementation makes no guarantees about the order in which the repeated combinations are yielded.

If no block is given, an `Enumerator` is returned instead.

Examples:

    a = [1, 2, 3]
    a.repeated_combination(1).to_a  #=> [[1], [2], [3]]
    a.repeated_combination(2).to_a  #=> [[1,1],[1,2],[1,3],[2,2],[2,3],[3,3]]
    a.repeated_combination(3).to_a  #=> [[1,1,1],[1,1,2],[1,1,3],[1,2,2],[1,2,3],
                                    #    [1,3,3],[2,2,2],[2,2,3],[2,3,3],[3,3,3]]
    a.repeated_combination(4).to_a  #=> [[1,1,1,1],[1,1,1,2],[1,1,1,3],[1,1,2,2],[1,1,2,3],
                                    #    [1,1,3,3],[1,2,2,2],[1,2,2,3],[1,2,3,3],[1,3,3,3],
                                    #    [2,2,2,2],[2,2,2,3],[2,2,3,3],[2,3,3,3],[3,3,3,3]]
    a.repeated_combination(0).to_a  #=> [[]] # one combination of length 0

    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) {|p| block} → ary click to toggle source
repeated_permutation(n) → Enumerator

When invoked with a block, yield all repeated permutations of length `n` of the elements of the array, then return the array itself.

The implementation makes no guarantees about the order in which the repeated permutations are yielded.

If no block is given, an `Enumerator` is returned instead.

Examples:

    a = [1, 2]
    a.repeated_permutation(1).to_a  #=> [[1], [2]]
    a.repeated_permutation(2).to_a  #=> [[1,1],[1,2],[2,1],[2,2]]
    a.repeated_permutation(3).to_a  #=> [[1,1,1],[1,1,2],[1,2,1],[1,2,2],
                                    #    [2,1,1],[2,1,2],[2,2,1],[2,2,2]]
    a.repeated_permutation(0).to_a  #=> [[]] # one permutation of length 0

    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_ary) → ary click to toggle source

Replaces the contents of `self` with the contents of `other_ary`, truncating or expanding if necessary.

    a = [ "a", "b", "c", "d", "e" ]
    a.replace([ "x", "y", "z" ])   #=> ["x", "y", "z"]
    a                              #=> ["x", "y", "z"]

    VALUE
    rb_ary_replace(VALUE copy, VALUE orig)
    {
        rb_ary_modify_check(copy);
        orig = to_ary(orig);
        if (copy == orig) return copy;

        if (RARRAY_LEN(orig) <= RARRAY_EMBED_LEN_MAX) {
            VALUE shared = 0;

            if (ARY_OWNS_HEAP_P(copy)) {
                ary_heap_free(copy);
            }
            else if (ARY_SHARED_P(copy)) {
                shared = ARY_SHARED(copy);
                FL_UNSET_SHARED(copy);
            }
            FL_SET_EMBED(copy);
            ary_memcpy(copy, 0, RARRAY_LEN(orig), RARRAY_CONST_PTR_TRANSIENT(orig));
            if (shared) {
                rb_ary_decrement_share(shared);
            }
            ARY_SET_LEN(copy, RARRAY_LEN(orig));
        }
        else {
            VALUE shared = ary_make_shared(orig);
            if (ARY_OWNS_HEAP_P(copy)) {
                ary_heap_free(copy);
            }
            else {
                rb_ary_unshare_safe(copy);
            }
            FL_UNSET_EMBED(copy);
            ARY_SET_PTR(copy, ARY_HEAP_PTR(orig));
            ARY_SET_LEN(copy, ARY_HEAP_LEN(orig));
            rb_ary_set_shared(copy, shared);
        }
        ary_verify(copy);
        return copy;
    }

reverse → new_ary click to toggle source

Returns a new array containing `self`'s elements in reverse order.

    [ "a", "b", "c" ].reverse   #=> ["c", "b", "a"]
    [ 1 ].reverse               #=> [1]

    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_TRANSIENT(ary);
            VALUE *p2 = (VALUE *)RARRAY_CONST_PTR_TRANSIENT(dup) + len - 1;
            do *p2-- = *p1++; while (--len > 0);
        }
        ARY_SET_LEN(dup, RARRAY_LEN(ary));
        return dup;
    }

reverse! → ary click to toggle source

Reverses `self` in place.

    a = [ "a", "b", "c" ]
    a.reverse!       #=> ["c", "b", "a"]
    a                #=> ["c", "b", "a"]

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

reverse_each {|item| block} → ary click to toggle source
reverse_each → Enumerator

Same as `Array#each`, but traverses `self` in reverse order.

    a = [ "a", "b", "c" ]
    a.reverse_each {|x| print x, " " }

produces:

    c b a

    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(obj) → int or nil click to toggle source
rindex {|item| block} → int or nil
rindex → Enumerator

Returns the index of the last object in `self` `==` to `obj`.

If a block is given instead of an argument, returns the index of the first object for which the block returns `true`, starting from the last object.

Returns `nil` if no match is found.

See also `Array#index`.

If neither block nor argument is given, an `Enumerator` is returned instead.

    a = [ "a", "b", "b", "b", "c" ]
    a.rindex("b")             #=> 3
    a.rindex("z")             #=> nil
    a.rindex {|x| x == "b"}   #=> 3

    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);
            }
        }
        return Qnil;
    }

rotate(count=1) → new_ary click to toggle source

Returns a new array by rotating `self` so that the element at `count` is the first element of the new array.

If `count` is negative then it rotates in the opposite direction, starting from the end of `self` where `-1` is the last element.

    a = [ "a", "b", "c", "d" ]
    a.rotate         #=> ["b", "c", "d", "a"]
    a                #=> ["a", "b", "c", "d"]
    a.rotate(2)      #=> ["c", "d", "a", "b"]
    a.rotate(-3)     #=> ["b", "c", "d", "a"]

    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_TRANSIENT(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!(count=1) → ary click to toggle source

Rotates `self` in place so that the element at `count` comes first, and returns `self`.

If `count` is negative then it rotates in the opposite direction, starting from the end of the array where `-1` is the last element.

    a = [ "a", "b", "c", "d" ]
    a.rotate!        #=> ["b", "c", "d", "a"]
    a                #=> ["b", "c", "d", "a"]
    a.rotate!(2)     #=> ["d", "a", "b", "c"]
    a.rotate!(-3)    #=> ["a", "b", "c", "d"]

    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 → obj click to toggle source
sample(random: rng) → obj
sample(n) → new_ary
sample(n, random: rng) → new_ary

Choose a random element or `n` random elements from the array.

The elements are chosen by using random and unique indices into the array in order to ensure that an element doesn't repeat itself unless the array already contained duplicate elements.

If the array is empty the first form returns `nil` and the second form returns an empty array.

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

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

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

    static VALUE
    rb_ary_sample(int argc, VALUE *argv, VALUE ary)
    {
        VALUE nv, result;
        VALUE opts, randgen = rb_cRandom;
        long n, len, i, j, k, idx[10];
        long rnds[numberof(idx)];
        long memo_threshold;

        if (OPTHASH_GIVEN_P(opts)) {
            VALUE rnd;
            ID keyword_ids[1];

            keyword_ids[0] = id_random;
            rb_get_kwargs(opts, keyword_ids, 0, 1, &rnd);
            if (rnd != Qundef) {
                randgen = rnd;
            }
        }
        len = RARRAY_LEN(ary);
        if (rb_check_arity(argc, 0, 1) == 0) {
            if (len < 2)
                i = 0;
            else
                i = RAND_UPTO(len);

            return rb_ary_elt(ary, i);
        }
        nv = argv[0];
        n = NUM2LONG(nv);
        if (n < 0) rb_raise(rb_eArgError, "negative sample number");
        if (n > len) n = len;
        if (n <= numberof(idx)) {
            for (i = 0; i < n; ++i) {
                rnds[i] = RAND_UPTO(len - i);
            }
        }
        k = len;
        len = RARRAY_LEN(ary);
        if (len < k && n <= numberof(idx)) {
            for (i = 0; i < n; ++i) {
                if (rnds[i] >= len) return rb_ary_new_capa(0);
            }
        }
        if (n > len) n = len;
        switch (n) {
          case 0:
            return rb_ary_new_capa(0);
          case 1:
            i = rnds[0];
            return rb_ary_new_from_values(1, &RARRAY_AREF(ary, i));
          case 2:
            i = rnds[0];
            j = rnds[1];
            if (j >= i) j++;
            return rb_ary_new_from_args(2, RARRAY_AREF(ary, i), RARRAY_AREF(ary, j));
          case 3:
            i = rnds[0];
            j = rnds[1];
            k = rnds[2];
            {
                long l = j, g = i;
                if (j >= i) l = i, g = ++j;
                if (k >= l && (++k >= g)) ++k;
            }
            return rb_ary_new_from_args(3, RARRAY_AREF(ary, i), RARRAY_AREF(ary, j), RARRAY_AREF(ary, k));
        }
        memo_threshold =
            len < 2560 ? len / 128 :
            len < 5120 ? len / 64 :
            len < 10240 ? len / 32 :
            len / 16;
        if (n <= numberof(idx)) {
            long sorted[numberof(idx)];
            sorted[0] = idx[0] = rnds[0];
            for (i=1; i<n; i++) {
                k = rnds[i];
                for (j = 0; j < i; ++j) {
                    if (k < sorted[j]) break;
                    ++k;
                }
                memmove(&sorted[j+1], &sorted[j], sizeof(sorted[0])*(i-j));
                sorted[j] = idx[i] = k;
            }
            result = rb_ary_new_capa(n);
            RARRAY_PTR_USE_TRANSIENT(result, ptr_result, {
                for (i=0; i<n; i++) {
                    ptr_result[i] = RARRAY_AREF(ary, idx[i]);
                }
            });
        }
        else if (n <= memo_threshold / 2) {
            long max_idx = 0;
    #undef RUBY_UNTYPED_DATA_WARNING
    #define RUBY_UNTYPED_DATA_WARNING 0
            VALUE vmemo = Data_Wrap_Struct(0, 0, st_free_table, 0);
            st_table *memo = st_init_numtable_with_size(n);
            DATA_PTR(vmemo) = memo;
            result = rb_ary_new_capa(n);
            RARRAY_PTR_USE(result, ptr_result, {
                for (i=0; i<n; i++) {
                    long r = RAND_UPTO(len-i) + i;
                    ptr_result[i] = r;
                    if (r > max_idx) max_idx = r;
                }
                len = RARRAY_LEN(ary);
                if (len <= max_idx) n = 0;
                else if (n > len) n = len;
                RARRAY_PTR_USE_TRANSIENT(ary, ptr_ary, {
                    for (i=0; i<n; i++) {
                        long j2 = j = ptr_result[i];
                        long i2 = i;
                        st_data_t value;
                        if (st_lookup(memo, (st_data_t)i, &value)) i2 = (long)value;
                        if (st_lookup(memo, (st_data_t)j, &value)) j2 = (long)value;
                        st_insert(memo, (st_data_t)j, (st_data_t)i2);
                        ptr_result[i] = ptr_ary[j2];
                    }
                });
            });
            DATA_PTR(vmemo) = 0;
            st_free_table(memo);
        }
        else {
            result = rb_ary_dup(ary);
            RBASIC_CLEAR_CLASS(result);
            RB_GC_GUARD(ary);
            RARRAY_PTR_USE(result, ptr_result, {
                for (i=0; i<n; i++) {
                    j = RAND_UPTO(len-i) + i;
                    nv = ptr_result[j];
                    ptr_result[j] = ptr_result[i];
                    ptr_result[i] = nv;
                }
            });
            RBASIC_SET_CLASS_RAW(result, rb_cArray);
        }
        ARY_SET_LEN(result, n);

        return result;
    }

select {|item| block} → new_ary click to toggle source
select → Enumerator

Returns a new array containing all elements of `ary` for which the given `block` returns a true value.

If no block is given, an `Enumerator` is returned instead.

    [1,2,3,4,5].select {|num| num.even? }     #=> [2, 4]

    a = %w[ a b c d e f ]
    a.select {|v| v =~ /[aeiou]/ }    #=> ["a", "e"]

See also `Enumerable#select`.

`Array#filter` is an alias for `Array#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;
    }

select! {|item| block } → ary or nil click to toggle source
select! → Enumerator

Invokes the given block passing in successive elements from `self`, deleting elements for which the block returns a `false` value.

The array may not be changed instantly every time the block is called.

If changes were made, it will return `self`, otherwise it returns `nil`.

If no block is given, an `Enumerator` is returned instead.

See also `Array#keep_if`.

`Array#filter!` is an alias for `Array#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);
    }

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 228
    def shelljoin
      Shellwords.join(self)
    end

shift → obj or nil click to toggle source
shift(n) → new_ary

Removes the first element of `self` and returns it (shifting all other elements down by one). Returns `nil` if the array is empty.

If a number `n` is given, returns an array of the first `n` elements (or less) just like `array.slice!(0, n)` does. With `ary` containing only the remainder elements, not including what was shifted to `new_ary`. See also `Array#unshift` for the opposite effect.

    args = [ "-m", "-q", "filename" ]
    args.shift     #=> "-m"
    args           #=> ["-q", "filename"]

    args = [ "-m", "-q", "filename" ]
    args.shift(2)  #=> ["-m", "-q"]
    args           #=> ["filename"]

    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 → new_ary click to toggle source
shuffle(random: rng) → new_ary

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 `rng` argument will be used as the random number generator.

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

    static VALUE
    rb_ary_shuffle(int argc, VALUE *argv, VALUE ary)
    {
        ary = rb_ary_dup(ary);
        rb_ary_shuffle_bang(argc, argv, ary);
        return ary;
    }

shuffle! → ary click to toggle source
shuffle!(random: rng) → ary

Shuffles elements in `self` in place.

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

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

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

    static VALUE
    rb_ary_shuffle_bang(int argc, VALUE *argv, VALUE ary)
    {
        VALUE opts, randgen = rb_cRandom;
        long i, len;

        if (OPTHASH_GIVEN_P(opts)) {
            VALUE rnd;
            ID keyword_ids[1];

            keyword_ids[0] = id_random;
            rb_get_kwargs(opts, keyword_ids, 0, 1, &rnd);
            if (rnd != Qundef) {
                randgen = rnd;
            }
        }
        rb_check_arity(argc, 0, 0);
        rb_ary_modify(ary);
        i = len = RARRAY_LEN(ary);
        RARRAY_PTR_USE(ary, ptr, {
            while (i) {
                long j = RAND_UPTO(i);
                VALUE tmp;
                if (len != RARRAY_LEN(ary) || ptr != RARRAY_CONST_PTR_TRANSIENT(ary)) {
                    rb_raise(rb_eRuntimeError, "modified during shuffle");
                }
                tmp = ptr[--i];
                ptr[i] = ptr[j];
                ptr[j] = tmp;
            }
        }); /* WB: no new reference */
        return ary;
    }

size()
Alias for: length
slice(index) → obj or nil click to toggle source
slice(start, length) → new_ary or nil
slice(range) → new_ary or nil

Element Reference — Returns the element at `index`, or returns a subarray starting at the `start` index and continuing for `length` elements, or returns a subarray specified by `range` of indices.

Negative indices count backward from the end of the array (-1 is the last element). For `start` and `range` cases the starting index is just before an element. Additionally, an empty array is returned when the starting index for an element range is at the end of the array.

Returns `nil` if the index (or starting index) are out of range.

    a = [ "a", "b", "c", "d", "e" ]
    a[2] +  a[0] + a[1]    #=> "cab"
    a[6]                   #=> nil
    a[1, 2]                #=> [ "b", "c" ]
    a[1..3]                #=> [ "b", "c", "d" ]
    a[4..7]                #=> [ "e" ]
    a[6..10]               #=> nil
    a[-3, 3]               #=> [ "c", "d", "e" ]
    # special cases
    a[5]                   #=> nil
    a[6, 1]                #=> nil
    a[5, 1]                #=> []
    a[5..10]               #=> []

    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]);
    }

slice!(index) → obj or nil click to toggle source
slice!(start, length) → new_ary or nil
slice!(range) → new_ary or nil

Deletes the element(s) given by an `index` (optionally up to `length` elements) or by a `range`.

Returns the deleted object (or objects), or `nil` if the `index` is out of range.

    a = [ "a", "b", "c" ]
    a.slice!(1)     #=> "b"
    a               #=> ["a", "c"]
    a.slice!(-1)    #=> "c"
    a               #=> ["a"]
    a.slice!(100)   #=> nil
    a               #=> ["a"]

    static VALUE
    rb_ary_slice_bang(int argc, VALUE *argv, VALUE ary)
    {
        VALUE arg1, arg2;
        long pos, len, orig_len;

        rb_ary_modify_check(ary);
        if (argc == 2) {
            pos = NUM2LONG(argv[0]);
            len = NUM2LONG(argv[1]);
          delete_pos_len:
            if (len < 0) return Qnil;
            orig_len = RARRAY_LEN(ary);
            if (pos < 0) {
                pos += orig_len;
                if (pos < 0) return Qnil;
            }
            else if (orig_len < pos) return Qnil;
            if (orig_len < pos + len) {
                len = orig_len - pos;
            }
            if (len == 0) return rb_ary_new2(0);
            arg2 = rb_ary_new4(len, RARRAY_CONST_PTR_TRANSIENT(ary)+pos);
            RBASIC_SET_CLASS(arg2, rb_obj_class(ary));
            rb_ary_splice(ary, pos, len, 0, 0);
            return arg2;
        }

        rb_check_arity(argc, 1, 2);
        arg1 = argv[0];

        if (!FIXNUM_P(arg1)) {
            switch (rb_range_beg_len(arg1, &pos, &len, RARRAY_LEN(ary), 0)) {
              case Qtrue:
                /* valid range */
                goto delete_pos_len;
              case Qnil:
                /* invalid range */
                return Qnil;
              default:
                /* not a range */
                break;
            }
        }

        return rb_ary_delete_at(ary, NUM2LONG(arg1));
    }

sort → new_ary click to toggle source
sort {|a, b| block} → new_ary

Returns a new array created by sorting `self`.

Comparisons for the sort will be done using the `<=>` operator or using an optional code block.

The block must implement a comparison between `a` and `b` and return an integer less than 0 when `b` follows `a`, `0` when `a` and `b` are equivalent, or an integer greater than 0 when `a` follows `b`.

The result is not guaranteed to be stable. When the comparison of two elements returns `0`, the order of the elements is unpredictable.

    ary = [ "d", "a", "e", "c", "b" ]
    ary.sort                     #=> ["a", "b", "c", "d", "e"]
    ary.sort {|a, b| b <=> a}    #=> ["e", "d", "c", "b", "a"]

See also `Enumerable#sort_by`.

    VALUE
    rb_ary_sort(VALUE ary)
    {
        ary = rb_ary_dup(ary);
        rb_ary_sort_bang(ary);
        return ary;
    }

sort! → ary click to toggle source
sort! {|a, b| block} → ary

Sorts `self` in place.

Comparisons for the sort will be done using the `<=>` operator or using an optional code block.

The block must implement a comparison between `a` and `b` and return an integer less than 0 when `b` follows `a`, `0` when `a` and `b` are equivalent, or an integer greater than 0 when `a` follows `b`.

The result is not guaranteed to be stable. When the comparison of two elements returns `0`, the order of the elements is unpredictable.

    ary = [ "d", "a", "e", "c", "b" ]
    ary.sort!                     #=> ["a", "b", "c", "d", "e"]
    ary.sort! {|a, b| b <=> a}    #=> ["e", "d", "c", "b", "a"]

See also `Enumerable#sort_by`.

    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.cmp_opt.opt_methods = 0;
            data.cmp_opt.opt_inited = 0;
            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! {|obj| block} → ary click to toggle source
sort_by! → Enumerator

Sorts `self` in place using a set of keys generated by mapping the values in `self` through the given block.

The result is not guaranteed to be stable. When two keys are equal, the order of the corresponding elements is unpredictable.

If no block is given, an `Enumerator` is returned instead.

See also `Enumerable#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) → number click to toggle source
sum(init=0) {|e| expr } → number

Returns the sum of elements. For example, [e1, e2, e3].sum returns init + e1 + e2 + e3.

If a block is given, the block is applied to each element before addition.

If ary is empty, it returns init.

    [].sum                             #=> 0
    [].sum(0.0)                        #=> 0.0
    [1, 2, 3].sum                      #=> 6
    [3, 5.5].sum                       #=> 8.5
    [2.5, 3.0].sum(0.0) {|e| e * e }   #=> 15.25
    [Object.new].sum                   #=> TypeError

The (arithmetic) mean value of an array can be obtained as follows.

    mean = ary.sum(0.0) / ary.length

This method can be used for non-numeric objects by explicit init argument.

    ["a", "b", "c"].sum("")            #=> "abc"
    [[1], [[2]], [3]].sum([])          #=> [1, [2], 3]

However, `Array#join` and `Array#flatten` is faster than `Array#sum` for array of strings and array of arrays.

    ["a", "b", "c"].join               #=> "abc"
    [[1], [[2]], [3]].flatten(1)       #=> [1, [2], 3]

`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;
        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_TYPE_P(e, T_BIGNUM))
                v = rb_big_plus(e, v);
            else if (RB_TYPE_P(e, T_RATIONAL)) {
                if (r == Qundef)
                    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 http://link.springer.com/article/10.1007/s00607-005-0139-x
             */
            double f, c;

            f = NUM2DBL(v);
            c = 0.0;
            goto has_float_value;
            for (; i < RARRAY_LEN(ary); i++) {
                double x, t;
                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_TYPE_P(e, T_BIGNUM))
                    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;
        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_ary click to toggle source

Returns first `n` elements from the array.

If a negative number is given, raises an `ArgumentError`.

See also `Array#drop`

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

    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 {|obj| block} → new_ary click to toggle source
take_while → Enumerator

Passes elements to the block until the block returns `nil` or `false`, then stops iterating and returns an array of all prior elements.

If no block is given, an `Enumerator` is returned instead.

See also `Array#drop_while`

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

    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 → ary click to toggle source

Returns `self`.

If called on a subclass of `Array`, converts the receiver to an `Array` object.

    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 → ary click to toggle source

Returns `self`.

    static VALUE
    rb_ary_to_ary_m(VALUE ary)
    {
        return ary;
    }

to_h → hash click to toggle source
to_h { block } → hash

Returns the result of interpreting ary as an array of `[key, value]` pairs.

    [[:foo, :bar], [1, 2]].to_h
      # => {:foo => :bar, 1 => 2}

If a block is given, the results of the block on each element of the array will be used as pairs.

    ["foo", "bar"].to_h {|s| [s.ord, s]}
      # => {102=>"foo", 98=>"bar"}

    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_ary click to toggle source

Assumes that `self` is an array of arrays and transposes the rows and columns.

    a = [[1,2], [3,4], [5,6]]
    a.transpose   #=> [[1, 3, 5], [2, 4, 6]]

If the length of the subarrays don't match, an `IndexError` is raised.

    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_ary1, other_ary2, ...) → ary click to toggle source

`Set` Union — Returns a new array by joining `other_ary`s with `self`, excluding any duplicates and preserving the order from the given arrays.

It compares elements using their `hash` and `eql?` methods for efficiency.

    [ "a", "b", "c" ].union( [ "c", "d", "a" ] )    #=> [ "a", "b", "c", "d" ]
    [ "a" ].union( ["e", "b"], ["a", "c", "b"] )    #=> [ "a", "e", "b", "c" ]
    [ "a" ].union #=> [ "a" ]

See also Array#|.

    static VALUE
    rb_ary_union_multi(int argc, VALUE *argv, VALUE ary)
    {
        int i;
        long sum;
        VALUE hash, ary_union;

        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) {
            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]);

        ary_union = rb_hash_values(hash);
        ary_recycle_hash(hash);
        return ary_union;
    }

uniq → new_ary click to toggle source
uniq {|item| ...} → new_ary

Returns a new array by removing duplicate values in `self`.

If a block is given, it will use the return value of the block for comparison.

It compares values using their `hash` and `eql?` methods for efficiency.

`self` is traversed in order, and the first occurrence is kept.

    a = [ "a", "a", "b", "b", "c" ]
    a.uniq   # => ["a", "b", "c"]

    b = [["student","sam"], ["student","george"], ["teacher","matz"]]
    b.uniq {|s| s.first}   # => [["student", "sam"], ["teacher", "matz"]]

    static VALUE
    rb_ary_uniq(VALUE ary)
    {
        VALUE hash, uniq;

        if (RARRAY_LEN(ary) <= 1)
            return rb_ary_dup(ary);
        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);
        }
        RBASIC_SET_CLASS(uniq, rb_obj_class(ary));
        ary_recycle_hash(hash);

        return uniq;
    }

uniq! → ary or nil click to toggle source
uniq! {|item| ...} → ary or nil

Removes duplicate elements from `self`.

If a block is given, it will use the return value of the block for comparison.

It compares values using their `hash` and `eql?` methods for efficiency.

`self` is traversed in order, and the first occurrence is kept.

Returns `nil` if no changes are made (that is, no duplicates are found).

    a = [ "a", "a", "b", "b", "c" ]
    a.uniq!   # => ["a", "b", "c"]

    b = [ "a", "b", "c" ]
    b.uniq!   # => nil

    c = [["student","sam"], ["student","george"], ["teacher","matz"]]
    c.uniq! {|s| s.first}   # => [["student", "sam"], ["teacher", "matz"]]

    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);
        ary_recycle_hash(hash);

        return ary;
    }

unshift(obj, ...) → ary click to toggle source
prepend(obj, ...) → ary

Prepends objects to the front of `self`, moving other elements upwards. See also `Array#shift` for the opposite effect.

    a = [ "b", "c", "d" ]
    a.unshift("a")   #=> ["a", "b", "c", "d"]
    a.unshift(1, 2)  #=> [ 1, 2, "a", "b", "c", "d"]

    static 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(selector, ...) → new_ary click to toggle source

Returns an array containing the elements in `self` corresponding to the given `selector`(s).

The selectors may be either integer indices or ranges.

See also `Array#select`.

    a = %w{ a b c d e f }
    a.values_at(1, 3, 5)          # => ["b", "d", "f"]
    a.values_at(1, 3, 5, 7)       # => ["b", "d", "f", nil]
    a.values_at(-1, -2, -2, -7)   # => ["f", "e", "e", nil]
    a.values_at(4..6, 3...6)      # => ["e", "f", nil, "d", "e", "f"]

    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(arg, ...) → new_ary click to toggle source
zip(arg, ...) {|arr| block} → nil

Converts any arguments to arrays, then merges elements of `self` with corresponding elements from each argument.

This generates a sequence of `ary.size` n-element arrays, where n is one more than the count of arguments.

If the size of any argument is less than the size of the initial array, `nil` values are supplied.

If a block is given, it is invoked for each output `array`, otherwise an array of arrays is returned.

    a = [ 4, 5, 6 ]
    b = [ 7, 8, 9 ]
    [1, 2, 3].zip(a, b)   #=> [[1, 4, 7], [2, 5, 8], [3, 6, 9]]
    [1, 2].zip(a, b)      #=> [[1, 4, 7], [2, 5, 8]]
    a.zip([1, 2], [8])    #=> [[4, 1, 8], [5, 2, nil], [6, nil, nil]]

    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;
    }

ary | other_ary → new_ary click to toggle source

`Set` Union — Returns a new array by joining `ary` with `other_ary`, excluding any duplicates and preserving the order from the given arrays.

It compares elements using their `hash` and `eql?` methods for efficiency.

    [ "a", "b", "c" ] | [ "c", "d", "a" ]    #=> [ "a", "b", "c", "d" ]
    [ "c", "d", "a" ] | [ "a", "b", "c" ]    #=> [ "c", "d", "a", "b" ]

See also `Array#union`.

    static VALUE
    rb_ary_or(VALUE ary1, VALUE ary2)
    {
        VALUE hash, ary3;

        ary2 = to_ary(ary2);
        if (RARRAY_LEN(ary1) + RARRAY_LEN(ary2) <= SMALL_ARRAY_LEN) {
            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);

        ary3 = rb_hash_values(hash);
        ary_recycle_hash(hash);
        return ary3;
    }