123456789_123456789_123456789_123456789_123456789_

Class: Array

Relationships & Source Files
Super Chains via Extension / Inclusion / Inheritance
Instance Chain:
self, ::Enumerable
Inherits: Object
Defined in: pack.rb,
array.c,
array.rb

Overview

An Array is an ordered, integer-indexed collection of objects, called elements. Any object may be an Array element.

Array Indexes

Array indexing starts at 0, as in C or Java.

A positive index is an offset from the first element:

  • Index 0 indicates the first element.

  • Index 1 indicates the second element.

  • …

A negative index is an offset, backwards, from the end of the array:

  • Index -1 indicates the last element.

  • Index -2 indicates the next-to-last element.

  • …

A non-negative index is in range if it is smaller than the size of the array. For a 3-element array:

  • Indexes 0 through 2 are in range.

  • Index 3 is out of range.

A negative index is in range if its absolute value is not larger than the size of the array. For a 3-element array:

  • Indexes -1 through -3 are in range.

  • Index -4 is out of range.

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 .new with zero, one (the initial size of the Array) or two arguments (the initial size and a default object).

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

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

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

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

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

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

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

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

Example Usage

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

Some of the more common ones are illustrated below.

Accessing Elements

Elements in an array can be retrieved using the #[] 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 #[].

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

Instance Attribute Summary

  • #empty? ⇒ Boolean readonly

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

Instance Method Summary

::Enumerable - Included

#all?

Passes each element of the collection to the given block.
#any?

Passes each element of the collection to the given block.
#chain

Returns an enumerator object generated from this enumerator and given enumerables.
#chunk

Enumerates over the items, chunking them together based on the return value of the block.
#chunk_while

Creates an enumerator for each chunked elements.
#collect

Alias for Enumerable#map.
#collect_concat

Alias for Enumerable#flat_map.
#count

Returns the number of items in enum through enumeration.
#cycle

Calls block for each element of enum repeatedly n times or forever if none or nil is given.
#detect

Alias for Enumerable#find.
#drop

Drops first n elements from enum, and returns rest elements in an array.
#drop_while

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

Iterates the given block for each array of consecutive <n> elements.
#each_entry

Calls block once for each element in self, passing that element as a parameter, converting multiple values from yield to an array.
#each_slice

Iterates the given block for each slice of <n> elements.
#each_with_index

Calls block with two arguments, the item and its index, for each item in enum.
#each_with_object

Iterates the given block for each element with an arbitrary object given, and returns the initially given object.
#entries

Alias for Enumerable#to_a.
#filter

Returns an array containing all elements of enum for which the given block returns a true value.
#filter_map

Returns a new array containing the truthy results (everything except false or nil) of running the block for every element in enum.
#find

Passes each entry in enum to block.
#find_all

Alias for Enumerable#filter.
#find_index

Compares each entry in enum with value or passes to block.
#first

Returns the first element, or the first n elements, of the enumerable.
#flat_map

Returns a new array with the concatenated results of running block once for every element in enum.
#grep

Returns an array of every element in enum for which Pattern === element.
#grep_v

Inverted version of Enumerable#grep.
#group_by

Groups the collection by result of the block.
#include?

Alias for Enumerable#member?.
#inject

Combines all elements of enum by applying a binary operation, specified by a block or a symbol that names a method or operator.
#lazy

Returns an ::Enumerator::Lazy, which redefines most ::Enumerable methods to postpone enumeration and enumerate values only on an as-needed basis.
#map

Returns a new array with the results of running block once for every element in enum.
#max

Returns the object in enum with the maximum value.
#max_by

Returns the object in enum that gives the maximum value from the given block.
#member?

Returns true if any member of enum equals obj.
#min

Returns the object in enum with the minimum value.
#min_by

Returns the object in enum that gives the minimum value from the given block.
#minmax

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

Returns a two element array containing the objects in enum that correspond to the minimum and maximum values respectively from the given block.
#none?

Passes each element of the collection to the given block.
#one?

Passes each element of the collection to the given block.
#partition

Returns two arrays, the first containing the elements of enum for which the block evaluates to true, the second containing the rest.
#reduce

Alias for Enumerable#inject.
#reject

Returns an array for all elements of enum for which the given block returns false.
#reverse_each

Builds a temporary array and traverses that array in reverse order.
#select

Alias for Enumerable#filter.
#slice_after

Creates an enumerator for each chunked elements.
#slice_before

Creates an enumerator for each chunked elements.
#slice_when

Creates an enumerator for each chunked elements.
#sort

Returns an array containing the items in enum sorted.
#sort_by

Sorts enum using a set of keys generated by mapping the values in enum through the given block.
#sum

Returns the sum of elements in an ::Enumerable.
#take

Returns first n elements from enum.
#take_while

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

Tallies the collection, i.e., counts the occurrences of each element.
#to_a

Returns an array containing the items in enum.
#to_h

Returns the result of interpreting enum as a list of [key, value] pairs.
#uniq

Returns a new array by removing duplicate values in self.
#zip

Takes one element from enum and merges corresponding elements from each args.

Constructor Details

.new ⇒ Array .new(array) ⇒ Array .new(size) ⇒ Array .new(size, default_value) ⇒ Array .new(size) {|index| ... } ⇒ Array

Returns a new Array.

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

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

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

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

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

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

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

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

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

Raises ArgumentError if #size is negative.

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

[ GitHub ] 

  


# File 'array.c', line 1063



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)  
  



  

    

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


  



  [ GitHub ]


  

  


# File 'array.c', line 1128



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(object)  ⇒ Object, ...   



  

    

If object is an Array object, returns object.



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



Returns nil if object does not respond to :to_ary



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


  



  [ GitHub ]


  

  


# File 'array.c', line 1013



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


  







Instance Attribute Details



  

    #empty?  ⇒ Boolean  (readonly)  



  

    

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


  



  [ GitHub ]


  

  


# File 'array.c', line 2657



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


  







