Class: Array

Inherits:
Object show all
Includes:
Enumerable
Defined in:
array.c

Overview

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.

Class Method Summary collapse

Instance Method Summary collapse

Methods included from Enumerable

#all?, #any?, #chunk, #collect_concat, #detect, #each_cons, #each_entry, #each_slice, #each_with_index, #each_with_object, #entries, #find, #find_all, #flat_map, #grep, #group_by, #inject, #max, #max_by, #member?, #min, #min_by, #minmax, #minmax_by, #none?, #one?, #partition, #reduce, #slice_before, #sort_by

Constructor Details

#new(size = 0, obj = nil) ⇒ Object #new(array) ⇒ Object #new(size) {|index| ... } ⇒ Object

Returns a new array. In the first form, the new array is empty. In the second it is created with size copies of obj (that is, size references to the same obj). The third form creates a copy of the array passed as a parameter (the array is generated by calling to_ary on the parameter). In the last form, an array of the given size is created. Each element in this array is calculated by passing the element's index to the given block and storing the return value.

Array.new
Array.new(2)
Array.new(5, "A")

# only one copy of the object is created
a = Array.new(2, Hash.new)
a[0]['cat'] = 'feline'
a
a[1]['cat'] = 'Felix'
a

# here multiple copies are created
a = Array.new(2) { Hash.new }
a[0]['cat'] = 'feline'
a

squares = Array.new(5) {|i| i*i}
squares

copy = Array.new(squares)

Overloads:




# File 'array.c'

/*
 *  call-seq:
 *     Array.new(size=0, obj=nil)
 *     Array.new(array)
 *     Array.new(size) {|index| block }
 *
 *  Returns a new array. In the first form, the new array is
 *  empty. In the second it is created with _size_ copies of _obj_
 *  (that is, _size_ references to the same
 *  _obj_). The third form creates a copy of the array
 *  passed as a parameter (the array is generated by calling
 *  to_ary  on the parameter). In the last form, an array
 *  of the given size is created. Each element in this array is
 *  calculated by passing the element's index to the given block and
 *  storing the return value.
 *
 *     Array.new
 *     Array.new(2)
 *     Array.new(5, "A")
 *
 *     # only one copy of the object is created
 *     a = Array.new(2, Hash.new)
 *     a[0]['cat'] = 'feline'
 *     a
 *     a[1]['cat'] = 'Felix'
 *     a
 *
 *     # here multiple copies are created
 *     a = Array.new(2) { Hash.new }
 *     a[0]['cat'] = 'feline'
 *     a
 *
 *     squares = Array.new(5) {|i| i*i}
 *     squares
 *
 *     copy = Array.new(squares)
 */

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) && RARRAY_PTR(ary)) {
        xfree(RARRAY_PTR(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);
    if (len < 0) {
    rb_raise(rb_eArgError, "negative array size");
    }
    if (len > ARY_MAX_SIZE) {
    rb_raise(rb_eArgError, "array size too big");
    }
    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 {
    memfill(RARRAY_PTR(ary), len, val);
    ARY_SET_LEN(ary, len);
    }
    return ary;
}

Class Method Details

.[] ⇒ Object

Returns a new array populated with the given objects.

Array.[]( 1, 'a', /^A/ )
Array[ 1, 'a', /^A/ ]
[ 1, 'a', /^A/ ]




# File 'array.c'

/*
* Returns a new array populated with the given objects.
*
*   Array.[]( 1, 'a', /^A/ )
*   Array[ 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) {
        MEMCPY(RARRAY_PTR(ary), argv, VALUE, argc);
        ARY_SET_LEN(ary, argc);
    }

    return ary;
}

.try_convert(obj) ⇒ Array?

Try to convert obj into an array, using to_ary method. Returns 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

Returns:




# File 'array.c'

/*
 *  call-seq:
 *     Array.try_convert(obj) -> array or nil
 *
 *  Try to convert <i>obj</i> into an array, using +to_ary+ method.
 *  Returns converted array or +nil+ if <i>obj</i> 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);
}

Instance Method Details

#&(other_ary) ⇒ Object

Set Intersection---Returns a new array containing elements common to the two arrays, with no duplicates.

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




# File 'array.c'

/*
 *  call-seq:
 *     ary & other_ary      -> new_ary
 *
 *  Set Intersection---Returns a new array
 *  containing elements common to the two arrays, with no duplicates.
 *
 *     [ 1, 1, 3, 5 ] & [ 1, 2, 3 ]   #=> [ 1, 3 ]
 */


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

    ary2 = to_ary(ary2);
    ary3 = rb_ary_new2(RARRAY_LEN(ary1) < RARRAY_LEN(ary2) ?
        RARRAY_LEN(ary1) : RARRAY_LEN(ary2));
    hash = ary_make_hash(ary2);

    if (RHASH_EMPTY_P(hash))
        return ary3;

    for (i=0; i<RARRAY_LEN(ary1); i++) {
    v = vv = rb_ary_elt(ary1, i);
    if (st_delete(RHASH_TBL(hash), (st_data_t*)&vv, 0)) {
        rb_ary_push(ary3, v);
    }
    }
    ary_recycle_hash(hash);

    return ary3;
}

#*(int) ⇒ Object #*(str) ⇒ Object

Repetition---With a String argument, equivalent to self.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"




# File 'array.c'

/*
 *  call-seq:
 *     ary * int     -> new_ary
 *     ary * str     -> new_string
 *
 *  Repetition---With a String argument, equivalent to
 *  self.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, *ptr, *ptr2;
    long i, 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_PTR(ary);
    ptr2 = RARRAY_PTR(ary2);
    t = RARRAY_LEN(ary);
    for (i=0; i<len; i+=t) {
    MEMCPY(ptr2+i, ptr, VALUE, t);
    }
  out:
    OBJ_INFECT(ary2, ary);

    return ary2;
}

#+(other_ary) ⇒ Object

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 ]




# File 'array.c'

/*
 *  call-seq:
 *     ary + other_ary   -> new_ary
 *
 *  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 ]
 */

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

    y = to_ary(y);
    len = RARRAY_LEN(x) + RARRAY_LEN(y);
    z = rb_ary_new2(len);
    MEMCPY(RARRAY_PTR(z), RARRAY_PTR(x), VALUE, RARRAY_LEN(x));
    MEMCPY(RARRAY_PTR(z) + RARRAY_LEN(x), RARRAY_PTR(y), VALUE, RARRAY_LEN(y));
    ARY_SET_LEN(z, len);
    return z;
}

#-(other_ary) ⇒ Object

Array Difference---Returns a new array that is a copy of the original array, removing any items that also appear in other_ary. (If you need set-like behavior, see the library class Set.)

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




# File 'array.c'

/*
 *  call-seq:
 *     ary - other_ary    -> new_ary
 *
 *  Array Difference---Returns a new array that is a copy of
 *  the original array, removing any items that also appear in
 *  <i>other_ary</i>. (If you need set-like behavior, see the
 *  library class Set.)
 *
 *     [ 1, 1, 2, 2, 3, 3, 4, 5 ] - [ 1, 2, 4 ]  #=>  [ 3, 3, 5 ]
 */

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

    hash = ary_make_hash(to_ary(ary2));
    ary3 = rb_ary_new();

    for (i=0; i<RARRAY_LEN(ary1); i++) {
    if (st_lookup(RHASH_TBL(hash), RARRAY_PTR(ary1)[i], 0)) continue;
    rb_ary_push(ary3, rb_ary_elt(ary1, i));
    }
    ary_recycle_hash(hash);
    return ary3;
}

#<<(obj) ⇒ Object

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.

[ 1, 2 ] << "c" << "d" << [ 3, 4 ]
        #=>  [ 1, 2, "c", "d", [ 3, 4 ] ]




# File 'array.c'

/*
 *  call-seq:
 *     ary << obj            -> ary
 *
 *  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.
 *
 *     [ 1, 2 ] << "c" << "d" << [ 3, 4 ]
 *             #=>  [ 1, 2, "c", "d", [ 3, 4 ] ]
 *
 */

VALUE
rb_ary_push(VALUE ary, VALUE item)
{
    rb_ary_modify(ary);
    return rb_ary_push_1(ary, item);
}

#<=>(other_ary) ⇒ -1, ...

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 <=>). If any value isn't equal, then that inequality is the return value. If all the values found are equal, then the return 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.

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

Returns:

  • (-1, 0, +1, nil) 



# File 'array.c'

/*
 *  call-seq:
 *     ary <=> other_ary   ->  -1, 0, +1 or nil
 *
 *  Comparison---Returns an integer (-1, 0,
 *  or +1) if this array is less than, equal to, or greater than
 *  <i>other_ary</i>.  Each object in each array is compared
 *  (using <=>). If any value isn't
 *  equal, then that inequality is the return value. If all the
 *  values found are equal, then the return is based on a
 *  comparison of the array lengths.  Thus, two arrays are
 *  ``equal'' according to <code>Array#<=></code> 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.
 *
 *     [ "a", "a", "c" ]    <=> [ "a", "b", "c" ]   #=> -1
 *     [ 1, 2, 3, 4, 5, 6 ] <=> [ 1, 2 ]            #=> +1
 *
 */

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

#==(other_ary) ⇒ Object

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 the other array.

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




# File 'array.c'

/*
 *  call-seq:
 *     ary == other_ary   ->   bool
 *
 *  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 the other array.
 *
 *     [ "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 (TYPE(ary2) != T_ARRAY) {
    if (!rb_respond_to(ary2, rb_intern("to_ary"))) {
        return Qfalse;
    }
    return rb_equal(ary2, ary1);
    }
    if (RARRAY_LEN(ary1) != RARRAY_LEN(ary2)) return Qfalse;
    return rb_exec_recursive_paired(recursive_equal, ary1, ary2, ary2);
}

#[](index) ⇒ Object? #[](start, length) ⇒ nil #[](range) ⇒ nil #slice(index) ⇒ Object? #slice(start, length) ⇒ nil #slice(range) ⇒ nil

Element Reference---Returns the element at index, or returns a subarray starting at start and continuing for length elements, or returns a subarray specified by range. Negative indices count backward from the end of the array (-1 is the last element). Returns nil if the index (or starting index) are out of range.

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[5, 1]                #=> []
a[5..10]               #=> []

Overloads:

  • #[](index) ⇒ Object?

    Returns:

  • #[](start, length) ⇒ nil

    Returns:

    • (nil)
  • #[](range) ⇒ nil

    Returns:

    • (nil)
  • #slice(index) ⇒ Object?

    Returns:

  • #slice(start, length) ⇒ nil

    Returns:

    • (nil)
  • #slice(range) ⇒ nil

    Returns:

    • (nil) 



# File 'array.c'

/*
 *  call-seq:
 *     ary[index]                -> obj     or nil
 *     ary[start, length]        -> new_ary or nil
 *     ary[range]                -> new_ary or nil
 *     ary.slice(index)          -> obj     or nil
 *     ary.slice(start, length)  -> new_ary or nil
 *     ary.slice(range)          -> new_ary or nil
 *
 *  Element Reference---Returns the element at _index_,
 *  or returns a subarray starting at _start_ and
 *  continuing for _length_ elements, or returns a subarray
 *  specified by _range_.
 *  Negative indices count backward from the end of the
 *  array (-1 is the last element). Returns +nil+ if the index
 *  (or starting index) are out of range.
 *
 *     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[5, 1]                #=> []
 *     a[5..10]               #=> []
 *
 */

VALUE
rb_ary_aref(int argc, VALUE *argv, VALUE ary)
{
    VALUE arg;
    long beg, len;

    if (argc == 2) {
    beg = NUM2LONG(argv[0]);
    len = NUM2LONG(argv[1]);
    if (beg < 0) {
        beg += RARRAY_LEN(ary);
    }
    return rb_ary_subseq(ary, beg, len);
    }
    if (argc != 1) {
    rb_scan_args(argc, argv, "11", 0, 0);
    }
    arg = argv[0];
    /* special case - speeding up */
    if (FIXNUM_P(arg)) {
    return rb_ary_entry(ary, FIX2LONG(arg));
    }
    /* check if idx is Range */
    switch (rb_range_beg_len(arg, &beg, &len, RARRAY_LEN(ary), 0)) {
      case Qfalse:
    break;
      case Qnil:
    return Qnil;
      default:
    return rb_ary_subseq(ary, beg, len);
    }
    return rb_ary_entry(ary, NUM2LONG(arg));
}

#[]=(index) ⇒ Object #[]=(start, length) ⇒ Object? #[]=(range) ⇒ Object?

Element Assignment---Sets the element at index, or replaces a subarray starting at start and continuing for length elements, or replaces a subarray specified by range. If indices are greater than the current capacity of the array, the array grows automatically. A negative indices will count backward from the end of the array. Inserts elements if length is zero. 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"]

Overloads:




# File 'array.c'

