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.

Creating Arrays

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

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

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

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

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

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

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

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

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

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

Array(=> “a”, :b => “b”) #=> [[:a, “a”], [:b, “b”]]

Example Usage

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

Some of the more common ones are illustrated below.

Accessing Elements

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

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

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

arr.at(0) #=> 1

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

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

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

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

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

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

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

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

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

Obtaining Information about an Array

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

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

To check whether an array contains any elements at all

browsers.empty? #=> false

To check whether a particular item is included in the array

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

Adding Items to Arrays

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

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

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

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

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

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

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

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

Removing Items from an Array

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

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

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

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

To delete an element at a particular index:

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

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

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

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

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

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

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

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

Iterating over Arrays

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

Note that this operation leaves the array unchanged.

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

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

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

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

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

Selecting Items from an Array

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

Non-destructive Selection

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

Destructive Selection

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

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

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

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

Class Method Summary collapse

Instance Method Summary collapse

Methods included from Enumerable

#chain, #chunk, #chunk_while, #collect_concat, #detect, #each_cons, #each_entry, #each_slice, #each_with_index, #each_with_object, #entries, #filter_map, #find, #find_all, #flat_map, #grep, #grep_v, #group_by, #inject, #lazy, #max_by, #member?, #min_by, #minmax_by, #partition, #reduce, #slice_after, #slice_before, #slice_when, #sort_by, #tally

Constructor Details

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

Returns a new array.

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

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

first_array = ["Matz", "Guido"]

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

first_array.equal? second_array       #=> false

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

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

Common gotchas

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

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

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

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

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

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

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

Overloads:



1001
1002
1003
1004
1005
1006
1007
1008
1009
1010
1011
1012
1013
1014
1015
1016
1017
1018
1019
1020
1021
1022
1023
1024
1025
1026
1027
1028
1029
1030
1031
1032
1033
1034
1035
1036
1037
1038
1039
1040
1041
1042
1043
1044
1045
1046
1047
1048
1049
1050
1051
1052
1053
1054
1055
1056
 
# File 'array.c', line 1001

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

    rb_ary_modify(ary);
    if (argc == 0) {
        if (ARY_OWNS_HEAP_P(ary) && ARY_HEAP_PTR(ary) != NULL) {
            ary_heap_free(ary);
  }
        rb_ary_unshare_safe(ary);
        FL_SET_EMBED(ary);
  ARY_SET_EMBED_LEN(ary, 0);
  if (rb_block_given_p()) {
      rb_warning("given block not used");
  }
  return ary;
    }
    rb_scan_args(argc, argv, "02", &size, &val);
    if (argc == 1 && !FIXNUM_P(size)) {
  val = rb_check_array_type(size);
  if (!NIL_P(val)) {
      rb_ary_replace(ary, val);
      return ary;
  }
    }

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

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

Class Method Details

.[](*args) ⇒ Object

Returns a new array populated with the given objects.

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



1066
1067
1068
1069
1070
1071
1072
1073
1074
1075
1076
 
# File 'array.c', line 1066

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

    return ary;
}

.try_convert(obj) ⇒ Array?

Tries to convert obj into an array, using the to_ary method. Returns the converted array or nil if obj cannot be converted. 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



939
940
941
942
943
 
# File 'array.c', line 939

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

Instance Method Details

#&(other_ary) ⇒ Array

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

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

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

See also Array#uniq.



4628
4629
4630
4631
4632
4633
4634
4635
4636
4637
4638
4639
4640
4641
4642
4643
4644
4645
4646
4647
4648
4649
4650
4651
4652
4653
4654
4655
4656
4657
4658
4659
4660
4661
 
# File 'array.c', line 4628

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

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

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

    hash = ary_make_hash(ary2);

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

    return ary3;
}

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

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

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

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



4091
4092
4093
4094
4095
4096
4097
4098
4099
4100
4101
4102
4103
4104
4105
4106
4107
4108
4109
4110
4111
4112
4113
4114
4115
4116
4117
4118
4119
4120
4121
4122
4123
4124
4125
4126
4127
4128
4129
4130
4131
4132
4133
 
# File 'array.c', line 4091

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

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

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

    ary2 = ary_new(rb_obj_class(ary), len);
    ARY_SET_LEN(ary2, len);

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

#+(other_ary) ⇒ Array

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

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

Note that

x += y

is the same as

x = x + y

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

See also Array#concat.



3999
4000
4001
4002
4003
4004
4005
4006
4007
4008
4009
4010
4011
4012
4013
4014
4015
 
# File 'array.c', line 3999

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

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

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

#-(other_ary) ⇒ Array

Array Difference

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

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

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

Note that while 1 and 2 were only present once in the array argument, and were present twice in the receiver array, all occurrences of each Integer are removed in the returned array.

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

See also Array#difference.



4518
4519
4520
4521
4522
4523
4524
4525
4526
4527
4528
4529
4530
4531
4532
4533
4534
4535
4536
4537
4538
4539
4540
4541
4542
4543
4544
 
# File 'array.c', line 4518

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

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

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

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

#<<(obj) ⇒ Array

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

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



1194
1195
1196
1197
1198
1199
1200
1201
1202
1203
1204
1205
 
# File 'array.c', line 1194

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

#<=>(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 the <=> operator).

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

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

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

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



4419
4420
4421
4422
4423
4424
4425
4426
4427
4428
4429
4430
4431
4432
4433
4434
 
# File 'array.c', line 4419

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) ⇒ Boolean

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

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



4252
4253
4254
4255
4256
4257
4258
4259
4260
4261
4262
4263
4264
4265
 
# File 'array.c', line 4252

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

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

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

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

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

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



1573
1574
1575
1576
1577
1578
1579
1580
1581
 
# File 'array.c', line 1573

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

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

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

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

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

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

See also Array#push, and Array#unshift.

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



2028
2029
2030
2031
2032
2033
2034
2035
2036
2037
2038
2039
2040
2041
2042
2043
2044
2045
2046
2047
2048
2049
2050
2051
2052
2053
2054
2055
2056
2057
2058
2059
 
# File 'array.c', line 2028

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

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

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

#all? {|obj| ... } ⇒ Boolean #all?(pattern) ⇒ Boolean

See also Enumerable#all?

Overloads:

  • #all? {|obj| ... } ⇒ Boolean

    Yields:

    • (obj) 


6366
6367
6368
6369
6370
6371
6372
6373
6374
6375
6376
6377
6378
6379
6380
6381
6382
6383
6384
6385
6386
6387
6388
6389
6390
6391
6392
 
# File 'array.c', line 6366

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

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

#any? {|obj| ... } ⇒ Boolean #any?(pattern) ⇒ Boolean

See also Enumerable#any?

Overloads:

  • #any? {|obj| ... } ⇒ Boolean

    Yields:

    • (obj) 