Instance Method Details



  

    #&(other_array)  ⇒ Array   



  

    

Returns a new Array containing each element found in both array and Array other_array; duplicates are omitted; items are compared using #eql?:



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



Preserves order from array:



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



Related: #intersection.


  



  [ GitHub ]


  

  


# File 'array.c', line 5385



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


  








  

    

      #*(n)  ⇒ Array 
      #*(string_separator)  ⇒ String 
    

  



  

    

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



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



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



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


  





  


  [ GitHub ]


  

  


# File 'array.c', line 4879



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

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

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

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

    ptr = RARRAY_CONST_PTR_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_array)  ⇒ Array   



  

    

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



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



Related: #concat.


  



  [ GitHub ]


  

  


# File 'array.c', line 4799



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



  

    

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



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



Related: #difference.


  



  [ GitHub ]


  

  


# File 'array.c', line 5288



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


  








  

    #<<(object)  ⇒ self   



  

    

Appends object to self; returns self:



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



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



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


  



  [ GitHub ]


  

  


# File 'array.c', line 1300



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_array)  ⇒ 1, 0   



  

    

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



Returns -1 if any result is -1:



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



Returns 1 if any result is 1:



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



When all results are zero:


  • 

    Returns -1 if array is smaller than other_array:
    


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

  • 

    Returns 1 if array is larger than other_array:
    


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

  • 

    Returns 0 if array and other_array are the same size:
    


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



  



  [ GitHub ]


  

  


# File 'array.c', line 5197



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



  

    

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



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



Otherwise, returns false.



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


  



  [ GitHub ]


  

  


# File 'array.c', line 5033



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)  ⇒ Object? 
      #[](range)  ⇒ Object? 
      #[](aseq)  ⇒ Object? 
      #slice(index)  ⇒ Object? 
      #slice(start, length)  ⇒ Object? 
      #slice(range)  ⇒ Object? 
      #slice(aseq)  ⇒ Object? 
    

    Also known as: #slice
  



  

    

Returns elements from self; does not modify self.



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



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



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



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



If #index is out of range, returns nil.



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



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



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



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



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



If #length is negative, returns nil.



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



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



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



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



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



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



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



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



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



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



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



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



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



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



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



#slice is an alias for [].


  





  


  [ GitHub ]


  

  


# File 'array.c', line 1801



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)  ⇒ Object 
      #[]=(start, length, object)  ⇒ Object 
      #[]=(range, object)  ⇒ Object 
    

  



  

    

Assigns elements in self; returns the given object.



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



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



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



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



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



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



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



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



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



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



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



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



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



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



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



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



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



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



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



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



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



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



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



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



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



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



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



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



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


  





  


  [ GitHub ]


  

  


# File 'array.c', line 2388



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

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

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


  








  

    

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

  



  

    

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



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



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



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



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



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



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



Related: Enumerable#all?


  





  


  [ GitHub ]


  

  


# File 'array.c', line 7478



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?  ⇒ Boolean 
      #any? {|element| ... } ⇒ Boolean 
      #any?(obj)  ⇒ Boolean 
    

  



  

    

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



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



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



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



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



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



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



Related: Enumerable#any?


  





  


  [ GitHub ]


  

  


# File 'array.c', line 7421



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


  








  

    

      #push(*objects)  ⇒ self 
      #append(*objects)  ⇒ self 
    

  



  

    

Alias for #push.


  









  

    #assoc(obj)  ⇒ Array?   



  

    

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



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



Returns nil if no such element is found.



Related: #rassoc.


  



  [ GitHub ]


  

  


# File 'array.c', line 4937



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 Integer offset #index; does not modify self.



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


  



  [ GitHub ]


  

  


# File 'array.c', line 1854



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


  








  

    

      #bsearch {|element| ... } ⇒ Object 
      #bsearch  ⇒ Enumerator 
    

  



  

    

Returns an element from self selected by a binary search. self should be sorted, but this is not checked.



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.



There are two search modes:


  • 

    Find-minimum mode: the block should return true or false.
    

  • 

    Find-any mode: the block should return a numeric value.
    




The block should not mix the modes by and sometimes returning true or false and sometimes returning a numeric value, but this is not checked.



Find-Minimum Mode



In find-minimum mode, the block always returns true or false. The further requirement (though not checked) is that there are no indexes i and j such that:


  • 

    0 <= i < j <= self.size.
    

  • 

    The block returns true for self[i] and false for self[j].
    




In find-minimum mode, method bsearch returns the first element for which the block returns true.



Examples:



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



Less formally: the block is such that all false-evaluating elements precede all true-evaluating elements.



These make sense as blocks in find-minimum mode:



a = [0, 4, 7, 10, 12]
a.map {|x| x >= 4 } # => [false, true, true, true, true]
a.map {|x| x >= 6 } # => [false, false, true, true, true]
a.map {|x| x >= -1 } # => [true, true, true, true, true]
a.map {|x| x >= 100 } # => [false, false, false, false, false]



This would not make sense:



a = [0, 4, 7, 10, 12]
a.map {|x| x == 7 } # => [false, false, true, false, false]



Find-Any Mode



In find-any mode, the block always returns a numeric value. The further requirement (though not checked) is that there are no indexes i and j such that:


  • 

    0 <= i < j <= self.size.
    

  • 

    The block returns a negative value for self[i] and a positive value for self[j].
    

  • 

    The block returns a negative value for self[i] and zero self[j].
    

  • 

    The block returns zero for self[i] and a positive value for self[j].
    




In find-any mode, method bsearch returns some element for which the block returns zero, or nil if no such element is found.



Examples:



a = [0, 4, 7, 10, 12]
a.bsearch {|element| 7 <=> element } # => 7
a.bsearch {|element| -1 <=> element } # => nil
a.bsearch {|element| 5 <=> element } # => nil
a.bsearch {|element| 15 <=> element } # => nil