/*
 *  call-seq:
 *     ary[index]         = obj                      ->  obj
 *     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 starting at _start_ and
 *  continuing for _length_ elements, or replaces a subarray
 *  specified by _range_.  If indices are greater than
 *  the current capacity of the array, the array grows
 *  automatically. A negative indices will count backward
 *  from the end of the array. Inserts elements if _length_ is
 *  zero. An +IndexError+ is raised if a negative index points
 *  past the beginning of the array. See also
 *  <code>Array#push</code>, and <code>Array#unshift</code>.
 *
 *     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"]
 */

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

    if (argc == 3) {
    rb_ary_modify_check(ary);
    beg = NUM2LONG(argv[0]);
    len = NUM2LONG(argv[1]);
    rb_ary_splice(ary, beg, len, argv[2]);
    return argv[2];
    }
    if (argc != 2) {
    rb_raise(rb_eArgError, "wrong number of arguments (%d for 2)", argc);
    }
    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 */
    rb_ary_splice(ary, beg, len, argv[1]);
    return argv[1];
    }

    offset = NUM2LONG(argv[0]);
fixnum:
    rb_ary_store(ary, offset, argv[1]);
    return argv[1];
}

#assoc(obj) ⇒ nil

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

Returns:

  • (nil) 



# File 'array.c'

/*
 *  call-seq:
 *     ary.assoc(obj)   -> new_ary  or  nil
 *
 *  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 <code>Array#rassoc</code>.
 *
 *     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_PTR(ary)[i]);
    if (!NIL_P(v) && RARRAY_LEN(v) > 0 &&
        rb_equal(RARRAY_PTR(v)[0], key))
        return v;
    }
    return Qnil;
}

#at(index) ⇒ Object?

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"

Returns:




# File 'array.c'

/*
 *  call-seq:
 *     ary.at(index)   ->   obj  or nil
 *
 *  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 <code>Array#[]</code>.
 *
 *     a = [ "a", "b", "c", "d", "e" ]
 *     a.at(0)     #=> "a"
 *     a.at(-1)    #=> "e"
 */

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

#clear ⇒ Object

Removes all elements from self.

a = [ "a", "b", "c", "d", "e" ]
a.clear    #=> [ ]




# File 'array.c'

/*
 *  call-seq:
 *     ary.clear    -> ary
 *
 *  Removes all elements from +self+.
 *
 *     a = [ "a", "b", "c", "d", "e" ]
 *     a.clear    #=> [ ]
 */

VALUE
rb_ary_clear(VALUE ary)
{
    rb_ary_modify(ary);
    ARY_SET_LEN(ary, 0);
    if (ARY_DEFAULT_SIZE * 2 < ARY_CAPA(ary)) {
    ary_resize_capa(ary, ARY_DEFAULT_SIZE * 2);
    }
    return ary;
}

#collect {|item| ... } ⇒ Object #map {|item| ... } ⇒ Object #collect ⇒ Object #map ⇒ Object

Invokes 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                          #=> ["a", "b", "c", "d"]

Overloads:

  • #collect {|item| ... } ⇒ Object

    Yields:

    • (item)
  • #map {|item| ... } ⇒ Object

    Yields:

    • (item) 



# File 'array.c'

/*
 *  call-seq:
 *     ary.collect {|item| block }  -> new_ary
 *     ary.map     {|item| block }  -> new_ary
 *     ary.collect                  -> an_enumerator
 *     ary.map                      -> an_enumerator
 *
 *  Invokes <i>block</i> once for each element of +self+. Creates a
 *  new array containing the values returned by the block.
 *  See also <code>Enumerable#collect</code>.
 *
 *  If no block is given, an enumerator is returned instead.
 *
 *     a = [ "a", "b", "c", "d" ]
 *     a.collect {|x| x + "!" }   #=> ["a!", "b!", "c!", "d!"]
 *     a                          #=> ["a", "b", "c", "d"]
 */

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

    RETURN_ENUMERATOR(ary, 0, 0);
    collect = rb_ary_new2(RARRAY_LEN(ary));
    for (i = 0; i < RARRAY_LEN(ary); i++) {
    rb_ary_push(collect, rb_yield(RARRAY_PTR(ary)[i]));
    }
    return collect;
}

#collect! {|item| ... } ⇒ Object #map! {|item| ... } ⇒ Object #collect ⇒ Object #map ⇒ Object

Invokes the block once for each element of self, replacing the element with the value returned by 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             #=>  [ "a!", "b!", "c!", "d!" ]

Overloads:

  • #collect! {|item| ... } ⇒ Object

    Yields:

    • (item)
  • #map! {|item| ... } ⇒ Object

    Yields:

    • (item) 



# File 'array.c'

/*
 *  call-seq:
 *     ary.collect! {|item| block }   -> ary
 *     ary.map!     {|item| block }   -> ary
 *     ary.collect                    -> an_enumerator
 *     ary.map                        -> an_enumerator
 *
 *  Invokes the block once for each element of +self+, replacing the
 *  element with the value returned by _block_.
 *  See also <code>Enumerable#collect</code>.
 *
 *  If no block is given, an enumerator is returned instead.
 *
 *     a = [ "a", "b", "c", "d" ]
 *     a.collect! {|x| x + "!" }
 *     a             #=>  [ "a!", "b!", "c!", "d!" ]
 */

static VALUE
rb_ary_collect_bang(VALUE ary)
{
    long i;

    RETURN_ENUMERATOR(ary, 0, 0);
    rb_ary_modify(ary);
    for (i = 0; i < RARRAY_LEN(ary); i++) {
    rb_ary_store(ary, i, rb_yield(RARRAY_PTR(ary)[i]));
    }
    return ary;
}

#combination(n) {|c| ... } ⇒ Object #combination(n) ⇒ Object

When invoked with a block, yields all combinations of length n of elements from ary and then returns ary 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

Overloads:

  • #combination(n) {|c| ... } ⇒ Object

    Yields:

    • (c) 



# File 'array.c'

/*
 *  call-seq:
 *     ary.combination(n) { |c| block }    -> ary
 *     ary.combination(n)                  -> an_enumerator
 *
 * When invoked with a block, yields all combinations of length <i>n</i>
 * of elements from <i>ary</i> and then returns <i>ary</i> 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 n, i, len;

    n = NUM2LONG(num);
    RETURN_ENUMERATOR(ary, 1, &num);
    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 < len; i++) {
        rb_yield(rb_ary_new3(1, RARRAY_PTR(ary)[i]));
    }
    }
    else {
    volatile VALUE t0 = tmpbuf(n+1, sizeof(long));
    long *stack = (long*)RSTRING_PTR(t0);
    volatile VALUE cc = tmpary(n);
    VALUE *chosen = RARRAY_PTR(cc);
    long lev = 0;

    MEMZERO(stack, long, n);
    stack[0] = -1;
    for (;;) {
        chosen[lev] = RARRAY_PTR(ary)[stack[lev+1]];
        for (lev++; lev < n; lev++) {
        chosen[lev] = RARRAY_PTR(ary)[stack[lev+1] = stack[lev]+1];
        }
        rb_yield(rb_ary_new4(n, chosen));
        if (RBASIC(t0)->klass) {
        rb_raise(rb_eRuntimeError, "combination reentered");
        }
        do {
        if (lev == 0) goto done;
        stack[lev--]++;
        } while (stack[lev+1]+n == len+lev+1);
    }
    done:
    tmpbuf_discard(t0);
    tmpary_discard(cc);
    }
    return ary;
}

#compact ⇒ Object

Returns a copy of self with all nil elements removed.

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




# File 'array.c'

/*
 *  call-seq:
 *     ary.compact     -> new_ary
 *
 *  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! ⇒ nil

Removes nil elements from the array. Returns nil if no changes were made, otherwise returns </i>ary</i>.

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

Returns:

  • (nil) 



# File 'array.c'

/*
 *  call-seq:
 *     ary.compact!    -> ary  or  nil
 *
 *  Removes +nil+ elements from the array.
 *  Returns +nil+ if no changes were made, otherwise returns
 *  </i>ary</i>.
 *
 *     [ "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 = RARRAY_PTR(ary);
    end = p + RARRAY_LEN(ary);

    while (t < end) {
    if (NIL_P(*t)) t++;
    else *p++ = *t++;
    }
    n = p - RARRAY_PTR(ary);
    if (RARRAY_LEN(ary) == n) {
    return Qnil;
    }
    ARY_SET_LEN(ary, n);
    if (n * 2 < ARY_CAPA(ary) && ARY_DEFAULT_SIZE * 2 < ARY_CAPA(ary)) {
    ary_resize_capa(ary, n * 2);
    }

    return ary;
}

#concat(other_ary) ⇒ Object

Appends the elements of other_ary to self.

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




# File 'array.c'

/*
 *  call-seq:
 *     ary.concat(other_ary)   -> ary
 *
 *  Appends the elements of <i>other_ary</i> to +self+.
 *
 *     [ "a", "b" ].concat( ["c", "d"] ) #=> [ "a", "b", "c", "d" ]
 */


VALUE
rb_ary_concat(VALUE x, VALUE y)
{
    rb_ary_modify_check(x);
    y = to_ary(y);
    if (RARRAY_LEN(y) > 0) {
    rb_ary_splice(x, RARRAY_LEN(x), 0, y);
    }
    return x;
}

#count ⇒ Integer #count(obj) ⇒ Integer #count {|item| ... } ⇒ Integer

Returns the number of elements. If an argument is given, counts the number of elements which equals to obj. If a block is given, counts the number of elements yielding a true value.

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

Overloads:




# File 'array.c'

/*
 *  call-seq:
 *     ary.count      -> int
 *     ary.count(obj) -> int
 *     ary.count { |item| block }  -> int
 *
 *  Returns the number of elements.  If an argument is given, counts
 *  the number of elements which equals to <i>obj</i>.  If a block is
 *  given, counts the number of elements yielding 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 n = 0;

    if (argc == 0) {
    VALUE *p, *pend;

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

    for (p = RARRAY_PTR(ary), pend = p + RARRAY_LEN(ary); p < pend; p++) {
        if (RTEST(rb_yield(*p))) n++;
    }
    }
    else {
    VALUE obj, *p, *pend;

    rb_scan_args(argc, argv, "1", &obj);
    if (rb_block_given_p()) {
        rb_warn("given block not used");
    }
    for (p = RARRAY_PTR(ary), pend = p + RARRAY_LEN(ary); p < pend; p++) {
        if (rb_equal(*p, obj)) n++;
    }
    }

    return LONG2NUM(n);
}

#cycle(n = nil) {|obj| ... } ⇒ nil #cycle(n = nil) ⇒ Object

Calls block for each element repeatedly n times or forever if none or nil is given. If a non-positive number is given or the array is empty, does nothing. 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.

Overloads:

  • #cycle(n = nil) {|obj| ... } ⇒ nil

    Yields:

    • (obj)

    Returns:

    • (nil) 



# File 'array.c'

/*
 *  call-seq:
 *     ary.cycle(n=nil) {|obj| block }  -> nil
 *     ary.cycle(n=nil)                 -> an_enumerator
 *
 *  Calls <i>block</i> for each element repeatedly _n_ times or
 *  forever if none or +nil+ is given.  If a non-positive number is
 *  given or the array is empty, does nothing.  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;
    VALUE nv = Qnil;

    rb_scan_args(argc, argv, "01", &nv);

    RETURN_ENUMERATOR(ary, argc, argv);
    if (NIL_P(nv)) {
        n = -1;
    }
    else {
        n = NUM2LONG(nv);
        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_PTR(ary)[i]);
        }
    }
    return Qnil;
}

#delete(obj) ⇒ Object? #delete(obj) { ... } ⇒ Object?

Deletes items from self that are equal to obj. If any items are found, returns obj. If the item is not found, returns nil. If the optional code block is given, returns the result of block if the item is not found. (To remove nil elements and get an informative return value, use #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"

Overloads:




# File 'array.c'

/*
 *  call-seq:
 *     ary.delete(obj)            -> obj or nil
 *     ary.delete(obj) { block }  -> obj or nil
 *
 *  Deletes items from +self+ that are equal to <i>obj</i>.
 *  If any items are found, returns <i>obj</i>.   If
 *  the item is not found, returns <code>nil</code>. If the optional
 *  code block is given, returns the result of <i>block</i> if the item
 *  is not found.  (To remove <code>nil</code> elements and
 *  get an informative return value, use #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_PTR(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;
    }

    rb_ary_modify(ary);
    if (RARRAY_LEN(ary) > i2) {
    ARY_SET_LEN(ary, i2);
    if (i2 * 2 < ARY_CAPA(ary) &&
        ARY_CAPA(ary) > ARY_DEFAULT_SIZE) {
        ary_resize_capa(ary, i2*2);
    }
    }

    return v;
}

#delete_at(index) ⇒ Object?

Deletes the element at the specified index, returning that element, or nil if the index is out of range. See also Array#slice!.

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

Returns:




# File 'array.c'

/*
 *  call-seq:
 *     ary.delete_at(index)  -> obj or nil
 *
 *  Deletes the element at the specified index, returning that element,
 *  or <code>nil</code> if the index is out of range. See also
 *  <code>Array#slice!</code>.
 *
 *     a = %w( 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| ... } ⇒ Object #delete_if ⇒ Object

Deletes every element of self for which block evaluates to true. See also Array#reject!

If no block is given, an enumerator is returned instead.

a = [ "a", "b", "c" ]
a.delete_if {|x| x >= "b" }   #=> ["a"]

Overloads:

  • #delete_if {|item| ... } ⇒ Object

    Yields:

    • (item) 



# File 'array.c'

/*
 *  call-seq:
 *     ary.delete_if {|item| block }  -> ary
 *     ary.delete_if                  -> an_enumerator
 *
 *  Deletes every element of +self+ for which <i>block</i> evaluates
 *  to true.
 *  See also <code>Array#reject!</code>
 *
 *  If no block is given, an enumerator is returned instead.
 *
 *     a = [ "a", "b", "c" ]
 *     a.delete_if {|x| x >= "b" }   #=> ["a"]
 */