6330
6331
6332
6333
6334
6335
6336
6337
6338
6339
6340
6341
6342
6343
6344
6345
6346
6347
6348
6349
6350
6351
6352
6353
6354
6355
6356
 
# File 'array.c', line 6330

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

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

#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



4155
4156
4157
4158
4159
4160
4161
4162
4163
4164
4165
4166
4167
4168
 
# File 'array.c', line 4155

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

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

#at(index) ⇒ Object?

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"



1628
1629
1630
1631
1632
 
# File 'array.c', line 1628

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

#bsearch {|x| ... } ⇒ Object

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

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

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

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

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

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

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

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

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

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

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

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

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

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

Yields:

  • (x) 


2928
2929
2930
2931
2932
2933
2934
2935
2936
2937
 
# File 'array.c', line 2928

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

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

#bsearch_index {|x| ... } ⇒ Integer?

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

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

Yields:

  • (x) 


2952
2953
2954
2955
2956
2957
2958
2959
2960
2961
2962
2963
2964
2965
2966
2967
2968
2969
2970
2971
2972
2973
2974
2975
2976
2977
2978
2979
2980
2981
2982
2983
2984
2985
2986
2987
2988
2989
2990
2991
2992
2993
2994
2995
2996
2997
 
# File 'array.c', line 2952

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

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

#clear ⇒ Array

Removes all elements from self.

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



3861
3862
3863
3864
3865
3866
3867
3868
3869
3870
3871
3872
3873
3874
3875
3876
3877
3878
3879
3880
 
# File 'array.c', line 3861

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

#collect {|item| ... } ⇒ Array #map {|item| ... } ⇒ Array #collect ⇒ Enumerator #map ⇒ Enumerator

Invokes the given block once for each element of self.

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

See also Enumerable#collect.

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

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

Overloads:

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

    Yields:

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

    Yields:

    • (item) 


3056
3057
3058
3059
3060
3061
3062
3063
3064
3065
3066
3067
3068
 
# File 'array.c', line 3056

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

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

#collect! {|item| ... } ⇒ Array #map! {|item| ... } ⇒ Array #collect! ⇒ Enumerator #map! ⇒ Enumerator

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

See also Enumerable#collect.

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

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

Overloads:

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

    Yields:

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

    Yields:

    • (item) 


3092
3093
3094
3095
3096
3097
3098
3099
3100
3101
3102
3103
 
# File 'array.c', line 3092

static VALUE
rb_ary_collect_bang(VALUE ary)
{
    long i;

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

#combination(n) {|c| ... } ⇒ Array #combination(n) ⇒ Enumerator

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

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

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

Examples:

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

Overloads:

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

    Yields:

    • (c) 


5865
5866
5867
5868
5869
5870
5871
5872
5873
5874
5875
5876
5877
5878
5879
5880
5881
5882
5883
5884
5885
5886
5887
5888
5889
5890
5891
5892
5893
5894
5895
 
# File 'array.c', line 5865

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

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

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

#compact ⇒ Array

Returns a copy of self with all nil elements removed.

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



5088
5089
5090
5091
5092
5093
5094
 
# File 'array.c', line 5088

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

#compact! ⇒ Array?

Removes nil elements from the array.

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

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



5055
5056
5057
5058
5059
5060
5061
5062
5063
5064
5065
5066
5067
5068
5069
5070
5071
5072
5073
5074
5075
5076
 
# File 'array.c', line 5055

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

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

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

    return ary;
}

#concat(other_ary1, other_ary2, ...) ⇒ Array

Appends the elements of other_arys to self.

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

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

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

See also Array#+.



4047
4048
4049
4050
4051
4052
4053
4054
4055
4056
4057
4058
4059
4060
4061
4062
4063
4064
4065
4066
 
# File 'array.c', line 4047

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

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

    ary_verify(ary);
    return ary;
}

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

Returns the number of elements.

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

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

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

Overloads:

  • #count {|item| ... } ⇒ Integer

    Yields:

    • (item) 


5117
5118
5119
5120
5121
5122
5123
5124
5125
5126
5127
5128
5129
5130
5131
5132
5133
5134
5135
5136
5137
5138
5139
5140
5141
5142
5143
5144
5145
 
# File 'array.c', line 5117

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

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

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

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

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

    return LONG2NUM(n);
}

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

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

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

Returns nil if the loop has finished without getting interrupted.

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

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

Overloads:

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

    Yields:

    • (obj) 


5601
5602
5603
5604
5605
5606
5607
5608
5609
5610
5611
5612
5613
5614
5615
5616
5617
5618
5619
5620
5621
5622
5623
 
# File 'array.c', line 5601

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

    rb_check_arity(argc, 0, 1);

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

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

#deconstruct ⇒ Object 



6674
6675
6676
6677
6678
 
# File 'array.c', line 6674

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

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

Deletes all items from self that are equal to obj.

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

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

a = [ "a", "b", "b", "b", "c" ]
a.delete("b")                   #=> "b"
a                               #=> ["a", "c"]
a.delete("z")                   #=> nil
a.delete("z") {"not found"}     #=> "not found"

Overloads:

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

    Yields:



3364
3365
3366
3367
3368
3369
3370
3371
3372
3373
3374
3375
3376
3377
3378
3379
3380
3381
3382
3383
3384
3385
3386
3387
3388
3389
3390
3391
3392
3393
 
# File 'array.c', line 3364

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

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

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

    ary_resize_smaller(ary, i2);

    ary_verify(ary);
    return v;
}

#delete_at(index) ⇒ 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 = ["ant", "bat", "cat", "dog"]
a.delete_at(2)    #=> "cat"
a                 #=> ["ant", "bat", "dog"]
a.delete_at(99)   #=> nil



3455
3456
3457
3458
3459
 
# File 'array.c', line 3455

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

#delete_if {|item| ... } ⇒ Array #delete_if ⇒ Enumerator

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

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

See also Array#reject!

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

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

Overloads:

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

    Yields:

    • (item) 


3638
3639
3640
3641
3642
3643
3644
3645
 
# File 'array.c', line 3638

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

#difference(other_ary1, other_ary2, ...) ⇒ Array

Array Difference

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

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

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

Note that while 1 and 2 were only present once in the array argument, and were present twice in the receiver array, all occurrences of each Integer are removed in the returned array.

Multiple array arguments can be supplied and all occurrences of any element in those supplied arrays that match the receiver will be removed from the returned array.

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

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

See also Array#-.



4575
4576
4577
4578
4579
4580
4581
4582
4583
4584
4585
4586
4587
4588
4589
4590
4591
4592
4593
4594
4595
4596
4597
4598
4599
4600
4601
4602
4603
4604
4605
4606
4607
4608
4609
 
# File 'array.c', line 4575

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

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

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

    ALLOCV_END(t0);

    return ary_diff;
}

#dig(idx, ...) ⇒ Object

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

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

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



6492
6493
6494
6495
6496
6497
6498
6499
6500
 
# File 'array.c', line 6492

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