Less formally: the block is such that:


  • 

    All positive-evaluating elements precede all zero-evaluating elements.
    

  • 

    All positive-evaluating elements precede all negative-evaluating elements.
    

  • 

    All zero-evaluating elements precede all negative-evaluating elements.
    




These make sense as blocks in find-any mode:



a = [0, 4, 7, 10, 12]
a.map {|element| 7 <=> element } # => [1, 1, 0, -1, -1]
a.map {|element| -1 <=> element } # => [-1, -1, -1, -1, -1]
a.map {|element| 5 <=> element } # => [1, 1, -1, -1, -1]
a.map {|element| 15 <=> element } # => [1, 1, 1, 1, 1]



This would not make sense:



a = [0, 4, 7, 10, 12]
a.map {|element| element <=> 7 } # => [-1, -1, 0, 1, 1]



Returns an enumerator if no block given:



a = [0, 4, 7, 10, 12]
a.bsearch # => #<Enumerator: [0, 4, 7, 10, 12]:bsearch>


  





  


  [ GitHub ]


  

  


# File 'array.c', line 3496



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

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


  








  

    

      #bsearch_index {|element| ... } ⇒ Integer? 
      #bsearch_index  ⇒ Enumerator 
    

  



  

    

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


  





  


  [ GitHub ]


  

  


# File 'array.c', line 3516



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



  

    

Removes all elements from self:



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


  



  [ GitHub ]


  

  


# File 'array.c', line 4533



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


  








  

    

      #map {|element| ... } ⇒ Array 
      #map  ⇒ Enumerator 
    

  



  

    

Alias for #map.


  





  








  

    

      #map! {|element| ... } ⇒ self 
      #map!  ⇒ Enumerator 
    

  



  

    

Alias for #map!.


  





  








  

    

      #combination(n) {|element| ... } ⇒ self 
      #combination(n)  ⇒ Enumerator 
    

  



  

    

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



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



Example:



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



Output:



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



Another example:



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



Output:



[0, 1, 2]



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



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



Output:



[]



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



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



Returns a new Enumerator if no block given:



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


  





  


  [ GitHub ]


  

  


# File 'array.c', line 6845



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 new Array containing all non-nil elements from self:



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


  



  [ GitHub ]


  

  


# File 'array.c', line 6068



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


  








  

    #compact!  ⇒ self?   



  

    

Removes all nil elements from self.



Returns self if any elements removed, otherwise nil.


  



  [ GitHub ]


  

  


# File 'array.c', line 6036



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_arrays)  ⇒ self   



  

    

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



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


  



  [ GitHub ]


  

  


# File 'array.c', line 4837



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 {|element| ... } ⇒ Integer 
    

  



  

    

Returns a count of specified elements.



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



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



With argument obj, returns the count of elements #eql? to obj:



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



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



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



With argument obj and a block given, issues a warning, ignores the block, and returns the count of elements #eql? to obj:


  





  


  [ GitHub ]


  

  


# File 'array.c', line 6100



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

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

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

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

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

    return LONG2NUM(n);
}


  








  

    

      #cycle {|element| ... } ⇒ nil 
      #cycle(count) {|element| ... } ⇒ nil 
      #cycle  ⇒ Enumerator 
      #cycle(count)  ⇒ Enumerator 
    

  



  

    

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



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



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



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



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



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



When no block is given, returns a new Enumerator:



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


  





  


  [ GitHub ]


  

  


# File 'array.c', line 6528



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  
  

  [ GitHub ]


  

  


# File 'array.c', line 7818



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


  








  

    

      #delete(obj)  ⇒ deleted_object 
      #delete(obj) {|nosuch| ... } ⇒ deleted_object, block_return 
    

  



  

    

Removes zero or more elements from self; returns self.



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



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



Returns nil if no elements removed.



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



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



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



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



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


  





  


  [ GitHub ]


  

  


# File 'array.c', line 3955



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

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

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

    ary_resize_smaller(ary, i2);

    ary_verify(ary);
    return v;
}


  








  

    #delete_at(index)  ⇒ deleted_object?   



  

    

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



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



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



If index is too large, returns nil.



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



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



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


  



  [ GitHub ]


  

  


# File 'array.c', line 4052



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


  








  

    

      #delete_if {|element| ... } ⇒ self 
      #delete_if  ⇒ Enumerator 
    

  



  

    

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



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



Returns a new Enumerator if no block given:



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


  





  


  [ GitHub ]


  

  


# File 'array.c', line 4293



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


  








  

    #difference(*other_arrays)  ⇒ Array   



  

    

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



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



Returns a copy of self if no arguments given.



Related: #-.


  



  [ GitHub ]


  

  


# File 'array.c', line 5332



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

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

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

    ALLOCV_END(t0);

    return ary_diff;
}


  








  

    #dig(index, *identifiers)  ⇒ Object   



  

    

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



Examples:



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


  



  [ GitHub ]


  

  


# File 'array.c', line 7651



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   



  

    

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



Examples:



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


  



  [ GitHub ]


  

  


# File 'array.c', line 7347



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 {|element| ... } ⇒ Array 
      #drop_while  ⇒ Enumerator 
    

  



  

    

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



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



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



With no block given, returns a new Enumerator:



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


  





  


  [ GitHub ]


  

  


# File 'array.c', line 7379



static VALUE
rb_ary_drop_while(VALUE ary)
{
    long i;

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


  








  

    

      #each {|element| ... } ⇒ self 
      #each  ⇒ Enumerator 
    

  



  

    

Iterates over array elements.



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



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



Output:



Symbol foo
String bar
Integer 2



Allows the array to be modified during iteration:



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



Output:



foo
bar



When no block given, returns a new Enumerator:



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



Output:



Symbol foo
String bar
Integer 2



Related: #each_index, #reverse_each.


  





  


  [ GitHub ]


  

  


# File 'array.c', line 2516



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


  








  

    

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

  



  

    

Iterates over array indexes.



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



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



Output:



0 foo
1 bar
2 2



Allows the array to be modified during iteration:



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



Output:



0
1



When no block given, returns a new Enumerator:



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



Output:



0 foo
1 bar
2 2



Related: #each, #reverse_each.


  





  


  [ GitHub ]


  

  


# File 'array.c', line 2567



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


  








  

    #eql?(other_array)  ⇒ Boolean   



  

    

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



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



Otherwise, returns false.



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


  



  [ GitHub ]


  

  


# File 'array.c', line 5077



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)  ⇒ element 
      #fetch(index, default_value)  ⇒ element 
      #fetch(index) {|index| ... } ⇒ element 
    

  



  

    