static VALUE
rb_ary_delete_if(VALUE ary)
{
    RETURN_ENUMERATOR(ary, 0, 0);
    rb_ary_reject_bang(ary);
    return ary;
}

#drop(n) ⇒ Object

Drops first n elements from ary, and returns rest elements in an array.

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




# File 'array.c'

/*
 *  call-seq:
 *     ary.drop(n)               -> new_ary
 *
 *  Drops first n elements from <i>ary</i>, and returns rest elements
 *  in an array.
 *
 *     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 {|arr| ... } ⇒ Object #drop_while ⇒ Object

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.

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

Overloads:

  • #drop_while {|arr| ... } ⇒ Object

    Yields:

    • (arr) 



# File 'array.c'

/*
 *  call-seq:
 *     ary.drop_while {|arr| block }   -> new_ary
 *     ary.drop_while                  -> an_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.
 *
 *     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_PTR(ary)[i]))) break;
    }
    return rb_ary_drop(ary, LONG2FIX(i));
}

#each {|item| ... } ⇒ Object #each ⇒ Object

Calls block once for each element in self, passing that element as a parameter.

If no block is given, an enumerator is returned instead.

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

produces:

a -- b -- c --

Overloads:

  • #each {|item| ... } ⇒ Object

    Yields:

    • (item) 



# File 'array.c'

/*
 *  call-seq:
 *     ary.each {|item| block }   -> ary
 *     ary.each                   -> an_enumerator
 *
 *  Calls <i>block</i> once for each element in +self+, passing that
 *  element as a parameter.
 *
 *  If no block is given, an enumerator is returned instead.
 *
 *     a = [ "a", "b", "c" ]
 *     a.each {|x| print x, " -- " }
 *
 *  produces:
 *
 *     a -- b -- c --
 */

VALUE
rb_ary_each(VALUE ary)
{
    long i;

    RETURN_ENUMERATOR(ary, 0, 0);
    for (i=0; i<RARRAY_LEN(ary); i++) {
    rb_yield(RARRAY_PTR(ary)[i]);
    }
    return ary;
}

#each_index {|index| ... } ⇒ Object #each_index ⇒ Object

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

If no block is given, an enumerator is returned instead.

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

produces:

0 -- 1 -- 2 --

Overloads:

  • #each_index {|index| ... } ⇒ Object

    Yields:




# File 'array.c'

/*
 *  call-seq:
 *     ary.each_index {|index| block }  -> ary
 *     ary.each_index                   -> an_enumerator
 *
 *  Same as <code>Array#each</code>, but passes the index of the element
 *  instead of the element itself.
 *
 *  If no block is given, an enumerator is returned instead.
 *
 *
 *     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_ENUMERATOR(ary, 0, 0);

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

#empty? ⇒ Boolean

Returns true if self contains no elements.

[].empty?   #=> true

Returns:

  • (Boolean) 



# File 'array.c'

/*
 *  call-seq:
 *     ary.empty?   -> true or false
 *
 *  Returns <code>true</code> 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) ⇒ Boolean

Returns true if self and other are the same object, or are both arrays with the same content.

Returns:

  • (Boolean) 



# File 'array.c'

/*
 *  call-seq:
 *     ary.eql?(other)  -> true or false
 *
 *  Returns <code>true</code> if +self+ and _other_ are the same object,
 *  or are both arrays with the same content.
 */

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

#fetch(index) ⇒ Object #fetch(index, default) ⇒ Object #fetch(index) {|index| ... } ⇒ Object

Tries to return the element at position index. If the index lies outside the array, the first form throws an IndexError exception, the second form returns default, and the third form returns the value of invoking the block, passing in the index. 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(4) { |i| i*i }   #=> 16

Overloads:




# File 'array.c'

/*
 *  call-seq:
 *     ary.fetch(index)                    -> obj
 *     ary.fetch(index, default )          -> obj
 *     ary.fetch(index) {|index| block }   -> obj
 *
 *  Tries to return the element at position <i>index</i>. If the index
 *  lies outside the array, the first form throws an
 *  <code>IndexError</code> exception, the second form returns
 *  <i>default</i>, and the third form returns the value of invoking
 *  the block, passing in the index. Negative values of <i>index</i>
 *  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(4) { |i| i*i }   #=> 16
 */

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_PTR(ary)[idx];
}

#fill(obj) ⇒ Object #fill(obj, start[, length]) ⇒ Object #fill(obj, range) ⇒ Object #fill {|index| ... } ⇒ Object #fill(start[, length]) {|index| ... } ⇒ Object #fill(range) {|index| ... } ⇒ Object

The first three forms set the selected elements of self (which may be the entire array) to obj. A start of nil is equivalent to zero. A length of nil is equivalent to self.length. The last three forms fill the array with the value of the block. The block is passed the absolute index of each element to be filled. Negative values of start count from the end of the array.

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]

Overloads:

  • #fill {|index| ... } ⇒ Object

    Yields:

  • #fill(start[, length]) {|index| ... } ⇒ Object

    Yields:

  • #fill(range) {|index| ... } ⇒ Object

    Yields:




# File 'array.c'

/*
 *  call-seq:
 *     ary.fill(obj)                                -> ary
 *     ary.fill(obj, start [, length])              -> ary
 *     ary.fill(obj, range )                        -> ary
 *     ary.fill {|index| block }                    -> ary
 *     ary.fill(start [, length] ) {|index| block } -> ary
 *     ary.fill(range) {|index| block }             -> ary
 *
 *  The first three forms set the selected elements of +self+ (which
 *  may be the entire array) to <i>obj</i>. A <i>start</i> of
 *  <code>nil</code> is equivalent to zero. A <i>length</i> of
 *  <code>nil</code> is equivalent to <i>self.length</i>. The last three
 *  forms fill the array with the value of the block. The block is
 *  passed the absolute index of each element to be filled.
 *  Negative values of <i>start</i> count from the end of the array.
 *
 *     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, arg1, arg2;
    long beg = 0, end = 0, len = 0;
    VALUE *p, *pend;
    int block_p = FALSE;

    if (rb_block_given_p()) {
    block_p = TRUE;
    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);
    }
    rb_mem_clear(RARRAY_PTR(ary) + RARRAY_LEN(ary), end - RARRAY_LEN(ary));
    ARY_SET_LEN(ary, end);
    }

    if (block_p) {
    VALUE v;
    long i;

    for (i=beg; i<end; i++) {
        v = rb_yield(LONG2NUM(i));
        if (i>=RARRAY_LEN(ary)) break;
        RARRAY_PTR(ary)[i] = v;
    }
    }
    else {
    p = RARRAY_PTR(ary) + beg;
    pend = p + len;
    while (p < pend) {
        *p++ = item;
    }
    }
    return ary;
}

#index(obj) ⇒ Integer? #index {|item| ... } ⇒ Integer? #index ⇒ Object

Returns the index of the first object in self such that is == to obj. If a block is given instead of an argument, returns first object for which block is true. Returns nil if no match is found. See also Array#rindex.

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

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

This is an alias of #find_index.

Overloads:




# File 'array.c'

/*
 *  call-seq:
 *     ary.index(obj)           ->  int or nil
 *     ary.index {|item| block} ->  int or nil
 *     ary.index                ->  an_enumerator
 *
 *  Returns the index of the first object in +self+ such that is
 *  <code>==</code> to <i>obj</i>. If a block is given instead of an
 *  argument, returns first object for which <em>block</em> is true.
 *  Returns <code>nil</code> if no match is found.
 *  See also <code>Array#rindex</code>.
 *
 *  If neither block nor argument is given, an enumerator is returned instead.
 *
 *     a = [ "a", "b", "c" ]
 *     a.index("b")        #=> 1
 *     a.index("z")        #=> nil
 *     a.index{|x|x=="b"}  #=> 1
 *
 *  This is an alias of <code>#find_index</code>.
 */

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_PTR(ary)[i]))) {
        return LONG2NUM(i);
        }
    }
    return Qnil;
    }
    rb_scan_args(argc, argv, "1", &val);
    if (rb_block_given_p())
    rb_warn("given block not used");
    for (i=0; i<RARRAY_LEN(ary); i++) {
    if (rb_equal(RARRAY_PTR(ary)[i], val))
        return LONG2NUM(i);
    }
    return Qnil;
}

#first ⇒ Object? #first(n) ⇒ Object

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.

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

Overloads:




# File 'array.c'

/*
 *  call-seq:
 *     ary.first     ->   obj or nil
 *     ary.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 <code>nil</code>, and the
 *  second form returns an empty array.
 *
 *     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_PTR(ary)[0];
    }
    else {
    return ary_take_first_or_last(argc, argv, ary, ARY_TAKE_FIRST);
    }
}

#flatten ⇒ Object #flatten(level) ⇒ Object

Returns a new array that is a one-dimensional flattening of this array (recursively). That is, for every element that is an array, extract its elements into the new array. If 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]]




# File 'array.c'

/*
 *  call-seq:
 *     ary.flatten -> new_ary
 *     ary.flatten(level) -> new_ary
 *
 *  Returns a new array that is a one-dimensional flattening of this
 *  array (recursively). That is, for every element that is an array,
 *  extract its elements into the new array.  If the optional
 *  <i>level</i> 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, lv;

    rb_scan_args(argc, argv, "01", &lv);
    if (!NIL_P(lv)) level = NUM2INT(lv);
    if (level == 0) return ary_make_shared_copy(ary);

    result = flatten(ary, level, &mod);
    OBJ_INFECT(result, ary);

    return result;
}

#flatten! ⇒ nil #flatten!(level) ⇒ Array?

Flattens self in place. Returns nil if no modifications were made (i.e., ary contains no subarrays.) If 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]]

Overloads:

  • #flatten! ⇒ nil

    Returns:

    • (nil)
  • #flatten!(level) ⇒ Array?

    Returns:




# File 'array.c'

/*
 *  call-seq:
 *     ary.flatten!        -> ary or nil
 *     ary.flatten!(level) -> array or nil
 *
 *  Flattens +self+ in place.
 *  Returns <code>nil</code> if no modifications were made (i.e.,
 *  <i>ary</i> contains no subarrays.)  If the optional <i>level</i>
 *  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;

    rb_scan_args(argc, argv, "01", &lv);
    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;
}

#frozen? ⇒ Boolean

Return true if this array is frozen (or temporarily frozen while being sorted).

Returns:

  • (Boolean) 



# File 'array.c'

/*
 *  call-seq:
 *     ary.frozen?  -> true or false
 *
 *  Return <code>true</code> if this array is frozen (or temporarily frozen
 *  while being sorted).
 */

static VALUE
rb_ary_frozen_p(VALUE ary)
{
    if (OBJ_FROZEN(ary)) return Qtrue;
    return Qfalse;
}

#hash ⇒ Fixnum

Compute a hash-code for this array. Two arrays with the same content will have the same hash code (and will compare using eql?).

Returns:




# File 'array.c'

/*
 *  call-seq:
 *     ary.hash   -> fixnum
 *
 *  Compute a hash-code for this array. Two arrays with the same content
 *  will have the same hash code (and will compare using <code>eql?</code>).
 */

static VALUE
rb_ary_hash(VALUE ary)
{
    return rb_exec_recursive_outer(recursive_hash, ary, 0);
}

#include?(obj) ⇒ Boolean

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

a = [ "a", "b", "c" ]
a.include?("b")   #=> true
a.include?("z")   #=> false

Returns:

  • (Boolean) 



# File 'array.c'

/*
 *  call-seq:
 *     ary.include?(obj)   -> true or false
 *
 *  Returns <code>true</code> if the given object is present in
 *  +self+ (that is, if any object <code>==</code> <i>anObject</i>),
 *  <code>false</code> otherwise.
 *
 *     a = [ "a", "b", "c" ]
 *     a.include?("b")   #=> true
 *     a.include?("z")   #=> false
 */

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

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