#drop(n) ⇒ Array

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

If a negative number is given, raises an ArgumentError.

See also Array#take

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



6278
6279
6280
6281
6282
6283
6284
6285
6286
6287
6288
6289
6290
 
# File 'array.c', line 6278

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

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

#drop_while {|obj| ... } ⇒ Array #drop_while ⇒ Enumerator

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

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

See also Array#take_while

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

Overloads:

  • #drop_while {|obj| ... } ⇒ Array

    Yields:

    • (obj) 


6310
6311
6312
6313
6314
6315
6316
6317
6318
6319
6320
 
# File 'array.c', line 6310

static VALUE
rb_ary_drop_while(VALUE ary)
{
    long i;

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

#each {|item| ... } ⇒ Array #each ⇒ Enumerator

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

If no block is given, an Enumerator is returned.

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

produces:

a -- b -- c --

Overloads:

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

    Yields:

    • (item) 


2128
2129
2130
2131
2132
2133
2134
2135
2136
2137
2138
 
# File 'array.c', line 2128

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

#each_index {|index| ... } ⇒ Array #each_index ⇒ Enumerator

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

An Enumerator is returned if no block is given.

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

produces:

0 -- 1 -- 2 --

Overloads:

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

    Yields:



2158
2159
2160
2161
2162
2163
2164
2165
2166
2167
2168
 
# File 'array.c', line 2158

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

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

#empty? ⇒ Boolean

Returns true if self contains no elements.

[].empty?   #=> true



2229
2230
2231
2232
2233
2234
2235
 
# File 'array.c', line 2229

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 (according to Object#eql?).



4288
4289
4290
4291
4292
4293
4294
4295
4296
 
# File 'array.c', line 4288

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

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

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

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

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

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

Overloads:

  • #fetch(index) {|index| ... } ⇒ Object

    Yields:



1713
1714
1715
1716
1717
1718
1719
1720
1721
1722
1723
1724
1725
1726
1727
1728
1729
1730
1731
1732
1733
1734
1735
1736
1737
1738
1739
 
# File 'array.c', line 1713

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

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

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

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

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

A start of nil is equivalent to zero.

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

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

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

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

Overloads:

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

    Yields:

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

    Yields:

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

    Yields:



3912
3913
3914
3915
3916
3917
3918
3919
3920
3921
3922
3923
3924
3925
3926
3927
3928
3929
3930
3931
3932
3933
3934
3935
3936
3937
3938
3939
3940
3941
3942
3943
3944
3945
3946
3947
3948
3949
3950
3951
3952
3953
3954
3955
3956
3957
3958
3959
3960
3961
3962
3963
3964
3965
3966
3967
3968
3969
3970
3971
3972
3973
3974
 
# File 'array.c', line 3912

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

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

    if (item == Qundef) {
  VALUE v;
  long i;

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

#select {|item| ... } ⇒ Array #select ⇒ Enumerator #filter {|item| ... } ⇒ Array #filter ⇒ Enumerator

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

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

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

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

See also Enumerable#select.

Array#filter is an alias for Array#select.

Overloads:

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

    Yields:

    • (item)
  • #filter {|item| ... } ⇒ Array

    Yields:

    • (item) 


3212
3213
3214
3215
3216
3217
3218
3219
3220
3221
3222
3223
3224
3225
3226
 
# File 'array.c', line 3212

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

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

#select! {|item| ... } ⇒ Array? #select! ⇒ Enumerator #filter! {|item| ... } ⇒ Array? #filter! ⇒ Enumerator

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

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

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

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

See also Array#keep_if.

Array#filter! is an alias for Array#select!.

Overloads:

  • #select! {|item| ... } ⇒ Array?

    Yields:

    • (item)
  • #filter! {|item| ... } ⇒ Array?

    Yields:

    • (item) 


3293
3294
3295
3296
3297
3298
3299
3300
3301
3302
3303
3304
 
# File 'array.c', line 3293

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

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

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

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

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

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

See also Array#rindex.

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

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

Overloads:

  • #find_index {|item| ... } ⇒ Integer?

    Yields:

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

    Yields:

    • (item) 


1767
1768
1769
1770
1771
1772
1773
1774
1775
1776
1777
1778
1779
1780
1781
1782
1783
1784
1785
1786
1787
1788
1789
1790
1791
1792
1793
 
# File 'array.c', line 1767

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

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

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

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

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



1649
1650
1651
1652
1653
1654
1655
1656
1657
1658
1659
 
# File 'array.c', line 1649

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

#flatten ⇒ Array #flatten(level) ⇒ Array

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

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

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

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



5295
5296
5297
5298
5299
5300
5301
5302
5303
5304
5305
5306
5307
5308
5309
5310
5311
5312
 
# File 'array.c', line 5295

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

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

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

    return result;
}

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

Flattens self in place.

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

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

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



5251
5252
5253
5254
5255
5256
5257
5258
5259
5260
5261
5262
5263
5264
5265
5266
5267
5268
5269
5270
5271
 
# File 'array.c', line 5251

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

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

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

    return ary;
}

#hash ⇒ Integer

Compute a hash-code for this array.

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

See also Object#hash.



4310
4311
4312
4313
4314
4315
4316
4317
4318
4319
4320
4321
4322
4323
4324
4325
 
# File 'array.c', line 4310

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

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

#include?(object) ⇒ Boolean

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

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



4339
4340
4341
4342
4343
4344
4345
4346
4347
4348
4349
4350
4351
4352
 
# File 'array.c', line 4339

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

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

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

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

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

See also Array#rindex.

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

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

Overloads:

  • #find_index {|item| ... } ⇒ Integer?

    Yields:

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

    Yields:

    • (item) 


1767
1768
1769
1770
1771
1772
1773
1774
1775
1776
1777
1778
1779
1780
1781
1782
1783
1784
1785
1786
1787
1788
1789
1790
1791
1792
1793
 
# File 'array.c', line 1767

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

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

#replace(other_ary) ⇒ Array #initialize_copy(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"]



3810
3811
3812
3813
3814
3815
3816
3817
3818
3819
3820
3821
3822
3823
3824
3825
3826
3827
3828
3829
3830
3831
3832
3833
3834
3835
3836
3837
3838
3839
3840
3841
3842
3843
3844
3845
3846
3847
3848
3849
 
# File 'array.c', line 3810

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

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

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

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

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

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

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



2077
2078
2079
2080
2081
2082
2083
2084
2085
2086
2087
2088
2089
2090
2091
2092
2093
2094
2095
2096
2097
2098
2099
 
# File 'array.c', line 2077

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

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

#inspect ⇒ String #to_s ⇒ String Also known as: to_s

Creates a string representation of self, by calling #inspect on each element.

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



2445
2446
2447
2448
2449
2450
 
# File 'array.c', line 2445

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

#intersection(other_ary1, other_ary2, ...) ⇒ Array

Set Intersection — Returns a new array containing unique elements common to self and other_arys. Order is preserved from the original array.

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

[ 1, 1, 3, 5 ].intersection([ 3, 2, 1 ])                    # => [ 1, 3 ]
[ "a", "b", "z" ].intersection([ "a", "b", "c" ], [ "b" ])  # => [ "b" ]
[ "a" ].intersection #=> [ "a" ]

See also Array#&.



4680
4681
4682
4683
4684
4685
4686
4687
4688
4689
4690
4691
 
# File 'array.c', line 4680

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

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

    return result;
}