Returns the element at offset  #index.



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



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



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



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



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



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



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



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


  





  


  [ GitHub ]


  

  


# File 'array.c', line 1977



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

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

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


  








  

    

      #fill(obj)  ⇒ self 
      #fill(obj, start)  ⇒ self 
      #fill(obj, start, length)  ⇒ self 
      #fill(obj, range)  ⇒ self 
      #fill {|index| ... } ⇒ self 
      #fill(start) {|index| ... } ⇒ self 
      #fill(start, length) {|index| ... } ⇒ self 
      #fill(range) {|index| ... } ⇒ self 
    

  



  

    

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



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



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



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



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



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



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



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



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



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



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



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



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



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



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



If start is negative, counts from the end:



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



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



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



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



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



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



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



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



If range.first is negative, replaces no elements:



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



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



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



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



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



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



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



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



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



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



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



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



If start is negative, counts from the end:



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



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



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



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



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



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



If start is negative, counts from the end:



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



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



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



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



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



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



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



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



If range.first is negative, does nothing:



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



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



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



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



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


  





  


  [ GitHub ]


  

  


# File 'array.c', line 4723



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 {|element| ... } ⇒ Array 
      #select  ⇒ Enumerator 
    

    Also known as: #select
  



  

    

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



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



Returns a new Enumerator if no block given:



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



filter is an alias for #select.


  





  


  [ GitHub ]


  

  


# File 'array.c', line 3792



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! {|element| ... } ⇒ self? 
      #select!  ⇒ Enumerator 
    

    Also known as: #select!
  



  

    

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



Returns self if any elements were removed:



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



Returns nil if no elements were removed.



Returns a new Enumerator if no block given:



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



filter! is an alias for #select!.


  





  


  [ GitHub ]


  

  


# File 'array.c', line 3874



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


  








  

    

      #index(object)  ⇒ Integer? 
      #index {|element| ... } ⇒ Integer? 
      #index  ⇒ Enumerator 
    

  



  

    

Alias for #index.


  





  








  

    

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

  



  

    

Returns elements from self; does not modify self.



When no argument is given, returns the first element:



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



If self is empty, returns nil.



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



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



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



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



If n == 0 returns an new empty Array:



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



Related: #last.


  





  


  [ GitHub ]


  

  


# File 'array.c', line 1889



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 recursive flattening of self:


  • 

    Each non-Array element is unchanged.
    

  • 

    Each Array is replaced by its individual elements.
    




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



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



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



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


  





  


  [ GitHub ]


  

  


# File 'array.c', line 6302



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

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

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

    return result;
}


  








  

    

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

  



  

    

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



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



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



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



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


  





  


  [ GitHub ]


  

  


# File 'array.c', line 6250



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   



  

    

Returns the integer hash value for self.



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



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


  



  [ GitHub ]


  

  


# File 'array.c', line 5098



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?(obj)  ⇒ Boolean   



  

    

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



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


  



  [ GitHub ]


  

  


# File 'array.c', line 5125



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

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


  








  

    

      #index(object)  ⇒ Integer? 
      #index {|element| ... } ⇒ Integer? 
      #index  ⇒ Enumerator 
    

    Also known as: #find_index
  



  

    

Returns the index of a specified element.



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



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



Returns nil if no such element found.



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



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



Returns nil if the block never returns a truthy value.



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



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



#find_index is an alias for index.



Related: #rindex.


  





  


  [ GitHub ]


  

  


# File 'array.c', line 2040



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_array)  ⇒ self 
      #initialize_copy(other_array)  ⇒ self 
    

  



  

    

Alias for #replace.


  





  








  

    #insert(index, *objects)  ⇒ self   



  

    

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



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



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



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



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



Does nothing if no objects given:



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



When #index is negative, inserts all given objects after the element at offset #indexself.size</tt>:



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


  



  [ GitHub ]


  

  


# File 'array.c', line 2444



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


  








  

    

      #to_s  ⇒ String 
      #inspect  ⇒ String 
    

  



  

    

Alias for #to_s.


  





  








  

    #intersection(*other_arrays)  ⇒ Array   



  

    

Returns a new Array containing each element found both in self and in all of the given Arrays other_arrays; duplicates are omitted; items are compared using #eql?:



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



Preserves order from self:



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



Returns a copy of self if no arguments given.



Related: #&.


  



  [ GitHub ]


  

  


# File 'array.c', line 5438



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

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

    return result;
}


  








  

    

      #join(->new_string)  
      #join(separator = $,)  ⇒ String 
    

  



  

    

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


  • 

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

  • 

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




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



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



With string argument separator, joins using that separator:



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



Joins recursively for nested Arrays:



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


  





  


  [ GitHub ]


  

  


# File 'array.c', line 2841



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

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

    return rb_ary_join(ary, sep);
}


  








  

    

      #keep_if {|element| ... } ⇒ self 
      #keep_if  ⇒ new_enumeration 
    

  



  

    

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



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



Returns a new Enumerator if no block given:



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


  





  


  [ GitHub ]


  

  


# File 'array.c', line 3902



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 elements from self; self is not modified.



When no argument is given, returns the last element:



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



If self is empty, returns nil.



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



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



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



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



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



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



Related: #first.


  





  


  [ GitHub ]


  

  


# File 'array.c', line 1931



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 count of elements in self.


  



  [ GitHub ]


  

  


# File 'array.c', line 2642



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


  








  

    

      #map {|element| ... } ⇒ Array 
      #map  ⇒ Enumerator 
    

    Also known as: #collect
  



  

    

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



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