#index(obj) ⇒ Integer? #index {|item| ... } ⇒ Integer? #index ⇒ Object

Returns the index of the first object in self such that is == to obj. If a block is given instead of an argument, returns first object for which block is true. Returns nil if no match is found. See also Array#rindex.

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

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

This is an alias of #find_index.

Overloads:




# File 'array.c'

/*
 *  call-seq:
 *     ary.index(obj)           ->  int or nil
 *     ary.index {|item| block} ->  int or nil
 *     ary.index                ->  an_enumerator
 *
 *  Returns the index of the first object in +self+ such that is
 *  <code>==</code> to <i>obj</i>. If a block is given instead of an
 *  argument, returns first object for which <em>block</em> is true.
 *  Returns <code>nil</code> if no match is found.
 *  See also <code>Array#rindex</code>.
 *
 *  If neither block nor argument is given, an enumerator is returned instead.
 *
 *     a = [ "a", "b", "c" ]
 *     a.index("b")        #=> 1
 *     a.index("z")        #=> nil
 *     a.index{|x|x=="b"}  #=> 1
 *
 *  This is an alias of <code>#find_index</code>.
 */

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_PTR(ary)[i]))) {
        return LONG2NUM(i);
        }
    }
    return Qnil;
    }
    rb_scan_args(argc, argv, "1", &val);
    if (rb_block_given_p())
    rb_warn("given block not used");
    for (i=0; i<RARRAY_LEN(ary); i++) {
    if (rb_equal(RARRAY_PTR(ary)[i], val))
        return LONG2NUM(i);
    }
    return Qnil;
}

#replace(other_ary) ⇒ Object

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"]




# File 'array.c'

/*
 *  call-seq:
 *     ary.replace(other_ary)  -> ary
 *
 *  Replaces the contents of +self+ with the contents of
 *  <i>other_ary</i>, 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 *ptr;
        VALUE shared = 0;

        if (ARY_OWNS_HEAP_P(copy)) {
            xfree(RARRAY_PTR(copy));
        }
        else if (ARY_SHARED_P(copy)) {
            shared = ARY_SHARED(copy);
            FL_UNSET_SHARED(copy);
        }
        FL_SET_EMBED(copy);
        ptr = RARRAY_PTR(orig);
        MEMCPY(RARRAY_PTR(copy), ptr, VALUE, RARRAY_LEN(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)) {
            xfree(RARRAY_PTR(copy));
        }
        else {
            rb_ary_unshare_safe(copy);
        }
        FL_UNSET_EMBED(copy);
        ARY_SET_PTR(copy, RARRAY_PTR(orig));
        ARY_SET_LEN(copy, RARRAY_LEN(orig));
        rb_ary_set_shared(copy, shared);
    }
    return copy;
}

#insert(index, obj...) ⇒ Object

Inserts the given values before the element with the given index (which may be negative).

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"]




# File 'array.c'

/*
 *  call-seq:
 *     ary.insert(index, obj...)  -> ary
 *
 *  Inserts the given values before the element with the given index
 *  (which may be negative).
 *
 *     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;

    if (argc < 1) {
    rb_raise(rb_eArgError, "wrong number of arguments (at least 1)");
    }
    rb_ary_modify_check(ary);
    if (argc == 1) return ary;
    pos = NUM2LONG(argv[0]);
    if (pos == -1) {
    pos = RARRAY_LEN(ary);
    }
    if (pos < 0) {
    pos++;
    }
    rb_ary_splice(ary, pos, 0, rb_ary_new4(argc - 1, argv + 1));
    return ary;
}

#to_s ⇒ String #inspect ⇒ String

Creates a string representation of self.

Overloads:




# File 'array.c'

/*
 *  call-seq:
 *     ary.to_s -> string
 *     ary.inspect  -> string
 *
 *  Creates a string representation of +self+.
 */

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

#join(sep = $,) ⇒ String

Returns a string created by converting each element of the array to a string, separated by sep.

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

Returns:




# File 'array.c'

/*
 *  call-seq:
 *     ary.join(sep=$,)    -> str
 *
 *  Returns a string created by converting each element of the array to
 *  a string, separated by <i>sep</i>.
 *
 *     [ "a", "b", "c" ].join        #=> "abc"
 *     [ "a", "b", "c" ].join("-")   #=> "a-b-c"
 */

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

    rb_scan_args(argc, argv, "01", &sep);
    if (NIL_P(sep)) sep = rb_output_fs;

    return rb_ary_join(ary, sep);
}

#keep_if {|item| ... } ⇒ Object #keep_if ⇒ Object

Deletes every element of self for which block evaluates to false. See also Array#select!

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"]

Overloads:

  • #keep_if {|item| ... } ⇒ Object

    Yields:

    • (item) 



# File 'array.c'

/*
 *  call-seq:
 *     ary.keep_if {|item| block } -> ary
 *     ary.keep_if                 -> an_enumerator
 *
 *  Deletes every element of +self+ for which <i>block</i> evaluates
 *  to false.
 *  See also <code>Array#select!</code>
 *
 *  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"]
 */

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

#last ⇒ Object? #last(n) ⇒ Object

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

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

Overloads:




# File 'array.c'

/*
 *  call-seq:
 *     ary.last     ->  obj or nil
 *     ary.last(n)  ->  new_ary
 *
 *  Returns the last element(s) of +self+. If the array is empty,
 *  the first form returns <code>nil</code>.
 *
 *     a = [ "w", "x", "y", "z" ]
 *     a.last     #=> "z"
 *     a.last(2)  #=> ["y", "z"]
 */

VALUE
rb_ary_last(int argc, VALUE *argv, VALUE ary)
{
    if (argc == 0) {
    if (RARRAY_LEN(ary) == 0) return Qnil;
    return RARRAY_PTR(ary)[RARRAY_LEN(ary)-1];
    }
    else {
    return ary_take_first_or_last(argc, argv, ary, ARY_TAKE_LAST);
    }
}

#length ⇒ Integer

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

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

Returns:




# File 'array.c'

/*
 *  call-seq:
 *     ary.length -> int
 *
 *  Returns the number of elements in +self+. May be zero.
 *
 *     [ 1, 2, 3, 4, 5 ].length   #=> 5
 */

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

#collect {|item| ... } ⇒ Object #map {|item| ... } ⇒ Object #collect ⇒ Object #map ⇒ Object

Invokes 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                          #=> ["a", "b", "c", "d"]

Overloads:

  • #collect {|item| ... } ⇒ Object

    Yields:

    • (item)
  • #map {|item| ... } ⇒ Object

    Yields:

    • (item) 



# File 'array.c'

/*
 *  call-seq:
 *     ary.collect {|item| block }  -> new_ary
 *     ary.map     {|item| block }  -> new_ary
 *     ary.collect                  -> an_enumerator
 *     ary.map                      -> an_enumerator
 *
 *  Invokes <i>block</i> once for each element of +self+. Creates a
 *  new array containing the values returned by the block.
 *  See also <code>Enumerable#collect</code>.
 *
 *  If no block is given, an enumerator is returned instead.
 *
 *     a = [ "a", "b", "c", "d" ]
 *     a.collect {|x| x + "!" }   #=> ["a!", "b!", "c!", "d!"]
 *     a                          #=> ["a", "b", "c", "d"]
 */

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

    RETURN_ENUMERATOR(ary, 0, 0);
    collect = rb_ary_new2(RARRAY_LEN(ary));
    for (i = 0; i < RARRAY_LEN(ary); i++) {
    rb_ary_push(collect, rb_yield(RARRAY_PTR(ary)[i]));
    }
    return collect;
}

#collect! {|item| ... } ⇒ Object #map! {|item| ... } ⇒ Object #collect ⇒ Object #map ⇒ Object

Invokes the block once for each element of self, replacing the element with the value returned by 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             #=>  [ "a!", "b!", "c!", "d!" ]

Overloads:

  • #collect! {|item| ... } ⇒ Object

    Yields:

    • (item)
  • #map! {|item| ... } ⇒ Object

    Yields:

    • (item) 



# File 'array.c'

/*
 *  call-seq:
 *     ary.collect! {|item| block }   -> ary
 *     ary.map!     {|item| block }   -> ary
 *     ary.collect                    -> an_enumerator
 *     ary.map                        -> an_enumerator
 *
 *  Invokes the block once for each element of +self+, replacing the
 *  element with the value returned by _block_.
 *  See also <code>Enumerable#collect</code>.
 *
 *  If no block is given, an enumerator is returned instead.
 *
 *     a = [ "a", "b", "c", "d" ]
 *     a.collect! {|x| x + "!" }
 *     a             #=>  [ "a!", "b!", "c!", "d!" ]
 */

static VALUE
rb_ary_collect_bang(VALUE ary)
{
    long i;

    RETURN_ENUMERATOR(ary, 0, 0);
    rb_ary_modify(ary);
    for (i = 0; i < RARRAY_LEN(ary); i++) {
    rb_ary_store(ary, i, rb_yield(RARRAY_PTR(ary)[i]));
    }
    return ary;
}

#pack ⇒ Object

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"

Directives for pack.

Integer      | Array   |
Directive    | Element | Meaning
---------------------------------------------------------------------------
   C         | Integer | 8-bit unsigned integer (unsigned char)
   S         | Integer | 16-bit unsigned integer, native endian (uint16_t)
   L         | Integer | 32-bit unsigned integer, native endian (uint32_t)
   Q         | Integer | 64-bit unsigned integer, native endian (uint64_t)
             |         |
   c         | Integer | 8-bit signed integer (char)
   s         | Integer | 16-bit signed integer, native endian (int16_t)
   l         | Integer | 32-bit signed integer, native endian (int32_t)
   q         | Integer | 64-bit signed integer, native endian (int64_t)
             |         |
   S_, S!    | Integer | unsigned short, native endian
   I, I_, I! | Integer | unsigned int, native endian
   L_, L!    | Integer | unsigned long, native endian
             |         |
   s_, s!    | Integer | signed short, native endian
   i, i_, i! | Integer | signed int, native endian
   l_, l!    | Integer | signed long, native endian
             |         |
   n         | Integer | 16-bit unsigned integer, network (big-endian) byte order
   N         | Integer | 32-bit unsigned integer, network (big-endian) byte order
   v         | Integer | 16-bit unsigned integer, VAX (little-endian) byte order
   V         | Integer | 32-bit unsigned integer, VAX (little-endian) byte order
             |         |
   U         | Integer | UTF-8 character
   w         | Integer | BER-compressed integer

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

String       |         |
Directive    |         | 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 RFC2045)
   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.        |         |
Directive    |         | Meaning
---------------------------------------------------------------------------
   @         | ---     | moves to absolute position
   X         | ---     | back up a byte
   x         | ---     | null byte




# File 'pack.c'

/*
 *  call-seq:
 *     arr.pack ( aTemplateString ) -> aBinaryString
 *
 *  Packs the contents of <i>arr</i> into a binary sequence according to
 *  the directives in <i>aTemplateString</i> (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
 *  (``<code>*</code>''), all remaining array elements will be
 *  converted. Any of the directives ``<code>sSiIlL</code>'' may be
 *  followed by an underscore (``<code>_</code>'') or
 *  exclamation mark (``<code>!</code>'') 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 <code>String#unpack</code>.
 *
 *     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"
 *
 *  Directives for +pack+.
 *
 *   Integer      | Array   |
 *   Directive    | Element | Meaning
 *   ---------------------------------------------------------------------------
 *      C         | Integer | 8-bit unsigned integer (unsigned char)
 *      S         | Integer | 16-bit unsigned integer, native endian (uint16_t)
 *      L         | Integer | 32-bit unsigned integer, native endian (uint32_t)
 *      Q         | Integer | 64-bit unsigned integer, native endian (uint64_t)
 *                |         |
 *      c         | Integer | 8-bit signed integer (char)
 *      s         | Integer | 16-bit signed integer, native endian (int16_t)
 *      l         | Integer | 32-bit signed integer, native endian (int32_t)
 *      q         | Integer | 64-bit signed integer, native endian (int64_t)
 *                |         |
 *      S_, S!    | Integer | unsigned short, native endian
 *      I, I_, I! | Integer | unsigned int, native endian
 *      L_, L!    | Integer | unsigned long, native endian
 *                |         |
 *      s_, s!    | Integer | signed short, native endian
 *      i, i_, i! | Integer | signed int, native endian
 *      l_, l!    | Integer | signed long, native endian
 *                |         |
 *      n         | Integer | 16-bit unsigned integer, network (big-endian) byte order
 *      N         | Integer | 32-bit unsigned integer, network (big-endian) byte order
 *      v         | Integer | 16-bit unsigned integer, VAX (little-endian) byte order
 *      V         | Integer | 32-bit unsigned integer, VAX (little-endian) byte order
 *                |         |
 *      U         | Integer | UTF-8 character
 *      w         | Integer | BER-compressed integer
 *                
 *   Float        |         |
 *   Directive    |         | Meaning
 *   ---------------------------------------------------------------------------
 *      D, d      | Float   | double-precision float, native format
 *      F, f      | Float   | single-precision float, native format
 *      E         | Float   | double-precision float, little-endian byte order
 *      e         | Float   | single-precision float, little-endian byte order
 *      G         | Float   | double-precision float, network (big-endian) byte order
 *      g         | Float   | single-precision float, network (big-endian) byte order
 *                
 *   String       |         |
 *   Directive    |         | 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 RFC2045)
 *      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.        |         |
 *   Directive    |         | Meaning
 *   ---------------------------------------------------------------------------
 *      @         | ---     | moves to absolute position
 *      X         | ---     | back up a byte
 *      x         | ---     | null byte
 */