#join(separator = $,) ⇒ String

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

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

For nested arrays, join is applied recursively:

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



2401
2402
2403
2404
2405
2406
2407
2408
2409
2410
2411
2412
2413
2414
 
# File 'array.c', line 2401

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

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

    return rb_ary_join(ary, sep);
}

#keep_if {|item| ... } ⇒ Array #keep_if ⇒ Enumerator

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

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

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

See also Array#select!.

Overloads:

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

    Yields:

    • (item) 


3323
3324
3325
3326
3327
3328
3329
 
# File 'array.c', line 3323

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

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

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

See also Array#first for the opposite effect.

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



1676
1677
1678
1679
1680
1681
1682
1683
1684
1685
1686
1687
 
# File 'array.c', line 1676

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

#length ⇒ Integer Also known as: size

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

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



2213
2214
2215
2216
2217
2218
 
# File 'array.c', line 2213

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

#collect {|item| ... } ⇒ Array #map {|item| ... } ⇒ Array #collect ⇒ Enumerator #map ⇒ Enumerator

Invokes the given block once for each element of self.

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

See also Enumerable#collect.

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

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

Overloads:

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

    Yields:

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

    Yields:

    • (item) 


3056
3057
3058
3059
3060
3061
3062
3063
3064
3065
3066
3067
3068
 
# File 'array.c', line 3056

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

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

#collect! {|item| ... } ⇒ Array #map! {|item| ... } ⇒ Array #collect! ⇒ Enumerator #map! ⇒ Enumerator

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

See also Enumerable#collect.

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

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

Overloads:

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

    Yields:

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

    Yields:

    • (item) 


3092
3093
3094
3095
3096
3097
3098
3099
3100
3101
3102
3103
 
# File 'array.c', line 3092

static VALUE
rb_ary_collect_bang(VALUE ary)
{
    long i;

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

#max ⇒ Object #max {|a, b| ... } ⇒ Object #max(n) ⇒ Array #max(n) {|a, b| ... } ⇒ Array

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

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

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

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

Overloads:

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

    Yields:

    • (a, b)
  • #max(n) {|a, b| ... } ⇒ Array

    Yields:

    • (a, b) 


4828
4829
4830
4831
4832
4833
4834
4835
4836
4837
4838
4839
4840
4841
4842
4843
4844
4845
4846
4847
4848
4849
4850
4851
4852
4853
4854
4855
4856
4857
 
# File 'array.c', line 4828

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

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

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

#min ⇒ Object #min {|a, b| ... } ⇒ Object #min(n) ⇒ Array #min(n) {|a, b| ... } ⇒ Array

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

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

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

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

Overloads:

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

    Yields:

    • (a, b)
  • #min(n) {|a, b| ... } ⇒ Array

    Yields:

    • (a, b) 


4881
4882
4883
4884
4885
4886
4887
4888
4889
4890
4891
4892
4893
4894
4895
4896
4897
4898
4899
4900
4901
4902
4903
4904
4905
4906
4907
4908
4909
4910
 
# File 'array.c', line 4881

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

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

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

#minmax ⇒ Array #minmax {|a, b| ... } ⇒ Array

Returns a two element array which contains the minimum and the maximum value in the array.

Can be given an optional block to override the default comparison method a <=> b.

Overloads:

  • #minmax {|a, b| ... } ⇒ Array

    Yields:

    • (a, b) 


4923
4924
4925
4926
4927
4928
4929
4930
 
# File 'array.c', line 4923

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

#none? {|obj| ... } ⇒ Boolean #none?(pattern) ⇒ Boolean

See also Enumerable#none?

Overloads:

  • #none? {|obj| ... } ⇒ Boolean

    Yields:

    • (obj) 


6402
6403
6404
6405
6406
6407
6408
6409
6410
6411
6412
6413
6414
6415
6416
6417
6418
6419
6420
6421
6422
6423
6424
6425
6426
6427
6428
 
# File 'array.c', line 6402

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

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

#one? {|obj| ... } ⇒ Boolean #one?(pattern) ⇒ Boolean

See also Enumerable#one?

Overloads:

  • #one? {|obj| ... } ⇒ Boolean

    Yields:

    • (obj) 


6438
6439
6440
6441
6442
6443
6444
6445
6446
6447
6448
6449
6450
6451
6452
6453
6454
6455
6456
6457
6458
6459
6460
6461
6462
6463
6464
6465
6466
6467
6468
6469
6470
6471
6472
6473
6474
 
# File 'array.c', line 6438

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

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

#permutation {|p| ... } ⇒ Array #permutation ⇒ Enumerator #permutation(n) {|p| ... } ⇒ Array #permutation(n) ⇒ Enumerator

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

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

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

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

Examples:

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

Overloads:

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

    Yields:

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

    Yields:

    • (p) 


5772
5773
5774
5775
5776
5777
5778
5779
5780
5781
5782
5783
5784
5785
5786
5787
5788
5789
5790
5791
5792
5793
5794
5795
5796
5797
5798
5799
5800
5801
5802
5803
5804
5805
5806
5807
5808
 
# File 'array.c', line 5772

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

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

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

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

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

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

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

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

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



1277
1278
1279
1280
1281
1282
1283
1284
1285
1286
1287
1288
1289
1290
1291
 
# File 'array.c', line 1277

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

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

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

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

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| ... } ⇒ Array

    Yields:

    • (p) 


6120
6121
6122
6123
6124
6125
6126
6127
6128
6129
6130
6131
6132
6133
6134
6135
6136
6137
6138
6139
6140
6141
6142
6143
6144
6145
6146
6147
6148
6149
6150
6151
6152
6153
6154
6155
6156
6157
6158
6159
6160
6161
6162
6163
6164
6165
6166
6167
6168
6169
6170
6171
6172
6173
6174
6175
6176
6177
6178
6179
6180
6181
6182
6183
6184
6185
6186
6187
6188
6189
6190
6191
6192
6193
6194
6195
6196
6197
6198
6199
6200
6201
6202
6203
6204
6205
6206
 
# File 'array.c', line 6120

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

    RBASIC_CLEAR_CLASS(t0);

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

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

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

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

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

    return NIL_P(result) ? ary : result;
}

#push(obj, ...) ⇒ Array #append(obj, ...) ⇒ Array Also known as: append

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

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



1234
1235
1236
1237
1238
 
# File 'array.c', line 1234

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

#rassoc(obj) ⇒ nil