Returns a new Enumerator if no block given:



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



#collect is an alias for map.


  





  


  [ GitHub ]


  

  


# File 'array.c', line 3626



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

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


  








  

    

      #map! {|element| ... } ⇒ self 
      #map!  ⇒ Enumerator 
    

    Also known as: #collect!
  



  

    

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



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



Returns a new Enumerator if no block given:



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



#collect! is an alias for map!.


  





  


  [ GitHub ]


  

  


# File 'array.c', line 3659



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  ⇒ element 
      #max {|a, b| ... } ⇒ element 
      #max(n)  ⇒ Array 
      #max(n) {|a, b| ... } ⇒ Array 
    

  



  

    

Returns one of the following:


  • 

    The maximum-valued element from self.
    

  • 

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




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



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



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



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



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



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



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



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



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



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


  





  


  [ GitHub ]


  

  


# File 'array.c', line 5684



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

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


  








  

    

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

  



  

    

Returns one of the following:


  • 

    The minimum-valued element from self.
    

  • 

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




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



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



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



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



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



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



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



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



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



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


  





  


  [ GitHub ]


  

  


# File 'array.c', line 5848



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

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


  








  

    

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

  



  

    

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



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



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



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



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


  





  


  [ GitHub ]


  

  


# File 'array.c', line 5909



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?  ⇒ Boolean 
      #none? {|element| ... } ⇒ Boolean 
      #none?(obj)  ⇒ Boolean 
    

  



  

    

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



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



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



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



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



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



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



Related: Enumerable#none?


  





  


  [ GitHub ]


  

  


# File 'array.c', line 7535



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?  ⇒ Boolean 
      #one? {|element| ... } ⇒ Boolean 
      #one?(obj)  ⇒ Boolean 
    

  



  

    

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



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



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



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



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



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



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



Related: Enumerable#one?


  





  


  [ GitHub ]


  

  


# File 'array.c', line 7596



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

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


  








  

    

      #pack(aTemplateString)  ⇒ aBinaryString 
      #pack(aTemplateString, buffer: aBufferString)  ⇒ aBufferString 
    

  



  

    

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



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



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



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



Directives for pack.



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

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

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

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


  





  


  [ GitHub ]


  

  


# File 'pack.rb', line 133



def pack(fmt, buffer: nil)
  Primitive.pack_pack(fmt, buffer)
end


  








  

    

      #permutation {|element| ... } ⇒ self 
      #permutation(n) {|element| ... } ⇒ self 
      #permutation  ⇒ Enumerator 
      #permutation(n)  ⇒ Enumerator 
    

  



  

    

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



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



Example:



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



Output:



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



Another example:



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



Output:



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



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



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



Output:



[]



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



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



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



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



Output:



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



Returns a new Enumerator if no block given:



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


  





  


  [ GitHub ]


  

  


# File 'array.c', line 6735



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 and returns trailing elements.



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



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



Returns nil if the array is empty.



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



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



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



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



Related: #push, #shift, #unshift.


  





  


  [ GitHub ]


  

  


# File 'array.c', line 1396



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

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

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


  








  

    #prepend(*objects)  ⇒ self     Also known as: #unshift
  



  

    

Prepends the given objects to self:



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



prepend is an alias for #unshift.



Related: #push, #pop, #shift.


  



  [ GitHub ]


  

  


# File 'array.c', line 1636



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


  








  

    

      #product(*other_arrays)  ⇒ Array 
      #product(*other_arrays) {|combination| ... } ⇒ self 
    

  



  

    

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


  • 

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

  • 

    The order of the returned combinations is indeterminate.
    




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



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



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



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



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



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



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



Output:



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



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



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



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



a.product {|combination| p combination }



Output:



[0]
[1]
[2]


  





  


  [ GitHub ]


  

  


# File 'array.c', line 7186



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(*objects)  ⇒ self     Also known as: #append
  



  

    

Appends trailing elements.



Appends each argument in objects to self;  returns self:



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



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



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



#append is an alias for Array#push.



Related: #pop, #shift, #unshift.


  



  [ GitHub ]


  

  


# File 'array.c', line 1343



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


  








  

    #rassoc(obj)  ⇒ Array?   



  

    

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



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



Returns nil if no such element is found.



Related: #assoc.


  



  [ GitHub ]


  

  


# File 'array.c', line 4966



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 {|element| ... } ⇒ Array 
      #reject  ⇒ Enumerator 
    

  



  

    

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



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



Returns a new Enumerator if no block given:



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


  





  


  [ GitHub ]


  

  


# File 'array.c', line 4267