static VALUE
pack_pack(VALUE ary, VALUE fmt)
{
    static const char nul10[] = "\0\0\0\0\0\0\0\0\0\0";
    static const char spc10[] = "          ";
    const char *p, *pend;
    VALUE res, from, associates = 0;
    char type;
    long items, 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 signed_p, integer_size, bigendian_p;

    StringValue(fmt);
    p = RSTRING_PTR(fmt);
    pend = p + RSTRING_LEN(fmt);
    res = rb_str_buf_new(0);

    items = RARRAY_LEN(ary);
    idx = 0;

#define TOO_FEW (rb_raise(rb_eArgError, toofew), 0)
#define THISFROM (items > 0 ? RARRAY_PTR(ary)[idx] : TOO_FEW)
#define NEXTFROM (items-- > 0 ? RARRAY_PTR(ary)[idx++] : TOO_FEW)

    while (p < pend) {
    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;
    }
        if (*p == '_' || *p == '!') {
        static const char natstr[] = "sSiIlL";

        if (strchr(natstr, type)) {
#ifdef NATINT_PACK
        natint = 1;
#endif
        p++;
        }
        else {
        rb_raise(rb_eArgError, "'%c' allowed only after types %s", *p, natstr);
        }
    }
    if (*p == '*') {   /* set data length */
        len = strchr("@Xxu", type) ? 0
                : strchr("PMm", type) ? 1
                : items;
        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;

          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 = byte & 0xff;
                rb_str_buf_cat(res, &c, 1);
                byte = 0;
            }
            }
            if (len & 7) {
            char c;
            byte >>= 7 - (len & 7);
            c = byte & 0xff;
            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 = byte & 0xff;
                rb_str_buf_cat(res, &c, 1);
                byte = 0;
            }
            }
            if (len & 7) {
            char c;
            byte <<= 7 - (len & 7);
            c = byte & 0xff;
            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 = byte & 0xff;
                rb_str_buf_cat(res, &c, 1);
                byte = 0;
            }
            }
            if (len & 1) {
            char c = byte & 0xff;
            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 = byte & 0xff;
                rb_str_buf_cat(res, &c, 1);
                byte = 0;
            }
            }
            if (len & 1) {
            char c = byte & 0xff;
            rb_str_buf_cat(res, &c, 1);
            }
            len = j;
            goto grow;
        }
        break;
        }
        break;

      case 'c':        /* signed char */
      case 'C':        /* unsigned char */
        while (len-- > 0) {
        char c;

        from = NEXTFROM;
        c = (char)num2i32(from);
        rb_str_buf_cat(res, &c, sizeof(char));
        }
        break;

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

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

      case 'i':        /* signed int */
            signed_p = 1;
            integer_size = (int)sizeof(int);
            bigendian_p = BIGENDIAN_P();
            goto pack_integer;

      case 'I':        /* unsigned int */
            signed_p = 0;
            integer_size = (int)sizeof(int);
            bigendian_p = BIGENDIAN_P();
            goto pack_integer;

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

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

      case 'q':        /* signed quad (64bit) int */
            signed_p = 1;
            integer_size = 8;
            bigendian_p = BIGENDIAN_P();
            goto pack_integer;

      case 'Q':        /* unsigned quad (64bit) int */
            signed_p = 0;
            integer_size = 8;
            bigendian_p = BIGENDIAN_P();
            goto pack_integer;

      case 'n':        /* unsigned short (network byte-order)  */
            signed_p = 0;
            integer_size = 2;
            bigendian_p = 1;
            goto pack_integer;

      case 'N':        /* unsigned long (network byte-order) */
            signed_p = 0;
            integer_size = 4;
            bigendian_p = 1;
            goto pack_integer;

      case 'v':        /* unsigned short (VAX byte-order) */
            signed_p = 0;
            integer_size = 2;
            bigendian_p = 0;
            goto pack_integer;

      case 'V':        /* unsigned long (VAX byte-order) */
            signed_p = 0;
            integer_size = 4;
            bigendian_p = 0;
            goto pack_integer;

          pack_integer:
            switch (integer_size) {
#if defined(HAVE_INT16_T) && !defined(FORCE_BIG_PACK)
              case SIZEOF_INT16_T:
        while (len-- > 0) {
                    union {
                        int16_t i;
                        char a[sizeof(int16_t)];
                    } v;

            from = NEXTFROM;
            v.i = (int16_t)num2i32(from);
            if (bigendian_p != BIGENDIAN_P()) v.i = swap16(v.i);
            rb_str_buf_cat(res, v.a, sizeof(int16_t));
        }
        break;
#endif

#if defined(HAVE_INT32_T) && !defined(FORCE_BIG_PACK)
              case SIZEOF_INT32_T:
        while (len-- > 0) {
            union {
                        int32_t i;
                        char a[sizeof(int32_t)];
                    } v;

            from = NEXTFROM;
            v.i = (int32_t)num2i32(from);
            if (bigendian_p != BIGENDIAN_P()) v.i = swap32(v.i);
            rb_str_buf_cat(res, v.a, sizeof(int32_t));
        }
        break;
#endif

#if defined(HAVE_INT64_T) && SIZEOF_LONG == SIZEOF_INT64_T && !defined(FORCE_BIG_PACK)
              case SIZEOF_INT64_T:
        while (len-- > 0) {
            union {
                        int64_t i;
                        char a[sizeof(int64_t)];
                    } v;

            from = NEXTFROM;
            v.i = num2i32(from); /* can return 64bit value if SIZEOF_LONG == SIZEOF_INT64_T */
            if (bigendian_p != BIGENDIAN_P()) v.i = swap64(v.i);
            rb_str_buf_cat(res, v.a, sizeof(int64_t));
        }
        break;
#endif

          default:
                if (integer_size > MAX_INTEGER_PACK_SIZE)
                    rb_bug("unexpected intger size for pack: %d", integer_size);
                while (len-- > 0) {
                    union {
                        unsigned long i[(MAX_INTEGER_PACK_SIZE+SIZEOF_LONG-1)/SIZEOF_LONG];
                        char a[(MAX_INTEGER_PACK_SIZE+SIZEOF_LONG-1)/SIZEOF_LONG*SIZEOF_LONG];
                    } v;
                    int num_longs = (integer_size+SIZEOF_LONG-1)/SIZEOF_LONG;
                    int i;

                    from = NEXTFROM;
                    rb_big_pack(from, v.i, num_longs);
                    if (bigendian_p) {
                        for (i = 0; i < num_longs/2; i++) {
                            unsigned long t = v.i[i];
                            v.i[i] = v.i[num_longs-1-i];
                            v.i[num_longs-1-i] = t;
                        }
                    }
            if (bigendian_p != BIGENDIAN_P()) {
                        for (i = 0; i < num_longs; i++)
                            v.i[i] = swapl(v.i[i]);
                    }
                    rb_str_buf_cat(res,
                                   bigendian_p ?
                                     v.a + sizeof(long)*num_longs - integer_size :
                                     v.a,
                                   integer_size);
                }
                break;
        }
        break;

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

        from = NEXTFROM;
        f = (float)RFLOAT_VALUE(rb_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 f;
        FLOAT_CONVWITH(ftmp);

        from = NEXTFROM;
        f = (float)RFLOAT_VALUE(rb_to_float(from));
        f = HTOVF(f,ftmp);
        rb_str_buf_cat(res, (char*)&f, sizeof(float));
        }
        break;

      case 'E':        /* double precision float in VAX byte-order */
        while (len-- > 0) {
        double d;
        DOUBLE_CONVWITH(dtmp);

        from = NEXTFROM;
        d = RFLOAT_VALUE(rb_to_float(from));
        d = HTOVD(d,dtmp);
        rb_str_buf_cat(res, (char*)&d, 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 f;
        FLOAT_CONVWITH(ftmp);

        from = NEXTFROM;
        f = (float)RFLOAT_VALUE(rb_to_float(from));
        f = HTONF(f,ftmp);
        rb_str_buf_cat(res, (char*)&f, sizeof(float));
        }
        break;

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

        from = NEXTFROM;
        d = RFLOAT_VALUE(rb_to_float(from));
        d = HTOND(d,dtmp);
        rb_str_buf_cat(res, (char*)&d, 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);

        if (len == 0 && type == 'm') {
        encodes(res, ptr, plen, type, 0);
        ptr += plen;
        break;
        }
        if (len <= 2)
        len = 45;
        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);
        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);
        }
        if (!associates) {
            associates = rb_ary_new();
        }
        rb_ary_push(associates, from);
        rb_obj_taint(from);
        rb_str_buf_cat(res, (char*)&t, sizeof(char*));
        }
        break;

      case 'w':        /* BER compressed integer  */
        while (len-- > 0) {
        unsigned long ul;
        VALUE buf = rb_str_new(0, 0);
        char c, *bufs, *bufe;

        from = NEXTFROM;
        if (TYPE(from) == T_BIGNUM) {
            VALUE big128 = rb_uint2big(128);
            while (TYPE(from) == T_BIGNUM) {
            from = rb_big_divmod(from, big128);
            c = NUM2INT(RARRAY_PTR(from)[1]) | 0x80; /* mod */
            rb_str_buf_cat(buf, &c, sizeof(char));
            from = RARRAY_PTR(from)[0]; /* div */
            }
        }

        {
            long l = NUM2LONG(from);
            if (l < 0) {
            rb_raise(rb_eArgError, "can't compress negative numbers");
            }
            ul = l;
        }

        while (ul) {
            c = (char)(ul & 0x7f) | 0x80;
            rb_str_buf_cat(buf, &c, sizeof(char));
            ul >>=  7;
        }

        if (RSTRING_LEN(buf)) {
            bufs = RSTRING_PTR(buf);
            bufe = bufs + RSTRING_LEN(buf) - 1;
            *bufs &= 0x7f; /* clear continue bit */
            while (bufs < bufe) { /* reverse */
            c = *bufs;
            *bufs++ = *bufe;
            *bufe-- = c;
            }
            rb_str_buf_cat(res, RSTRING_PTR(buf), RSTRING_LEN(buf));
        }
        else {
            c = 0;
            rb_str_buf_cat(res, &c, sizeof(char));
        }
        }
        break;

      default:
        break;
    }
    }

    if (associates) {
    rb_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| ... } ⇒ Object #permutation ⇒ Object #permutation(n) {|p| ... } ⇒ Object #permutation(n) ⇒ Object

When invoked with a block, yield all permutations of length n of the elements of ary, 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

Overloads:

  • #permutation {|p| ... } ⇒ Object

    Yields:

    • (p)
  • #permutation(n) {|p| ... } ⇒ Object

    Yields:

    • (p) 



# File 'array.c'

/*
 *  call-seq:
 *     ary.permutation { |p| block }          -> ary
 *     ary.permutation                        -> an_enumerator
 *     ary.permutation(n) { |p| block }       -> ary
 *     ary.permutation(n)                     -> an_enumerator
 *
 * When invoked with a block, yield all permutations of length <i>n</i>
 * of the elements of <i>ary</i>, then return the array itself.
 * If <i>n</i> 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)
{
    VALUE num;
    long r, n, i;

    n = RARRAY_LEN(ary);                  /* Array length */
    RETURN_ENUMERATOR(ary, argc, argv);   /* Return enumerator if no block */
    rb_scan_args(argc, argv, "01", &num);
    r = NIL_P(num) ? n : NUM2LONG(num);   /* 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_PTR(ary)[i]));
    }
    }
    else {             /* this is the general case */
    volatile VALUE t0 = tmpbuf(n,sizeof(long));
    long *p = (long*)RSTRING_PTR(t0);
    volatile VALUE t1 = tmpbuf(n,sizeof(char));
    char *used = (char*)RSTRING_PTR(t1);
    VALUE ary0 = ary_make_shared_copy(ary); /* private defensive copy of ary */
    RBASIC(ary0)->klass = 0;

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

    permute0(n, r, p, 0, used, ary0); /* compute and yield permutations */
    tmpbuf_discard(t0);
    tmpbuf_discard(t1);
    RBASIC(ary0)->klass = rb_cArray;
    }
    return ary;
}

#pop ⇒ Object? #pop(n) ⇒ Object

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.

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

Overloads:




# File 'array.c'