Searches through the array whose elements are also arrays.

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

Returns the first contained array that matches obj.

See also Array#assoc.

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



4188
4189
4190
4191
4192
4193
4194
4195
4196
4197
4198
4199
4200
4201
4202
 
# File 'array.c', line 4188

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

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

#reject {|item| ... } ⇒ Array #reject ⇒ Enumerator

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

See also Array#delete_if

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

Overloads:

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

    Yields:

    • (item) 


3609
3610
3611
3612
3613
3614
3615
3616
3617
3618
 
# File 'array.c', line 3609

static VALUE
rb_ary_reject(VALUE ary)
{
    VALUE rejected_ary;

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

#reject! {|item| ... } ⇒ Array? #reject! ⇒ Enumerator

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

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

See also Enumerable#reject and Array#delete_if.

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

Overloads:

  • #reject! {|item| ... } ⇒ Array?

    Yields:

    • (item) 


3588
3589
3590
3591
3592
3593
3594
 
# File 'array.c', line 3588

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

#repeated_combination(n) {|c| ... } ⇒ Array #repeated_combination(n) ⇒ Enumerator

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

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

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

Examples:

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

Overloads:

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

    Yields:

    • (c) 


6064
6065
6066
6067
6068
6069
6070
6071
6072
6073
6074
6075
6076
6077
6078
6079
6080
6081
6082
6083
6084
6085
6086
6087
6088
6089
6090
6091
6092
6093
6094
6095
6096
6097
 
# File 'array.c', line 6064

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

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

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

#repeated_permutation(n) {|p| ... } ⇒ Array #repeated_permutation(n) ⇒ Enumerator

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

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

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

Examples:

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

Overloads:

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

    Yields:

    • (p) 


5970
5971
5972
5973
5974
5975
5976
5977
5978
5979
5980
5981
5982
5983
5984
5985
5986
5987
5988
5989
5990
5991
5992
5993
5994
5995
5996
5997
5998
5999
6000
6001
 
# File 'array.c', line 5970

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

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

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

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

#replace(other_ary) ⇒ Array #initialize_copy(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"]



3810
3811
3812
3813
3814
3815
3816
3817
3818
3819
3820
3821
3822
3823
3824
3825
3826
3827
3828
3829
3830
3831
3832
3833
3834
3835
3836
3837
3838
3839
3840
3841
3842
3843
3844
3845
3846
3847
3848
3849
 
# File 'array.c', line 3810

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

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

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

#reverse ⇒ Array

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

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



2586
2587
2588
2589
2590
2591
2592
2593
2594
2595
2596
2597
2598
2599
 
# File 'array.c', line 2586

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

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

#reverse! ⇒ Array

Reverses self in place.

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



2570
2571
2572
2573
2574
 
# File 'array.c', line 2570

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

#reverse_each {|item| ... } ⇒ Array #reverse_each ⇒ Enumerator

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

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

produces:

c b a

Overloads:

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

    Yields:

    • (item) 


2185
2186
2187
2188
2189
2190
2191
2192
2193
2194
2195
2196
2197
2198
2199
2200
2201
 
# File 'array.c', line 2185

static VALUE
rb_ary_reverse_each(VALUE ary)
{
    long len;

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

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

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

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

Returns nil if no match is found.

See also Array#index.

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

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

Overloads:

  • #rindex {|item| ... } ⇒ Integer?

    Yields:

    • (item) 


1819
1820
1821
1822
1823
1824
1825
1826
1827
1828
1829
1830
1831
1832
1833
1834
1835
1836
1837
1838
1839
1840
1841
1842
1843
1844
1845
1846
1847
1848
1849
1850
 
# File 'array.c', line 1819

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

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

#rotate(count = 1) ⇒ Array

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

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

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



2673
2674
2675
2676
2677
2678
2679
2680
2681
2682
2683
2684
2685
2686
2687
2688
2689
2690
2691
2692
 
# File 'array.c', line 2673

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

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

#rotate!(count = 1) ⇒ Array

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

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

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



2648
2649
2650
2651
2652
2653
2654
 
# File 'array.c', line 2648

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

#sample ⇒ Object #sample(random: rng) ⇒ Object #sample(n) ⇒ Array #sample(n, random: rng) ⇒ Array

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

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

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

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

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

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



5423
5424
5425
5426
5427
5428
5429
5430
5431
5432
5433
5434
5435
5436
5437
5438
5439
5440
5441
5442
5443
5444
5445
5446
5447
5448
5449
5450
5451
5452
5453
5454
5455
5456
5457
5458
5459
5460
5461
5462
5463
5464
5465
5466
5467
5468
5469
5470
5471
5472
5473
5474
5475
5476
5477
5478
5479
5480
5481
5482
5483
5484
5485
5486
5487
5488
5489
5490
5491
5492
5493
5494
5495
5496
5497
5498
5499
5500
5501
5502
5503
5504
5505
5506
5507
5508
5509
5510
5511
5512
5513
5514
5515
5516
5517
5518
5519
5520
5521
5522
5523
5524
5525
5526
5527
5528
5529
5530
5531
5532
5533
5534
5535
5536
5537
5538
5539
5540
5541
5542
5543
5544
5545
5546
5547
5548
5549
5550
5551
5552
5553
5554
5555
5556
5557
5558
5559
5560
5561
5562
5563
 
# File 'array.c', line 5423

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

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

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

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

    return result;
}

#select {|item| ... } ⇒ Array #select ⇒ Enumerator #filter {|item| ... } ⇒ Array #filter ⇒ Enumerator

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

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

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

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

See also Enumerable#select.

Array#filter is an alias for Array#select.

Overloads:

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

    Yields:

    • (item)
  • #filter {|item| ... } ⇒ Array

    Yields:

    • (item) 


3212
3213
3214
3215
3216
3217
3218
3219
3220
3221
3222
3223
3224
3225
3226
 
# File 'array.c', line 3212

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

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

#select! {|item| ... } ⇒ Array? #select! ⇒ Enumerator #filter! {|item| ... } ⇒ Array? #filter! ⇒ Enumerator

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

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

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

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

See also Array#keep_if.

Array#filter! is an alias for Array#select!.

Overloads:

  • #select! {|item| ... } ⇒ Array?

    Yields:

    • (item)
  • #filter! {|item| ... } ⇒ Array?

    Yields:

    • (item) 


3293
3294
3295
3296
3297
3298
3299
3300
3301
3302
3303
3304
 
# File 'array.c', line 3293

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

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

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

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

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

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

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

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



1350
1351
1352
1353
1354
1355
1356
1357
1358
1359
1360
1361
1362
1363
1364
1365
1366
 
# File 'array.c', line 1350

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

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

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

    return result;
}

#shuffle ⇒ Array #shuffle(random: rng) ⇒ Array

Returns a new array with elements of self shuffled.

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

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

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



5387
5388
5389
5390
5391
5392
5393
 