static VALUE
rb_ary_reject(VALUE ary)
{
    VALUE rejected_ary;

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


  








  

    

      #reject! {|element| ... } ⇒ self? 
      #reject!  ⇒ Enumerator 
    

  



  

    

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



Returns self if any elements removed:



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



Returns nil if no elements removed.



Returns a new Enumerator if no block given:



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


  





  


  [ GitHub ]


  

  


# File 'array.c', line 4243



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


  








  

    

      #repeated_combination(n) {|combination| ... } ⇒ self 
      #repeated_combination(n)  ⇒ Enumerator 
    

  



  

    

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



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



n = 1:



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



Output:



[0]
[1]
[2]



n = 2:



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



Output:



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



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



If n is negative, does not call the block:



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



Returns a new Enumerator if no block given:



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



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



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


  





  


  [ GitHub ]


  

  


# File 'array.c', line 7102



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

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

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


  








  

    

      #repeated_permutation(n) {|permutation| ... } ⇒ self 
      #repeated_permutation(n)  ⇒ Enumerator 
    

  



  

    

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



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



n = 1:



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



Output:



[0]
[1]
[2]



n = 2:



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



Output:



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



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



If n is negative, does not call the block:



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



Returns a new Enumerator if no block given:



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



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



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


  





  


  [ GitHub ]


  

  


# File 'array.c', line 6982



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

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

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

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


  








  

    #replace(other_array)  ⇒ self     Also known as: #initialize_copy
  



  

    

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



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


  



  [ GitHub ]


  

  


# File 'array.c', line 4483



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 with the elements of self in reverse order.



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


  



  [ GitHub ]


  

  


# File 'array.c', line 3038



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!  ⇒ self   



  

    

Reverses self in place:



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


  



  [ GitHub ]


  

  


# File 'array.c', line 3022



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


  








  

    

      #reverse_each {|element| ... } ⇒ self 
      #reverse_each  ⇒ Enumerator 
    

  



  

    

Iterates backwards over array elements.



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



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



Output:



Integer 2
String bar
Symbol foo



Allows the array to be modified during iteration:



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



Output:



2
bar



When no block given, returns a new Enumerator:



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



Output:



Integer 2
String bar
Symbol foo



Related: #each, #each_index.


  





  


  [ GitHub ]


  

  


# File 'array.c', line 2617



static VALUE
rb_ary_reverse_each(VALUE ary)
{
    long len;

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


  








  

    

      #rindex(object)  ⇒ Integer? 
      #rindex {|element| ... } ⇒ Integer? 
      #rindex  ⇒ Enumerator 
    

  



  

    

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



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



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



Returns nil if no such object found.



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



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



Returns nil if the block never returns a truthy value.



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



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



Related: #index.


  





  


  [ GitHub ]


  

  


# File 'array.c', line 2099



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  ⇒ Array 
      #rotate(count)  ⇒ Array 
    

  



  

    

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



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



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



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



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



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



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



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



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



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



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



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



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


  





  


  [ GitHub ]


  

  


# File 'array.c', line 3182



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!  ⇒ self 
      #rotate!(count)  ⇒ self 
    

  



  

    

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



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



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



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



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



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



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



If #count is zero, returns self unmodified:



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



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



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



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



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


  





  


  [ GitHub ]


  

  


# File 'array.c', line 3132



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


  








  

    

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

  



  

    

Returns random elements from self.



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



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



If self is empty, returns nil.



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



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



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



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



But self may contain duplicates:



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



Returns a new empty Array if self is empty.



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



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


  





  


  [ GitHub ]


  

  


# File 'array.rb', line 58



def sample(n = (ary = false), random: Random)
  Primitive.rb_ary_sample(random, n, ary)
end


  








  

    

      #select {|element| ... } ⇒ Array 
      #select  ⇒ Enumerator 
    

  



  

    

Alias for #filter.


  





  








  

    

      #select! {|element| ... } ⇒ self? 
      #select!  ⇒ Enumerator 
    

  



  

    

Alias for #filter!.


  





  








  

    

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

  



  

    

Removes and returns leading elements.



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



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



Returns nil if self is empty.



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



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



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



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



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



Related: #push, #pop, #unshift.


  





  


  [ GitHub ]


  

  


# File 'array.c', line 1476



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

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

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

    return result;
}


  








  

    #shuffle(random: Random)  ⇒ 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 random argument will be used as the random number generator:



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


  



  [ GitHub ]


  

  


# File 'array.rb', line 26



def shuffle(random: Random)
  Primitive.rb_ary_shuffle(random)
end


  








  

    #shuffle!(random: Random)  ⇒ Array   



  

    

Shuffles the elements of self in place.



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



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



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


  



  [ GitHub ]


  

  


# File 'array.rb', line 12



def shuffle!(random: Random)
  Primitive.rb_ary_shuffle_bang(random)
end


  








  

    

      #length  ⇒ Integer 
      #size  ⇒ Integer 
    

  



  

    

Alias for #length.


  





  








  

    

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

  



  

    

Alias for #[].


  





  








  

    

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

  



  

    

Removes and returns elements from self.



When the only argument is an Integer n, removes and returns the nth element in self:



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



If n is negative, counts backwards from the end of self:



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



If n is out of range, returns nil.



When the only arguments are Integers start and #length, removes #length elements from self beginning at offset  start; returns the deleted objects in a new Array:



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



If start + length exceeds the array size, removes and returns all elements from offset start to the end:



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



If start == a.size and #length is non-negative, returns a new empty Array.



If #length is negative, returns nil.



When the only argument is a Range object range, treats range.min as start above and range.size as #length above:



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



If range.start == a.size, returns a new empty Array.



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



If range.end is negative, counts backwards from the end of the array:



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



If range.start is negative, calculates the start index backwards from the end of the array:



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


  





  


  [ GitHub ]


  

  


# File 'array.c', line 4149



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

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

    if (argc == 2) {
	pos = NUM2LONG(argv[0]);
	len = NUM2LONG(argv[1]);
        return ary_slice_bang_by_rb_ary_splice(ary, pos, len);
    }

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

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


  








  

    

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

  



  

    

Returns a new Array whose elements are those from self, sorted.



With no block, compares elements using operator #<=> (see ::Comparable):



a = 'abcde'.split('').shuffle
a # => ["e", "b", "d", "a", "c"]
a1 = a.sort
a1 # => ["a", "b", "c", "d", "e"]



With a block, calls the block with each element pair; for each element pair a and b, the block should return an integer:


  • 

    Negative when b is to follow a.
    

  • 

    Zero when a and b are equivalent.
    

  • 

    Positive when a is to follow b.
    




Example:



a = 'abcde'.split('').shuffle
a # => ["e", "b", "d", "a", "c"]
a1 = a.sort {|a, b| a <=> b }
a1 # => ["a", "b", "c", "d", "e"]
a2 = a.sort {|a, b| b <=> a }
a2 # => ["e", "d", "c", "b", "a"]



When the block returns zero, the order for a and b is indeterminate, and may be unstable:



a = 'abcde'.split('').shuffle
a # => ["e", "b", "d", "a", "c"]
a1 = a.sort {|a, b| 0 }
a1 # =>  ["c", "e", "b", "d", "a"]



Related: Enumerable#sort_by.


  





  


  [ GitHub ]


  

  


# File 'array.c', line 3395



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


  








  

    

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

  



  

    

Returns self with its elements sorted in place.



With no block, compares elements using operator #<=> (see ::Comparable):



a = 'abcde'.split('').shuffle
a # => ["e", "b", "d", "a", "c"]
a.sort!
a # => ["a", "b", "c", "d", "e"]



With a block, calls the block with each element pair; for each element pair a and b, the block should return an integer:


  • 

    Negative when b is to follow a.
    

  • 

    Zero when a and b are equivalent.
    

  • 

    Positive when a is to follow b.
    




Example:



a = 'abcde'.split('').shuffle
a # => ["e", "b", "d", "a", "c"]
a.sort! {|a, b| a <=> b }
a # => ["a", "b", "c", "d", "e"]
a.sort! {|a, b| b <=> a }
a # => ["e", "d", "c", "b", "a"]



When the block returns zero, the order for a and b is indeterminate, and may be unstable:



a = 'abcde'.split('').shuffle
a # => ["e", "b", "d", "a", "c"]
a.sort! {|a, b| 0 }
a # => ["d", "e", "c", "a", "b"]


  





  


  [ GitHub ]


  

  


# File 'array.c', line 3297



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! {|element| ... } ⇒ self 
      #sort_by!  ⇒ Enumerator 
    

  



  

    

Sorts the elements of self in place, using an ordering determined by the block; returns self.



Calls the block with each successive element; sorts elements based on the values returned from the block.



For duplicates returned by the block, the ordering is indeterminate, and may be unstable.



This example sorts strings based on their sizes:



a = ['aaaa', 'bbb', 'cc', 'd']
a.sort_by! {|element| element.size }
a # => ["d", "cc", "bbb", "aaaa"]



Returns a new Enumerator if no block given:



a = ['aaaa', 'bbb', 'cc', 'd']
a.sort_by! # => #<Enumerator: ["aaaa", "bbb", "cc", "d"]:sort_by!>


  





  


  [ GitHub ]


  

  


# File 'array.c', line 3594



static VALUE
rb_ary_sort_by_bang(VALUE ary)
{
    VALUE sorted;

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


  








  

    

      #sum(init = 0)  ⇒ Object 
      #sum(init = 0) {|element| ... } ⇒ Object 
    

  



  

    

When no block is given, returns the object equivalent to:



sum = init
array.each {|element| sum += element }
sum



For example, [e1, e2, e3].sum returns </tt>init + e1 + e2 + e3</tt>.



Examples:



a = [0, 1, 2, 3]
a.sum # => 6
a.sum(100) # => 106



The elements need not be numeric, but must be +-compatible with each other and with init:



a = ['abc', 'def', 'ghi']
a.sum('jkl') # => "jklabcdefghi"



When a block is given, it is called with each element and the block’s return value (instead of the element itself) is used as the addend:



a = ['zero', 1, :two]
s = a.sum('Coerced and concatenated: ') {|element| element.to_s }
s # => "Coerced and concatenated: zero1two"



Notes:


  • 

    #join and #flatten may be faster than sum for an Array of Strings or an Array of Arrays.
    

  • 

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



  





  


  [ GitHub ]


  

  


# File 'array.c', line 7708



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 https://link.springer.com/article/10.1007/s00607-005-0139-x
         */
        double f, c;
        double x, t;

        f = NUM2DBL(v);
        c = 0.0;
        goto has_float_value;
        for (; i < RARRAY_LEN(ary); i++) {
            e = RARRAY_AREF(ary, i);
            if (block_given)
                e = rb_yield(e);
            if (RB_FLOAT_TYPE_P(e))
              has_float_value:
                x = RFLOAT_VALUE(e);
            else if (FIXNUM_P(e))
                x = FIX2LONG(e);
            else if (RB_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 a new Array containing the first n element of self, where n is a non-negative Integer; does not modify self.



Examples:



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


  



  [ GitHub ]


  

  


# File 'array.c', line 7290



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


  








  

    

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

  



  

    

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



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



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



With no block given, returns a new Enumerator:



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


  





  


  [ GitHub ]


  

  


# File 'array.c', line 7320



static VALUE
rb_ary_take_while(VALUE ary)
{
    long i;

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


  








  

    #to_a  ⇒ self, Array   



  

    

When self is an instance of Array, returns self:



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



Otherwise, returns a new Array containing the elements of self:



class MyArray < Array; end
a = MyArray.new(['foo', 'bar', 'two'])
a.instance_of?(Array) # => false
a.kind_of?(Array) # => true
a1 = a.to_a
a1 # => ["foo", "bar", "two"]
a1.class # => Array # Not MyArray


  



  [ GitHub ]


  

  


# File 'array.c', line 2917



static VALUE
rb_ary_to_a(VALUE ary)
{
    if (rb_obj_class(ary) != rb_cArray) {
	VALUE dup = rb_ary_new2(RARRAY_LEN(ary));
	rb_ary_replace(dup, ary);
	return dup;
    }
    return ary;
}


  








  

    #to_ary  ⇒ self   



  

    

Returns self.


  



  [ GitHub ]


  

  


# File 'array.c', line 2981



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


  








  

    

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

  



  

    

Returns a new Hash formed from self.



When a block is given, calls the block with each array element; the block must return a 2-element Array whose two elements form a key-value pair in the returned Hash:



a = ['foo', :bar, 1, [2, 3], {baz: 4}]
h = a.to_h {|item| [item, item] }
h # => {"foo"=>"foo", :bar=>:bar, 1=>1, [2, 3]=>[2, 3], {:baz=>4}=>{:baz=>4}}



When no block is given, self must be an Array of 2-element sub-arrays, each sub-array is formed into a key-value pair in the new Hash:



[].to_h # => {}
a = [['foo', 'zero'], ['bar', 'one'], ['baz', 'two']]
h = a.to_h
h # => {"foo"=>"zero", "bar"=>"one", "baz"=>"two"}


  





  


  [ GitHub ]


  

  


# File 'array.c', line 2950



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

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


  








  

    #to_s  ⇒ String     Also known as: #inspect
  



  

    

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



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



to_s is an alias for #inspect.


  



  [ GitHub ]


  

  


# File 'array.c', line 2886



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


  








  

    #transpose  ⇒ Array   



  

    

Transposes the rows and columns in an Array of Arrays; the nested Arrays must all be the same size:



a = [[:a0, :a1], [:b0, :b1], [:c0, :c1]]
a.transpose # => [[:a0, :b0, :c0], [:a1, :b1, :c1]]


  



  [ GitHub ]


  

  


# File 'array.c', line 4446



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

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


  








  

    #union(*other_arrays)  ⇒ Array   



  

    

Returns a new Array that is the union of self and all given Arrays other_arrays; duplicates are removed;  order is preserved;  items are compared using #eql?:



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



Returns a copy of self if no arguments given.



Related: #|.


  



  [ GitHub ]


  

  


# File 'array.c', line 5532



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

  



  

    

Returns a new Array containing those elements from self that are not duplicates, the first occurrence always being retained.



With no block given, identifies and omits duplicates using method #eql? to compare.



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



With a block given, calls the block for each element; identifies (using method #eql?) and omits duplicate values, that is, those elements for which the block returns the same value:



a = ['a', 'aa', 'aaa', 'b', 'bb', 'bbb']
a.uniq {|element| element.size } # => ["a", "aa", "aaa"]


  





  


  [ GitHub ]


  

  


# File 'array.c', line 6003



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

    return uniq;
}


  








  

    

      #uniq!  ⇒ self? 
      #uniq! {|element| ... } ⇒ self? 
    

  



  

    

Removes duplicate elements from self, the first occurrence always being retained; returns self if any elements removed, nil otherwise.



With no block given, identifies and removes elements using method #eql? to compare.



Returns self if any elements removed:



a = [0, 0, 1, 1, 2, 2]
a.uniq! # => [0, 1, 2]



Returns nil if no elements removed.



With a block given, calls the block for each element; identifies (using method #eql?) and removes elements for which the block returns duplicate values.



Returns self if any elements removed:



a = ['a', 'aa', 'aaa', 'b', 'bb', 'bbb']
a.uniq! {|element| element.size } # => ['a', 'aa', 'aaa']



Returns nil if no elements removed.


  





  


  [ GitHub ]


  

  


# File 'array.c', line 5952



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


  








  

    

      #prepend(*objects)  ⇒ self 
      #unshift(*objects)  ⇒ self 
    

  



  

    

Alias for #prepend.


  





  








  

    #values_at(*indexes)  ⇒ Array   



  

    

Returns a new Array whose elements are the elements of self at the given Integer indexes.



For each positive #index, returns the element at offset #index:



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



The given indexes may be in any order, and may repeat:



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



Assigns nil for an #index that is too large:



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



Returns a new empty Array if no arguments given.



For each negative #index, counts backward from the end of the array:



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



Assigns nil for an #index that is too small:



a = [:foo, 'bar', 2]
a.values_at(0, -5, 1, -6, 2) # => [:foo, nil, "bar", nil, 2]



The given indexes may have a mixture of signs:



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


  



  [ GitHub ]


  

  


# File 'array.c', line 3760



static VALUE
rb_ary_values_at(int argc, VALUE *argv, VALUE ary)
{
    long i, olen = RARRAY_LEN(ary);
    VALUE result = rb_ary_new_capa(argc);
    for (i = 0; i < argc; ++i) {
	append_values_at_single(result, ary, olen, argv[i]);
    }
    RB_GC_GUARD(ary);
    return result;
}


  








  

    

      #zip(*other_arrays)  ⇒ Array 
      #zip(*other_arrays) {|other_array| ... } ⇒ nil 
    

  



  

    

When no block given, returns a new Array new_array of size self.size whose elements are Arrays.



Each nested array new_array[n] is of size other_arrays.size+1, and contains:


  • 

    The nth element of self.
    

  • 

    The nth element of each of the other_arrays.
    




If all other_arrays and self are the same size:



a = [:a0, :a1, :a2, :a3]
b = [:b0, :b1, :b2, :b3]
c = [:c0, :c1, :c2, :c3]
d = a.zip(b, c)
d # => [[:a0, :b0, :c0], [:a1, :b1, :c1], [:a2, :b2, :c2], [:a3, :b3, :c3]]



If any array in other_arrays is smaller than self, fills to self.size with nil:



a = [:a0, :a1, :a2, :a3]
b = [:b0, :b1, :b2]
c = [:c0, :c1]
d = a.zip(b, c)
d # => [[:a0, :b0, :c0], [:a1, :b1, :c1], [:a2, :b2, nil], [:a3, nil, nil]]



If any array in other_arrays is larger than self, its trailing elements are ignored:



a = [:a0, :a1, :a2, :a3]
b = [:b0, :b1, :b2, :b3, :b4]
c = [:c0, :c1, :c2, :c3, :c4, :c5]
d = a.zip(b, c)
d # => [[:a0, :b0, :c0], [:a1, :b1, :c1], [:a2, :b2, :c2], [:a3, :b3, :c3]]



When a block is given, calls the block with each of the sub-arrays (formed as above); returns nil



a = [:a0, :a1, :a2, :a3]
b = [:b0, :b1, :b2, :b3]
c = [:c0, :c1, :c2, :c3]
a.zip(b, c) {|sub_array| p sub_array} # => nil



Output:



[:a0, :b0, :c0]
[:a1, :b1, :c1]
[:a2, :b2, :c2]
[:a3, :b3, :c3]


  





  


  [ GitHub ]


  

  


# File 'array.c', line 4378



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



  

    

Returns the union of array and Array other_array; duplicates are removed; order is preserved; items are compared using #eql?:



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



Related: #union.


  



  [ GitHub ]


  

  


# File 'array.c', line 5496



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