/*
 *  call-seq:
 *     ary.pop    -> obj or nil
 *     ary.pop(n) -> new_ary
 *
 *  Removes the last element from +self+ and returns it, or
 *  <code>nil</code> if the array is empty.
 *
 *  If a number _n_ is given, returns an array of the last n elements
 *  (or less) just like <code>array.slice!(-n, n)</code> does.
 *
 *     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));
    return result;
}

#product(other_ary, ...) ⇒ Object #product(other_ary, ...) {|p| ... } ⇒ Object

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([])          #=> []

Overloads:

  • #product(other_ary, ...) {|p| ... } ⇒ Object

    Yields:

    • (p) 



# File 'array.c'

/*
 *  call-seq:
 *     ary.product(other_ary, ...)                -> new_ary
 *     ary.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, <i>product</i> 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 = tmpbuf(n, sizeof(int));
    VALUE *arrays = RARRAY_PTR(t0); /* The arrays we're computing the product of */
    int *counters = (int*)RSTRING_PTR(t1); /* 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(t0)->klass = 0;
    RBASIC(t1)->klass = 0;

    /* 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]), l = resultlen;
        if (k == 0) {
        result = rb_ary_new2(0);
        goto done;
        }
        resultlen *= k;
        if (resultlen < k || resultlen < l || resultlen / k != l) {
        rb_raise(rb_eRangeError, "too big to product");
        }
    }
    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 overlows, we are done */
        if (--m < 0) goto done;
        counters[m]++;
    }
    }
done:
    tmpary_discard(t0);
    tmpbuf_discard(t1);

    return NIL_P(result) ? ary : result;
}

#push(obj, ...) ⇒ Object

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.

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




# File 'array.c'

/*
 *  call-seq:
 *     ary.push(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.
 *
 *     a = [ "a", "b", "c" ]
 *     a.push("d", "e", "f")
 *             #=> ["a", "b", "c", "d", "e", "f"]
 */

static VALUE
rb_ary_push_m(int argc, VALUE *argv, VALUE ary)
{
    rb_ary_modify(ary);
    while (argc--) {
    rb_ary_push_1(ary, *argv++);
    }
    return ary;
}

#rassoc(obj) ⇒ nil

Searches through the array whose elements are also arrays. Compares obj with the second element of each contained array using ==. Returns the first contained array that matches. See also Array#assoc.

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

Returns:

  • (nil) 



# File 'array.c'

/*
 *  call-seq:
 *     ary.rassoc(obj) -> new_ary or nil
 *
 *  Searches through the array whose elements are also arrays. Compares
 *  _obj_ with the second element of each contained array using
 *  <code>==</code>. Returns the first contained array that matches. See
 *  also <code>Array#assoc</code>.
 *
 *     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_PTR(ary)[i];
    if (TYPE(v) == T_ARRAY &&
        RARRAY_LEN(v) > 1 &&
        rb_equal(RARRAY_PTR(v)[1], value))
        return v;
    }
    return Qnil;
}

#reject {|item| ... } ⇒ Object #reject ⇒ Object

Returns a new array containing the items in self for which the block is not true. See also Array#delete_if

If no block is given, an enumerator is returned instead.

Overloads:

  • #reject {|item| ... } ⇒ Object

    Yields:

    • (item) 



# File 'array.c'

/*
 *  call-seq:
 *     ary.reject {|item| block }  -> new_ary
 *     ary.reject                  -> an_enumerator
 *
 *  Returns a new array containing the items in +self+
 *  for which the block is not true.
 *  See also <code>Array#delete_if</code>
 *
 *  If no block is given, an enumerator is returned instead.
 *
 */

static VALUE
rb_ary_reject(VALUE ary)
{
    RETURN_ENUMERATOR(ary, 0, 0);
    ary = rb_ary_dup(ary);
    rb_ary_reject_bang(ary);
    return ary;
}

#reject! {|item| ... } ⇒ nil #reject! ⇒ Object

Equivalent to Array#delete_if, deleting elements from self for which the block evaluates to true, but returns nil if no changes were made. See also Enumerable#reject and Array#delete_if.

If no block is given, an enumerator is returned instead.

Overloads:

  • #reject! {|item| ... } ⇒ nil

    Yields:

    • (item)

    Returns:

    • (nil) 



# File 'array.c'

/*
 *  call-seq:
 *     ary.reject! {|item| block }  -> ary or nil
 *     ary.reject!                  -> an_enumerator
 *
 *  Equivalent to <code>Array#delete_if</code>, deleting elements from
 *  +self+ for which the block evaluates to true, but returns
 *  <code>nil</code> if no changes were made.
 *  See also <code>Enumerable#reject</code> and <code>Array#delete_if</code>.
 *
 *  If no block is given, an enumerator is returned instead.
 *
 */

static VALUE
rb_ary_reject_bang(VALUE ary)
{
    long i1, i2;

    RETURN_ENUMERATOR(ary, 0, 0);
    rb_ary_modify(ary);
    for (i1 = i2 = 0; i1 < RARRAY_LEN(ary); i1++) {
    VALUE v = RARRAY_PTR(ary)[i1];
    if (RTEST(rb_yield(v))) continue;
    if (i1 != i2) {
        rb_ary_store(ary, i2, v);
    }
    i2++;
    }

    if (RARRAY_LEN(ary) == i2) return Qnil;
    if (i2 < RARRAY_LEN(ary))
    ARY_SET_LEN(ary, i2);
    return ary;
}

#repeated_combination(n) {|c| ... } ⇒ Object #repeated_combination(n) ⇒ Object

When invoked with a block, yields all repeated combinations of length n of elements from ary and then returns ary 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

Overloads:

  • #repeated_combination(n) {|c| ... } ⇒ Object

    Yields:

    • (c) 



# File 'array.c'

/*
 *  call-seq:
 *     ary.repeated_combination(n) { |c| block } -> ary
 *     ary.repeated_combination(n)               -> an_enumerator
 *
 * When invoked with a block, yields all repeated combinations of
 * length <i>n</i> of elements from <i>ary</i> and then returns
 * <i>ary</i> 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_ENUMERATOR(ary, 1, &num);   /* 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 < len; i++) {
        rb_yield(rb_ary_new3(1, RARRAY_PTR(ary)[i]));
    }
    }
    else if (len == 0) {
    /* yield nothing */
    }
    else {
    volatile VALUE t0 = tmpbuf(n, sizeof(long));
    long *p = (long*)RSTRING_PTR(t0);
    VALUE ary0 = ary_make_shared_copy(ary); /* private defensive copy of ary */
    RBASIC(ary0)->klass = 0;

    rcombinate0(len, n, p, 0, n, ary0); /* compute and yield repeated combinations */
    tmpbuf_discard(t0);
    RBASIC(ary0)->klass = rb_cArray;
    }
    return ary;
}

#repeated_permutation(n) {|p| ... } ⇒ Object #repeated_permutation(n) ⇒ Object

When invoked with a block, yield all repeated permutations of length n of the elements of ary, 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

Overloads:

  • #repeated_permutation(n) {|p| ... } ⇒ Object

    Yields:

    • (p) 



# File 'array.c'

/*
 *  call-seq:
 *     ary.repeated_permutation(n) { |p| block } -> ary
 *     ary.repeated_permutation(n)               -> an_enumerator
 *
 * When invoked with a block, yield all repeated permutations of length
 * <i>n</i> of the elements of <i>ary</i>, 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_ENUMERATOR(ary, 1, &num);      /* 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_PTR(ary)[i]));
    }
    }
    else {             /* this is the general case */
    volatile VALUE t0 = tmpbuf(r, sizeof(long));
    long *p = (long*)RSTRING_PTR(t0);
    VALUE ary0 = ary_make_shared_copy(ary); /* private defensive copy of ary */
    RBASIC(ary0)->klass = 0;

    rpermute0(n, r, p, 0, ary0); /* compute and yield repeated permutations */
    tmpbuf_discard(t0);
    RBASIC(ary0)->klass = rb_cArray;
    }
    return ary;
}

#replace(other_ary) ⇒ Object

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"]




# File 'array.c'

/*
 *  call-seq:
 *     ary.replace(other_ary)  -> ary
 *
 *  Replaces the contents of +self+ with the contents of
 *  <i>other_ary</i>, 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 *ptr;
        VALUE shared = 0;

        if (ARY_OWNS_HEAP_P(copy)) {
            xfree(RARRAY_PTR(copy));
        }
        else if (ARY_SHARED_P(copy)) {
            shared = ARY_SHARED(copy);
            FL_UNSET_SHARED(copy);
        }
        FL_SET_EMBED(copy);
        ptr = RARRAY_PTR(orig);
        MEMCPY(RARRAY_PTR(copy), ptr, VALUE, RARRAY_LEN(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)) {
            xfree(RARRAY_PTR(copy));
        }
        else {
            rb_ary_unshare_safe(copy);
        }
        FL_UNSET_EMBED(copy);
        ARY_SET_PTR(copy, RARRAY_PTR(orig));
        ARY_SET_LEN(copy, RARRAY_LEN(orig));
        rb_ary_set_shared(copy, shared);
    }
    return copy;
}

#reverse ⇒ Object

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

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




# File 'array.c'

/*
 *  call-seq:
 *     ary.reverse -> new_ary
 *
 *  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)
{
    VALUE dup = rb_ary_dup_setup(ary);
    long len = RARRAY_LEN(ary);

    if (len > 0) {
    VALUE *p1 = RARRAY_PTR(ary);
    VALUE *p2 = RARRAY_PTR(dup) + len - 1;
    do *p2-- = *p1++; while (--len > 0);
    }
    return dup;
}

#reverse! ⇒ Object

Reverses self in place.

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




# File 'array.c'

/*
 *  call-seq:
 *     ary.reverse!   -> ary
 *
 *  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| ... } ⇒ Object #reverse_each ⇒ Object

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

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

produces:

c b a

Overloads:

  • #reverse_each {|item| ... } ⇒ Object

    Yields:

    • (item) 



# File 'array.c'

/*
 *  call-seq:
 *     ary.reverse_each {|item| block }   -> ary
 *     ary.reverse_each                   -> an_enumerator
 *
 *  Same as <code>Array#each</code>, 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_ENUMERATOR(ary, 0, 0);
    len = RARRAY_LEN(ary);
    while (len--) {
    rb_yield(RARRAY_PTR(ary)[len]);
    if (RARRAY_LEN(ary) < len) {
        len = RARRAY_LEN(ary);
    }
    }
    return ary;
}

#rindex(obj) ⇒ Integer? #rindex {|item| ... } ⇒ Integer? #rindex ⇒ Object

Returns the index of the last object in self == to obj. If a block is given instead of an argument, returns first object for which block is 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

Overloads:




# File 'array.c'

/*
 *  call-seq:
 *     ary.rindex(obj)           ->  int or nil
 *     ary.rindex {|item| block} ->  int or nil
 *     ary.rindex                ->  an_enumerator
 *
 *  Returns the index of the last object in +self+
 *  <code>==</code> to <i>obj</i>. If a block is given instead of an
 *  argument, returns first object for which <em>block</em> is
 *  true, starting from the last object.
 *  Returns <code>nil</code> if no match is found.
 *  See also <code>Array#index</code>.
 *
 *  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);

    if (argc == 0) {
    RETURN_ENUMERATOR(ary, 0, 0);
    while (i--) {
        if (RTEST(rb_yield(RARRAY_PTR(ary)[i])))
        return LONG2NUM(i);
        if (i > RARRAY_LEN(ary)) {
        i = RARRAY_LEN(ary);
        }
    }
    return Qnil;
    }
    rb_scan_args(argc, argv, "1", &val);
    if (rb_block_given_p())
    rb_warn("given block not used");
    while (i--) {
    if (rb_equal(RARRAY_PTR(ary)[i], val))
        return LONG2NUM(i);
    if (i > RARRAY_LEN(ary)) {
        i = RARRAY_LEN(ary);
    }
    }
    return Qnil;
}

#rotate([n = 1]) ⇒ Object

Returns new array by rotating self, whose first element is the element at cnt in self. If cnt is negative then it rotates in counter direction.

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"]




# File 'array.c'

/*
 *  call-seq:
 *     ary.rotate([n = 1]) -> new_ary
 *
 *  Returns new array by rotating +self+, whose first element is the
 *  element at +cnt+ in +self+.  If +cnt+ is negative then it rotates
 *  in counter direction.
 *
 *     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, *ptr, *ptr2;
    long len, cnt = 1;

    switch (argc) {
      case 1: cnt = NUM2LONG(argv[0]);
      case 0: break;
      default: rb_scan_args(argc, argv, "01", NULL);
    }

    len = RARRAY_LEN(ary);
    rotated = rb_ary_dup_setup(ary);
    if (len > 0) {
    cnt = rotate_count(cnt, len);
    ptr = RARRAY_PTR(ary);
    ptr2 = RARRAY_PTR(rotated);
    len -= cnt;
    MEMCPY(ptr2, ptr + cnt, VALUE, len);
    MEMCPY(ptr2 + len, ptr, VALUE, cnt);
    }
    return rotated;
}

#rotate!(cnt = 1) ⇒ Object

Rotates self in place so that the element at cnt comes first, and returns self. If cnt is negative then it rotates in counter direction.

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"]




# File 'array.c'

/*
 *  call-seq:
 *     ary.rotate!(cnt=1) -> ary
 *
 *  Rotates +self+ in place so that the element at +cnt+ comes first,
 *  and returns +self+.  If +cnt+ is negative then it rotates in
 *  counter direction.
 *
 *     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 = 1;

    switch (argc) {
      case 1: n = NUM2LONG(argv[0]);
      case 0: break;
      default: rb_scan_args(argc, argv, "01", NULL);
    }
    rb_ary_rotate(ary, n);
    return ary;
}

#sample ⇒ Object #sample(n) ⇒ Object

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.

Overloads:




# File 'array.c'

/*
 *  call-seq:
 *     ary.sample        -> obj
 *     ary.sample(n)     -> 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
 *  <code>nil</code> and the second form returns an empty array.
 *
 */