# File 'array.c', line 5387

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

#shuffle! ⇒ Array #shuffle!(random: rng) ⇒ Array

Shuffles elements in self in place.

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

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

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



5336
5337
5338
5339
5340
5341
5342
5343
5344
5345
5346
5347
5348
5349
5350
5351
5352
5353
5354
5355
5356
5357
5358
5359
5360
5361
5362
5363
5364
5365
5366
5367
5368
 
# File 'array.c', line 5336

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

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

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

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

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

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

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

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



1573
1574
1575
1576
1577
1578
1579
1580
1581
 
# File 'array.c', line 1573

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

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

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

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

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



3482
3483
3484
3485
3486
3487
3488
3489
3490
3491
3492
3493
3494
3495
3496
3497
3498
3499
3500
3501
3502
3503
3504
3505
3506
3507
3508
3509
3510
3511
3512
3513
3514
3515
3516
3517
3518
3519
3520
3521
3522
3523
3524
3525
3526
3527
3528
 
# File 'array.c', line 3482

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

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

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

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

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

#sort ⇒ Array #sort {|a, b| ... } ⇒ Array

Returns a new array created by sorting self.

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

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

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

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

To produce the reverse order, the following can also be used (and may be faster):

ary.sort.reverse!             #=> ["e", "d", "c", "b", "a"]

See also Enumerable#sort_by.

Overloads:

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

    Yields:

    • (a, b) 


2865
2866
2867
2868
2869
2870
2871
 
# File 'array.c', line 2865

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

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

Sorts self in place.

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

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

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

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

See also Enumerable#sort_by.

Overloads:

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

    Yields:

    • (a, b) 


2776
2777
2778
2779
2780
2781
2782
2783
2784
2785
2786
2787
2788
2789
2790
2791
2792
2793
2794
2795
2796
2797
2798
2799
2800
2801
2802
2803
2804
2805
2806
2807
2808
2809
2810
2811
2812
2813
2814
2815
2816
2817
2818
2819
2820
2821
2822
2823
2824
2825
2826
2827
2828
2829
2830
2831
2832
2833
2834
 
# File 'array.c', line 2776

VALUE
rb_ary_sort_bang(VALUE ary)
{
    rb_ary_modify(ary);
    assert(!ARY_SHARED_P(ary));
    if (RARRAY_LEN(ary) > 1) {
  VALUE tmp = ary_make_substitution(ary); /* only ary refers tmp */
  struct ary_sort_data data;
  long len = RARRAY_LEN(ary);
  RBASIC_CLEAR_CLASS(tmp);
  data.ary = tmp;
  data.cmp_opt.opt_methods = 0;
  data.cmp_opt.opt_inited = 0;
  RARRAY_PTR_USE(tmp, ptr, {
            ruby_qsort(ptr, len, sizeof(VALUE),
                       rb_block_given_p()?sort_1:sort_2, &data);
  }); /* WB: no new reference */
  rb_ary_modify(ary);
        if (ARY_EMBED_P(tmp)) {
            if (ARY_SHARED_P(ary)) { /* ary might be destructively operated in the given block */
                rb_ary_unshare(ary);
    FL_SET_EMBED(ary);
            }
      ary_memcpy(ary, 0, ARY_EMBED_LEN(tmp), ARY_EMBED_PTR(tmp));
            ARY_SET_LEN(ary, ARY_EMBED_LEN(tmp));
        }
        else {
            if (!ARY_EMBED_P(ary) && ARY_HEAP_PTR(ary) == ARY_HEAP_PTR(tmp)) {
                FL_UNSET_SHARED(ary);
                ARY_SET_CAPA(ary, RARRAY_LEN(tmp));
            }
            else {
                assert(!ARY_SHARED_P(tmp));
                if (ARY_EMBED_P(ary)) {
                    FL_UNSET_EMBED(ary);
                }
                else if (ARY_SHARED_P(ary)) {
                    /* ary might be destructively operated in the given block */
                    rb_ary_unshare(ary);
                }
                else {
                    ary_heap_free(ary);
                }
                ARY_SET_PTR(ary, ARY_HEAP_PTR(tmp));
                ARY_SET_HEAP_LEN(ary, len);
                ARY_SET_CAPA(ary, ARY_HEAP_LEN(tmp));
            }
            /* tmp was lost ownership for the ptr */
            FL_UNSET(tmp, FL_FREEZE);
            FL_SET_EMBED(tmp);
            ARY_SET_EMBED_LEN(tmp, 0);
            FL_SET(tmp, FL_FREEZE);
        }
        /* tmp will be GC'ed. */
        RBASIC_SET_CLASS_RAW(tmp, rb_cArray); /* rb_cArray must be marked */
    }
    ary_verify(ary);
    return ary;
}

#sort_by! {|obj| ... } ⇒ Array #sort_by! ⇒ Enumerator

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

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

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

See also Enumerable#sort_by.

Overloads:

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

    Yields:

    • (obj) 


3022
3023
3024
3025
3026
3027
3028
3029
3030
3031
3032
 
# File 'array.c', line 3022

static VALUE
rb_ary_sort_by_bang(VALUE ary)
{
    VALUE sorted;

    RETURN_SIZED_ENUMERATOR(ary, 0, 0, ary_enum_length);
    rb_ary_modify(ary);
    sorted = rb_block_call(ary, rb_intern("sort_by"), 0, 0, sort_by_i, 0);
    rb_ary_replace(ary, sorted);
    return ary;
}

#sum(init = 0) ⇒ Numeric #sum(init = 0) {|e| ... } ⇒ Numeric

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

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

If ary is empty, it returns init.

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

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

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

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

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

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

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

Array#sum method may not respect method redefinition of “+” methods such as Integer#+.

Overloads:

  • #sum(init = 0) {|e| ... } ⇒ Numeric

    Yields:

    • (e) 


6564
6565
6566
6567
6568
6569
6570
6571
6572
6573
6574
6575
6576
6577
6578
6579
6580
6581
6582
6583
6584
6585
6586
6587
6588
6589
6590
6591
6592
6593
6594
6595
6596
6597
6598
6599
6600
6601
6602
6603
6604
6605
6606
6607
6608
6609
6610
6611
6612
6613
6614
6615
6616
6617
6618
6619
6620
6621
6622
6623
6624
6625
6626
6627
6628
6629
6630
6631
6632
6633
6634
6635
6636
6637
6638
6639
6640
6641
6642
6643
6644
6645
6646
6647
6648
6649
6650
6651
6652
6653
6654
6655
6656
6657
6658
6659
6660
6661
6662
6663
6664
6665
6666
6667
6668
6669
6670
6671
6672
 
# File 'array.c', line 6564

static VALUE
rb_ary_sum(int argc, VALUE *argv, VALUE ary)
{
    VALUE e, v, r;
    long i, n;
    int block_given;

    v = (rb_check_arity(argc, 0, 1) ? argv[0] : LONG2FIX(0));

    block_given = rb_block_given_p();

    if (RARRAY_LEN(ary) == 0)
        return v;

    n = 0;
    r = Qundef;
    for (i = 0; i < RARRAY_LEN(ary); i++) {
        e = RARRAY_AREF(ary, i);
        if (block_given)
            e = rb_yield(e);
        if (FIXNUM_P(e)) {
            n += FIX2LONG(e); /* should not overflow long type */
            if (!FIXABLE(n)) {
                v = rb_big_plus(LONG2NUM(n), v);
                n = 0;
            }
        }
        else if (RB_TYPE_P(e, T_BIGNUM))
            v = rb_big_plus(e, v);
        else if (RB_TYPE_P(e, T_RATIONAL)) {
            if (r == Qundef)
                r = e;
            else
                r = rb_rational_plus(r, e);
        }
        else
            goto not_exact;
    }
    v = finish_exact_sum(n, r, v, argc!=0);
    return v;

  not_exact:
    v = finish_exact_sum(n, r, v, i!=0);

    if (RB_FLOAT_TYPE_P(e)) {
        /*
         * Kahan-Babuska balancing compensated summation algorithm
         * See http://link.springer.com/article/10.1007/s00607-005-0139-x
         */
        double f, c;
        double x, t;

        f = NUM2DBL(v);
        c = 0.0;
        goto has_float_value;
        for (; i < RARRAY_LEN(ary); i++) {
            e = RARRAY_AREF(ary, i);
            if (block_given)
                e = rb_yield(e);
            if (RB_FLOAT_TYPE_P(e))
              has_float_value:
                x = RFLOAT_VALUE(e);
            else if (FIXNUM_P(e))
                x = FIX2LONG(e);
            else if (RB_TYPE_P(e, T_BIGNUM))
                x = rb_big2dbl(e);
            else if (RB_TYPE_P(e, T_RATIONAL))
                x = rb_num2dbl(e);
            else
                goto not_float;

            if (isnan(f)) continue;
            if (isnan(x)) {
                f = x;
                continue;
            }
            if (isinf(x)) {
                if (isinf(f) && signbit(x) != signbit(f))
                    f = NAN;
                else
                    f = x;
                continue;
            }
            if (isinf(f)) continue;

            t = f + x;
            if (fabs(f) >= fabs(x))
                c += ((f - t) + x);
            else
                c += ((x - t) + f);
            f = t;
        }
        f += c;
        return DBL2NUM(f);

      not_float:
        v = DBL2NUM(f);
    }

    goto has_some_value;
    for (; i < RARRAY_LEN(ary); i++) {
        e = RARRAY_AREF(ary, i);
        if (block_given)
            e = rb_yield(e);
      has_some_value:
        v = rb_funcall(v, idPLUS, 1, e);
    }
    return v;
}

#take(n) ⇒ Array

Returns first n elements from the array.

If a negative number is given, raises an ArgumentError.

See also Array#drop

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



6223
6224
6225
6226
6227
6228
6229
6230
6231
 
# File 'array.c', line 6223

static VALUE
rb_ary_take(VALUE obj, VALUE n)
{
    long len = NUM2LONG(n);
    if (len < 0) {
  rb_raise(rb_eArgError, "attempt to take negative size");
    }
    return rb_ary_subseq(obj, 0, len);
}

#take_while {|obj| ... } ⇒ Array #take_while ⇒ Enumerator

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

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

See also Array#drop_while

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

Overloads:

  • #take_while {|obj| ... } ⇒ Array

    Yields:

    • (obj) 


6250
6251
6252
6253
6254
6255
6256
6257
6258
6259
6260
 
# File 'array.c', line 6250

static VALUE
rb_ary_take_while(VALUE ary)
{
    long i;

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

#to_a ⇒ Array

Returns self.

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



2467
2468
2469
2470
2471
2472
2473
2474
2475
2476
 
# File 'array.c', line 2467

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 ⇒ Array

Returns self.



2527
2528
2529
2530
2531
 
# File 'array.c', line 2527

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

#to_h ⇒ Hash #to_h {|item| ... } ⇒ Hash

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

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

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

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

Overloads:

  • #to_h {|item| ... } ⇒ Hash

    Yields:

    • (item) 


2496
2497
2498
2499
2500
2501
2502
2503
2504
2505
2506
2507
2508
2509
2510
2511
2512
2513
2514
2515
2516
2517
2518
 
# File 'array.c', line 2496

static VALUE
rb_ary_to_h(VALUE ary)
{
    long i;
    VALUE hash = rb_hash_new_with_size(RARRAY_LEN(ary));
    int block_given = rb_block_given_p();

    for (i=0; i<RARRAY_LEN(ary); i++) {
  const VALUE e = rb_ary_elt(ary, i);
  const VALUE elt = block_given ? rb_yield_force_blockarg(e) : e;
  const VALUE key_value_pair = rb_check_array_type(elt);
  if (NIL_P(key_value_pair)) {
      rb_raise(rb_eTypeError, "wrong element type %"PRIsVALUE" at %ld (expected array)",
         rb_obj_class(elt), i);
  }
  if (RARRAY_LEN(key_value_pair) != 2) {
      rb_raise(rb_eArgError, "wrong array length at %ld (expected 2, was %ld)",
    i, RARRAY_LEN(key_value_pair));
  }
  rb_hash_aset(hash, RARRAY_AREF(key_value_pair, 0), RARRAY_AREF(key_value_pair, 1));
    }
    return hash;
}

#transpose ⇒ Array

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

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

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



3769
3770
3771
3772
3773
3774
3775
3776
3777
3778
3779
3780
3781
3782
3783
3784
3785
3786
3787
3788
3789
3790
3791
3792
3793
3794
3795
 
# File 'array.c', line 3769

static VALUE
rb_ary_transpose(VALUE ary)
{
    long elen = -1, alen, i, j;
    VALUE tmp, result = 0;

    alen = RARRAY_LEN(ary);
    if (alen == 0) return rb_ary_dup(ary);
    for (i=0; i<alen; i++) {
  tmp = to_ary(rb_ary_elt(ary, i));
  if (elen < 0) {    /* first element */
      elen = RARRAY_LEN(tmp);
      result = rb_ary_new2(elen);
      for (j=0; j<elen; j++) {
    rb_ary_store(result, j, rb_ary_new2(alen));
      }
  }
  else if (elen != RARRAY_LEN(tmp)) {
      rb_raise(rb_eIndexError, "element size differs (%ld should be %ld)",
         RARRAY_LEN(tmp), elen);
  }
  for (j=0; j<elen; j++) {
      rb_ary_store(rb_ary_elt(result, j), i, rb_ary_elt(tmp, j));
  }
    }
    return result;
}

#union(other_ary1, other_ary2, ...) ⇒ Array

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

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

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

See also Array#|.



4776
4777
4778
4779
4780
4781
4782
4783
4784
4785
4786
4787
4788
4789
4790
4791
4792
4793
4794
4795
4796
4797
4798
4799
4800
4801
4802
4803
4804
 
# File 'array.c', line 4776

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

    sum = RARRAY_LEN(ary);
    for (i = 0; i < argc; i++) {
        argv[i] = to_ary(argv[i]);
        sum += RARRAY_LEN(argv[i]);
    }

    if (sum <= SMALL_ARRAY_LEN) {
        ary_union = rb_ary_new();

        rb_ary_union(ary_union, ary);
        for (i = 0; i < argc; i++) rb_ary_union(ary_union, argv[i]);

        return ary_union;
    }

    hash = ary_make_hash(ary);
    for (i = 0; i < argc; i++) rb_ary_union_hash(hash, argv[i]);

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

#uniq ⇒ Array #uniq {|item| ... } ⇒ Array

Returns a new array by removing duplicate values in self.

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

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

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

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

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

Overloads:

  • #uniq {|item| ... } ⇒ Array

    Yields:

    • (item) 


5018
5019
5020
5021
5022
5023
5024
5025
5026
5027
5028
5029
5030
5031
5032
5033
5034
5035
5036
5037
5038
5039
5040
5041
 
# File 'array.c', line 5018

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

    if (RARRAY_LEN(ary) <= 1) {
        hash = 0;
        uniq = rb_ary_dup(ary);
    }
    else if (rb_block_given_p()) {
  hash = ary_make_hash_by(ary);
  uniq = rb_hash_values(hash);
    }
    else {
  hash = ary_make_hash(ary);
  uniq = rb_hash_values(hash);
    }
    RBASIC_SET_CLASS(uniq, rb_obj_class(ary));
    if (hash) {
        ary_recycle_hash(hash);
    }

    return uniq;
}