static VALUE
rb_ary_sample(int argc, VALUE *argv, VALUE ary)
{
    VALUE nv, result, *ptr;
    long n, len, i, j, k, idx[10];

    len = RARRAY_LEN(ary);
    if (argc == 0) {
    if (len == 0) return Qnil;
    i = len == 1 ? 0 : (long)(rb_genrand_real()*len);
    return RARRAY_PTR(ary)[i];
    }
    rb_scan_args(argc, argv, "1", &nv);
    n = NUM2LONG(nv);
    if (n < 0) rb_raise(rb_eArgError, "negative sample number");
    ptr = RARRAY_PTR(ary);
    len = RARRAY_LEN(ary);
    if (n > len) n = len;
    switch (n) {
      case 0: return rb_ary_new2(0);
      case 1:
    return rb_ary_new4(1, &ptr[(long)(rb_genrand_real()*len)]);
      case 2:
    i = (long)(rb_genrand_real()*len);
    j = (long)(rb_genrand_real()*(len-1));
    if (j >= i) j++;
    return rb_ary_new3(2, ptr[i], ptr[j]);
      case 3:
    i = (long)(rb_genrand_real()*len);
    j = (long)(rb_genrand_real()*(len-1));
    k = (long)(rb_genrand_real()*(len-2));
    {
        long l = j, g = i;
        if (j >= i) l = i, g = ++j;
        if (k >= l && (++k >= g)) ++k;
    }
    return rb_ary_new3(3, ptr[i], ptr[j], ptr[k]);
    }
    if ((size_t)n < sizeof(idx)/sizeof(idx[0])) {
    VALUE *ptr_result;
    long sorted[sizeof(idx)/sizeof(idx[0])];
    sorted[0] = idx[0] = (long)(rb_genrand_real()*len);
    for (i=1; i<n; i++) {
        k = (long)(rb_genrand_real()*--len);
        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_new2(n);
    ptr_result = RARRAY_PTR(result);
    for (i=0; i<n; i++) {
        ptr_result[i] = ptr[idx[i]];
    }
    }
    else {
    VALUE *ptr_result;
    result = rb_ary_new4(len, ptr);
    ptr_result = RARRAY_PTR(result);
    RB_GC_GUARD(ary);
    for (i=0; i<n; i++) {
        j = (long)(rb_genrand_real()*(len-i)) + i;
        nv = ptr_result[j];
        ptr_result[j] = ptr_result[i];
        ptr_result[i] = nv;
    }
    }
    ARY_SET_LEN(result, n);

    return result;
}

#select {|item| ... } ⇒ Object #select ⇒ Object

Invokes the block passing in successive elements from self, returning an array containing those elements for which the block returns a true value (equivalent to Enumerable#select).

If no block is given, an enumerator is returned instead.

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

Overloads:

  • #select {|item| ... } ⇒ Object

    Yields:

    • (item) 



# File 'array.c'

/*
 *  call-seq:
 *     ary.select {|item| block } -> new_ary
 *     ary.select                 -> an_enumerator
 *
 *  Invokes the block passing in successive elements from +self+,
 *  returning an array containing those elements for which the block
 *  returns a true value (equivalent to <code>Enumerable#select</code>).
 *
 *  If no block is given, an enumerator is returned instead.
 *
 *     a = %w{ a b c d e f }
 *     a.select {|v| v =~ /[aeiou]/}   #=> ["a", "e"]
 */

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

    RETURN_ENUMERATOR(ary, 0, 0);
    result = rb_ary_new2(RARRAY_LEN(ary));
    for (i = 0; i < RARRAY_LEN(ary); i++) {
    if (RTEST(rb_yield(RARRAY_PTR(ary)[i]))) {
        rb_ary_push(result, rb_ary_elt(ary, i));
    }
    }
    return result;
}

#select! {|item| ... } ⇒ nil #select! ⇒ Object

Invokes the block passing in successive elements from self, deleting elements for which the block returns a false value. It returns self if changes were made, otherwise it returns nil. See also Array#keep_if

If no block is given, an enumerator is returned instead.

Overloads:

  • #select! {|item| ... } ⇒ nil

    Yields:

    • (item)

    Returns:

    • (nil) 



# File 'array.c'

/*
 *  call-seq:
 *     ary.select! {|item| block } -> new_ary or nil
 *     ary.select!                 -> an_enumerator
 *
 *  Invokes the block passing in successive elements from
 *  +self+, deleting elements for which the block returns a
 *  false value. It returns +self+ if changes were made,
 *  otherwise it returns <code>nil</code>.
 *  See also <code>Array#keep_if</code>
 *
 *  If no block is given, an enumerator is returned instead.
 *
 */

static VALUE
rb_ary_select_bang(VALUE ary)
{
    long i1, i2;

    RETURN_ENUMERATOR(ary, 0, 0);
    rb_ary_modify(ary);
    for (i1 = i2 = 0; i1 < RARRAY_LEN(ary); i1++) {
    VALUE v = RARRAY_PTR(ary)[i1];
    if (!RTEST(rb_yield(v))) continue;
    if (i1 != i2) {
        rb_ary_store(ary, i2, v);
    }
    i2++;
    }

    if (RARRAY_LEN(ary) == i2) return Qnil;
    if (i2 < RARRAY_LEN(ary))
    ARY_SET_LEN(ary, i2);
    return ary;
}

#shift ⇒ Object? #shift(n) ⇒ Object

Returns the first element of self and removes 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.

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

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

Overloads:




# File 'array.c'

/*
 *  call-seq:
 *     ary.shift    -> obj or nil
 *     ary.shift(n) -> new_ary
 *
 *  Returns the first element of +self+ and removes it (shifting all
 *  other elements down by one). Returns <code>nil</code> if the array
 *  is empty.
 *
 *  If a number _n_ is given, returns an array of the first n elements
 *  (or less) just like <code>array.slice!(0, n)</code> does.
 *
 *     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);
    if (ARY_SHARED_P(ary)) {
    if (ARY_SHARED_NUM(ARY_SHARED(ary)) == 1) {
        rb_mem_clear(RARRAY_PTR(ary), n);
    }
        ARY_INCREASE_PTR(ary, n);
    }
    else {
    MEMMOVE(RARRAY_PTR(ary), RARRAY_PTR(ary)+n, VALUE, RARRAY_LEN(ary)-n);
    }
    ARY_INCREASE_LEN(ary, -n);

    return result;
}

#shuffle ⇒ Object

Returns a new array with elements of this array shuffled.

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




# File 'array.c'

/*
 *  call-seq:
 *     ary.shuffle -> new_ary
 *
 *  Returns a new array with elements of this array shuffled.
 *
 *     a = [ 1, 2, 3 ]           #=> [1, 2, 3]
 *     a.shuffle                 #=> [2, 3, 1]
 */

static VALUE
rb_ary_shuffle(VALUE ary)
{
    ary = rb_ary_dup(ary);
    rb_ary_shuffle_bang(ary);
    return ary;
}

#shuffle! ⇒ Object

Shuffles elements in self in place.




# File 'array.c'

/*
 *  call-seq:
 *     ary.shuffle!        -> ary
 *
 *  Shuffles elements in +self+ in place.
 */


static VALUE
rb_ary_shuffle_bang(VALUE ary)
{
    VALUE *ptr;
    long i = RARRAY_LEN(ary);

    rb_ary_modify(ary);
    ptr = RARRAY_PTR(ary);
    while (i) {
    long j = (long)(rb_genrand_real()*i);
    VALUE tmp = ptr[--i];
    ptr[i] = ptr[j];
    ptr[j] = tmp;
    }
    return ary;
}

#[](index) ⇒ Object? #[](start, length) ⇒ nil #[](range) ⇒ nil #slice(index) ⇒ Object? #slice(start, length) ⇒ nil #slice(range) ⇒ nil

Element Reference---Returns the element at index, or returns a subarray starting at start and continuing for length elements, or returns a subarray specified by range. Negative indices count backward from the end of the array (-1 is the last element). Returns nil if the index (or starting index) are out of range.

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[5, 1]                #=> []
a[5..10]               #=> []

Overloads:

  • #[](index) ⇒ Object?

    Returns:

  • #[](start, length) ⇒ nil

    Returns:

    • (nil)
  • #[](range) ⇒ nil

    Returns:

    • (nil)
  • #slice(index) ⇒ Object?

    Returns:

  • #slice(start, length) ⇒ nil

    Returns:

    • (nil)
  • #slice(range) ⇒ nil

    Returns:

    • (nil) 



# File 'array.c'

/*
 *  call-seq:
 *     ary[index]                -> obj     or nil
 *     ary[start, length]        -> new_ary or nil
 *     ary[range]                -> new_ary or nil
 *     ary.slice(index)          -> obj     or nil
 *     ary.slice(start, length)  -> new_ary or nil
 *     ary.slice(range)          -> new_ary or nil
 *
 *  Element Reference---Returns the element at _index_,
 *  or returns a subarray starting at _start_ and
 *  continuing for _length_ elements, or returns a subarray
 *  specified by _range_.
 *  Negative indices count backward from the end of the
 *  array (-1 is the last element). Returns +nil+ if the index
 *  (or starting index) are out of range.
 *
 *     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[5, 1]                #=> []
 *     a[5..10]               #=> []
 *
 */

VALUE
rb_ary_aref(int argc, VALUE *argv, VALUE ary)
{
    VALUE arg;
    long beg, len;

    if (argc == 2) {
    beg = NUM2LONG(argv[0]);
    len = NUM2LONG(argv[1]);
    if (beg < 0) {
        beg += RARRAY_LEN(ary);
    }
    return rb_ary_subseq(ary, beg, len);
    }
    if (argc != 1) {
    rb_scan_args(argc, argv, "11", 0, 0);
    }
    arg = argv[0];
    /* special case - speeding up */
    if (FIXNUM_P(arg)) {
    return rb_ary_entry(ary, FIX2LONG(arg));
    }
    /* check if idx is Range */
    switch (rb_range_beg_len(arg, &beg, &len, RARRAY_LEN(ary), 0)) {
      case Qfalse:
    break;
      case Qnil:
    return Qnil;
      default:
    return rb_ary_subseq(ary, beg, len);
    }
    return rb_ary_entry(ary, NUM2LONG(arg));
}

#slice!(index) ⇒ Object? #slice!(start, length) ⇒ nil #slice!(range) ⇒ nil

Deletes the element(s) given by an index (optionally with a length) 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"]

Overloads:

  • #slice!(index) ⇒ Object?

    Returns:

  • #slice!(start, length) ⇒ nil

    Returns:

    • (nil)
  • #slice!(range) ⇒ nil

    Returns:

    • (nil) 



# File 'array.c'

/*
 *  call-seq:
 *     ary.slice!(index)         -> obj or nil
 *     ary.slice!(start, length) -> new_ary or nil
 *     ary.slice!(range)         -> new_ary or nil
 *
 *  Deletes the element(s) given by an index (optionally with a length)
 *  or by a range. Returns the deleted object (or objects), or
 *  <code>nil</code> 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_PTR(ary)+pos);
    RBASIC(arg2)->klass = rb_obj_class(ary);
    rb_ary_splice(ary, pos, len, Qundef);
    return arg2;
    }

    if (argc != 1) {
    /* error report */
    rb_scan_args(argc, argv, "11", NULL, NULL);
    }
    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 ⇒ Object #sort {|a, b| ... } ⇒ Object

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 implements a comparison between a and b, returning -1, 0, or +1. See also Enumerable#sort_by.

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

Overloads:

  • #sort {|a, b| ... } ⇒ Object

    Yields:

    • (a, b) 



# File 'array.c'