#uniq! ⇒ Array? #uniq! {|item| ... } ⇒ Array?

Removes duplicate elements from self.

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

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

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

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

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

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

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

Overloads:

  • #uniq! {|item| ... } ⇒ Array?

    Yields:

    • (item) 


4966
4967
4968
4969
4970
4971
4972
4973
4974
4975
4976
4977
4978
4979
4980
4981
4982
4983
4984
4985
4986
4987
4988
4989
4990
4991
4992
4993
4994
4995
 
# File 'array.c', line 4966

static VALUE
rb_ary_uniq_bang(VALUE ary)
{
    VALUE hash;
    long hash_size;

    rb_ary_modify_check(ary);
    if (RARRAY_LEN(ary) <= 1)
        return Qnil;
    if (rb_block_given_p())
  hash = ary_make_hash_by(ary);
    else
  hash = ary_make_hash(ary);

    hash_size = RHASH_SIZE(hash);
    if (RARRAY_LEN(ary) == hash_size) {
  return Qnil;
    }
    rb_ary_modify_check(ary);
    ARY_SET_LEN(ary, 0);
    if (ARY_SHARED_P(ary) && !ARY_EMBED_P(ary)) {
  rb_ary_unshare(ary);
  FL_SET_EMBED(ary);
    }
    ary_resize_capa(ary, hash_size);
    rb_hash_foreach(hash, push_value, ary);
    ary_recycle_hash(hash);

    return ary;
}

#unshift(obj, ...) ⇒ Array #prepend(obj, ...) ⇒ Array Also known as: prepend

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

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



1476
1477
1478
1479
1480
1481
1482
1483
1484
1485
1486
1487
1488
1489
1490
1491
 
# File 'array.c', line 1476

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

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

    target_ary = ary_ensure_room_for_unshift(ary, argc);
    ary_memcpy0(ary, 0, argc, argv, target_ary);
    ARY_SET_LEN(ary, len + argc);
    return ary;
}

#values_at(selector, ...) ⇒ Array

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

The selectors may be either integer indices or ranges.

See also Array#select.

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



3177
3178
3179
3180
3181
3182
3183
3184
3185
3186
3187
 
# File 'array.c', line 3177

static VALUE
rb_ary_values_at(int argc, VALUE *argv, VALUE ary)
{
    long i, olen = RARRAY_LEN(ary);
    VALUE result = rb_ary_new_capa(argc);
    for (i = 0; i < argc; ++i) {
  append_values_at_single(result, ary, olen, argv[i]);
    }
    RB_GC_GUARD(ary);
    return result;
}

#zip(arg, ...) ⇒ Array #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 ary.size n-element arrays, where n is one more than the count of arguments.

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

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

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

Overloads:

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

    Yields:

    • (arr) 


3698
3699
3700
3701
3702
3703
3704
3705
3706
3707
3708
3709
3710
3711
3712
3713
3714
3715
3716
3717
3718
3719
3720
3721
3722
3723
3724
3725
3726
3727
3728
3729
3730
3731
3732
3733
3734
3735
3736
3737
3738
3739
3740
3741
3742
3743
3744
3745
3746
3747
3748
3749
3750
3751
3752
3753
3754
 
# File 'array.c', line 3698

static VALUE
rb_ary_zip(int argc, VALUE *argv, VALUE ary)
{
    int i, j;
    long len = RARRAY_LEN(ary);
    VALUE result = Qnil;

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

    if (rb_block_given_p()) {
  int arity = rb_block_arity();

  if (arity > 1) {
      VALUE work, *tmp;

      tmp = ALLOCV_N(VALUE, work, argc+1);

      for (i=0; i<RARRAY_LEN(ary); i++) {
    tmp[0] = RARRAY_AREF(ary, i);
    for (j=0; j<argc; j++) {
        tmp[j+1] = rb_ary_elt(argv[j], i);
    }
    rb_yield_values2(argc+1, tmp);
      }

      if (work) ALLOCV_END(work);
  }
  else {
      for (i=0; i<RARRAY_LEN(ary); i++) {
    VALUE tmp = rb_ary_new2(argc+1);

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

  for (i=0; i<len; i++) {
      VALUE tmp = rb_ary_new_capa(argc+1);

      rb_ary_push(tmp, RARRAY_AREF(ary, i));
      for (j=0; j<argc; j++) {
    rb_ary_push(tmp, rb_ary_elt(argv[j], i));
      }
      rb_ary_push(result, tmp);
  }
    }

    return result;
}

#|(other_ary) ⇒ Array

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

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

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

See also Array#union.



4739
4740
4741
4742
4743
4744
4745
4746
4747
4748
4749
4750
4751
4752
4753
4754
4755
4756
4757
4758
 
# File 'array.c', line 4739

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

    ary2 = to_ary(ary2);
    if (RARRAY_LEN(ary1) + RARRAY_LEN(ary2) <= SMALL_ARRAY_LEN) {
  ary3 = rb_ary_new();
        rb_ary_union(ary3, ary1);
        rb_ary_union(ary3, ary2);
  return ary3;
    }

    hash = ary_make_hash(ary1);
    rb_ary_union_hash(hash, ary2);

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