/*
 *  call-seq:
 *     ary.sort                   -> new_ary
 *     ary.sort {| a,b | block }  -> new_ary
 *
 *  Returns a new array created by sorting +self+. Comparisons for
 *  the sort will be done using the <code><=></code> operator or using
 *  an optional code block. The block implements a comparison between
 *  <i>a</i> and <i>b</i>, returning -1, 0, or +1. See also
 *  <code>Enumerable#sort_by</code>.
 *
 *     a = [ "d", "a", "e", "c", "b" ]
 *     a.sort                    #=> ["a", "b", "c", "d", "e"]
 *     a.sort {|x,y| y <=> x }   #=> ["e", "d", "c", "b", "a"]
 */

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

#sort! ⇒ Object #sort! {|a, b| ... } ⇒ Object

Sorts self. Comparisons for the sort will be done using the <=> operator or using an optional code block. The block implements a comparison between a and b, returning -1, 0, or +1. See also Enumerable#sort_by.

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

Overloads:

  • #sort! {|a, b| ... } ⇒ Object

    Yields:

    • (a, b) 



# File 'array.c'

/*
 *  call-seq:
 *     ary.sort!                   -> ary
 *     ary.sort! {| a,b | block }  -> ary
 *
 *  Sorts +self+. Comparisons for
 *  the sort will be done using the <code><=></code> operator or using
 *  an optional code block. The block implements a comparison between
 *  <i>a</i> and <i>b</i>, returning -1, 0, or +1. See also
 *  <code>Enumerable#sort_by</code>.
 *
 *     a = [ "d", "a", "e", "c", "b" ]
 *     a.sort                    #=> ["a", "b", "c", "d", "e"]
 *     a.sort {|x,y| y <=> x }   #=> ["e", "d", "c", "b", "a"]
 */

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;

    RBASIC(tmp)->klass = 0;
    data.ary = tmp;
    data.opt_methods = 0;
    data.opt_inited = 0;
    ruby_qsort(RARRAY_PTR(tmp), RARRAY_LEN(tmp), sizeof(VALUE),
           rb_block_given_p()?sort_1:sort_2, &data);

        if (ARY_EMBED_P(tmp)) {
            assert(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);
            MEMCPY(RARRAY_PTR(ary), ARY_EMBED_PTR(tmp), VALUE, ARY_EMBED_LEN(tmp));
            ARY_SET_LEN(ary, ARY_EMBED_LEN(tmp));
        }
        else {
            assert(!ARY_EMBED_P(tmp));
            if (ARY_HEAP_PTR(ary) == ARY_HEAP_PTR(tmp)) {
                assert(!ARY_EMBED_P(ary));
                FL_UNSET_SHARED(ary);
                ARY_SET_CAPA(ary, ARY_CAPA(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 {
                    xfree(ARY_HEAP_PTR(ary));
                }
                ARY_SET_PTR(ary, RARRAY_PTR(tmp));
                ARY_SET_HEAP_LEN(ary, RARRAY_LEN(tmp));
                ARY_SET_CAPA(ary, ARY_CAPA(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(tmp)->klass = rb_cArray;
    }
    return ary;
}

#sort_by! {|obj| ... } ⇒ Object #sort_by! ⇒ Object

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

If no block is given, an enumerator is returned instead.

Overloads:

  • #sort_by! {|obj| ... } ⇒ Object

    Yields:

    • (obj) 



# File 'array.c'

/*
 *  call-seq:
 *     ary.sort_by! {| obj | block }    -> ary
 *     ary.sort_by!                     -> an_enumerator
 *
 *  Sorts +self+ in place using a set of keys generated by mapping the
 *  values in +self+ through the given block.
 *
 *  If no block is given, an enumerator is returned instead.
 *
 */

static VALUE
rb_ary_sort_by_bang(VALUE ary)
{
    VALUE sorted;

    RETURN_ENUMERATOR(ary, 0, 0);
    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;
}

#take(n) ⇒ Object

Returns first n elements from ary.

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




# File 'array.c'

/*
 *  call-seq:
 *     ary.take(n)               -> new_ary
 *
 *  Returns first n elements from <i>ary</i>.
 *
 *     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 {|arr| ... } ⇒ Object #take_while ⇒ Object

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.

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

Overloads:

  • #take_while {|arr| ... } ⇒ Object

    Yields:

    • (arr) 



# File 'array.c'

/*
 *  call-seq:
 *     ary.take_while {|arr| block }   -> new_ary
 *     ary.take_while                  -> an_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.
 *
 *     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_PTR(ary)[i]))) break;
    }
    return rb_ary_take(ary, LONG2FIX(i));
}

#to_a ⇒ Object

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




# File 'array.c'

/*
 *  call-seq:
 *     ary.to_a     -> ary
 *
 *  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 ⇒ Object

Returns self.




# File 'array.c'

/*
 *  call-seq:
 *     ary.to_ary -> ary
 *
 *  Returns +self+.
 */

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

#transpose ⇒ Object

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]]




# File 'array.c'

/*
 *  call-seq:
 *     ary.transpose -> new_ary
 *
 *  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]]
 */

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

#uniq ⇒ Object

Returns a new array by removing duplicate values in self.

a = [ "a", "a", "b", "b", "c" ]
a.uniq   #=> ["a", "b", "c"]
c = [ "a:def", "a:xyz", "b:abc", "b:xyz", "c:jkl" ]
c.uniq {|s| s[/^\w+/]}  #=> [ "a:def", "b:abc", "c:jkl" ]




# File 'array.c'

/*
 *  call-seq:
 *     ary.uniq   -> new_ary
 *
 *  Returns a new array by removing duplicate values in +self+.
 *
 *     a = [ "a", "a", "b", "b", "c" ]
 *     a.uniq   #=> ["a", "b", "c"]
 *     c = [ "a:def", "a:xyz", "b:abc", "b:xyz", "c:jkl" ]
 *     c.uniq {|s| s[/^\w+/]}  #=> [ "a:def", "b:abc", "c:jkl" ]
 */

static VALUE
rb_ary_uniq(VALUE ary)
{
    VALUE hash, uniq, v;
    long i;

    if (RARRAY_LEN(ary) <= 1)
        return rb_ary_dup(ary);
    if (rb_block_given_p()) {
    hash = ary_make_hash_by(ary);
    uniq = ary_new(rb_obj_class(ary), RHASH_SIZE(hash));
    st_foreach(RHASH_TBL(hash), push_value, uniq);
    }
    else {
    hash = ary_make_hash(ary);
    uniq = ary_new(rb_obj_class(ary), RHASH_SIZE(hash));
    for (i=0; i<RARRAY_LEN(ary); i++) {
        st_data_t vv = (st_data_t)(v = rb_ary_elt(ary, i));
        if (st_delete(RHASH_TBL(hash), &vv, 0)) {
        rb_ary_push(uniq, v);
        }
    }
    }
    ary_recycle_hash(hash);

    return uniq;
}

#uniq! ⇒ nil

Removes duplicate elements from self. 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 = [ "a:def", "a:xyz", "b:abc", "b:xyz", "c:jkl" ]
c.uniq! {|s| s[/^\w+/]}  #=> [ "a:def", "b:abc", "c:jkl" ]

Returns:

  • (nil) 



# File 'array.c'

/*
 *  call-seq:
 *     ary.uniq! -> ary or nil
 *
 *  Removes duplicate elements from +self+.
 *  Returns <code>nil</code> 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 = [ "a:def", "a:xyz", "b:abc", "b:xyz", "c:jkl" ]
 *     c.uniq! {|s| s[/^\w+/]}  #=> [ "a:def", "b:abc", "c:jkl" ]
 */

static VALUE
rb_ary_uniq_bang(VALUE ary)
{
    VALUE hash, v;
    long i, j;

    rb_ary_modify_check(ary);
    if (RARRAY_LEN(ary) <= 1)
        return Qnil;
    if (rb_block_given_p()) {
    hash = ary_make_hash_by(ary);
    if (RARRAY_LEN(ary) == (i = RHASH_SIZE(hash))) {
        return Qnil;
    }
    ary_resize_capa(ary, i);
    ARY_SET_LEN(ary, 0);
    st_foreach(RHASH_TBL(hash), push_value, ary);
    }
    else {
    hash = ary_make_hash(ary);
    if (RARRAY_LEN(ary) == (long)RHASH_SIZE(hash)) {
        return Qnil;
    }
    for (i=j=0; i<RARRAY_LEN(ary); i++) {
        st_data_t vv = (st_data_t)(v = rb_ary_elt(ary, i));
        if (st_delete(RHASH_TBL(hash), &vv, 0)) {
        rb_ary_store(ary, j++, v);
        }
    }
    ARY_SET_LEN(ary, j);
    }
    ary_recycle_hash(hash);

    return ary;
}

#unshift(obj, ...) ⇒ Object

Prepends objects to the front of self, moving other elements upwards.

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




# File 'array.c'

/*
 *  call-seq:
 *     ary.unshift(obj, ...)  -> ary
 *
 *  Prepends objects to the front of +self+,
 *  moving other elements upwards.
 *
 *     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;

    rb_ary_modify(ary);
    if (argc == 0) return ary;
    if (ARY_CAPA(ary) <= (len = RARRAY_LEN(ary)) + argc) {
    ary_double_capa(ary, len + argc);
    }

    /* sliding items */
    MEMMOVE(RARRAY_PTR(ary) + argc, RARRAY_PTR(ary), VALUE, len);
    MEMCPY(RARRAY_PTR(ary), argv, VALUE, argc);
    ARY_INCREASE_LEN(ary, argc);

    return ary;
}

#values_at(selector, ...) ⇒ Object

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)
a.values_at(1, 3, 5, 7)
a.values_at(-1, -3, -5, -7)
a.values_at(1..3, 2...5)




# File 'array.c'

/*
 *  call-seq:
 *     ary.values_at(selector,... )  -> new_ary
 *
 *  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 <code>Array#select</code>.
 *
 *     a = %w{ a b c d e f }
 *     a.values_at(1, 3, 5)
 *     a.values_at(1, 3, 5, 7)
 *     a.values_at(-1, -3, -5, -7)
 *     a.values_at(1..3, 2...5)
 */

static VALUE
rb_ary_values_at(int argc, VALUE *argv, VALUE ary)
{
    return rb_get_values_at(ary, RARRAY_LEN(ary), argc, argv, rb_ary_entry);
}

#zip(arg, ...) ⇒ Object #zip(arg, ...) {|arr| ... } ⇒ nil

Converts any arguments to arrays, then merges elements of self with corresponding elements from each argument. This generates a sequence of self.size n-element arrays, where n is one more that the count of arguments. If the size of any argument is less than enumObj.size, 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]]

Overloads:

  • #zip(arg, ...) {|arr| ... } ⇒ nil

    Yields:

    • (arr)

    Returns:

    • (nil) 



# File 'array.c'

/*
 *  call-seq:
 *     ary.zip(arg, ...)                   -> new_ary
 *     ary.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 <code>self.size</code> <em>n</em>-element
 *  arrays, where <em>n</em> is one more that the count of arguments. If
 *  the size of any argument is less than <code>enumObj.size</code>,
 *  <code>nil</code> 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;
    VALUE result = Qnil;

    len = RARRAY_LEN(ary);
    for (i=0; i<argc; i++) {
    argv[i] = take_items(argv[i], len);
    }
    if (!rb_block_given_p()) {
    result = rb_ary_new2(len);
    }

    for (i=0; i<RARRAY_LEN(ary); i++) {
    VALUE tmp = rb_ary_new2(argc+1);

    rb_ary_push(tmp, rb_ary_elt(ary, i));
    for (j=0; j<argc; j++) {
        rb_ary_push(tmp, rb_ary_elt(argv[j], i));
    }
    if (NIL_P(result)) {
        rb_yield(tmp);
    }
    else {
        rb_ary_push(result, tmp);
    }
    }
    return result;
}

#|(other_ary) ⇒ Object

Set Union---Returns a new array by joining this array with other_ary, removing duplicates.

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




# File 'array.c'

/*
 *  call-seq:
 *     ary | other_ary     -> new_ary
 *
 *  Set Union---Returns a new array by joining this array with
 *  <i>other_ary</i>, removing duplicates.
 *
 *     [ "a", "b", "c" ] | [ "c", "d", "a" ]
 *            #=> [ "a", "b", "c", "d" ]
 */

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

    ary2 = to_ary(ary2);
    ary3 = rb_ary_new2(RARRAY_LEN(ary1)+RARRAY_LEN(ary2));
    hash = ary_add_hash(ary_make_hash(ary1), ary2);

    for (i=0; i<RARRAY_LEN(ary1); i++) {
    v = vv = rb_ary_elt(ary1, i);
    if (st_delete(RHASH_TBL(hash), (st_data_t*)&vv, 0)) {
        rb_ary_push(ary3, v);
    }
    }
    for (i=0; i<RARRAY_LEN(ary2); i++) {
    v = vv = rb_ary_elt(ary2, i);
    if (st_delete(RHASH_TBL(hash), (st_data_t*)&vv, 0)) {
        rb_ary_push(ary3, v);
    }
    }
    ary_recycle_hash(hash);
    return ary3;
}