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 the array 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
#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
#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?
#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
#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
#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

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

Returns a new Array.

Argument array, if given, must be an Array-convertible object (implements #to_ary).

Argument #size, if given must be an Integer-convertible object (implements to_int).

Argument default_value may be any object.


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

a = Array.new
a # => []

With no block and a single 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 argument #size, returns a new Array of the given size whose elements are all nil:

a = Array.new(0)
a # => []
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']
a[1].equal?(a[0]) # => true # Identity check.
a[2].equal?(a[0]) # => true # Identity check.

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

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

a = Array.new(0) { |n| raise 'Cannot happen' }
a # => []
a = Array.new { |n| raise 'Cannot happen' }
a # => []

With a block and arguments #size and default_value, gives a warning message ('warning: block supersedes default value argument'), and assigns elements from the block's return values:

Array.new(4, :default) {} # => [nil, nil, nil, nil]

Raises an exception if #size is a negative integer:

# Raises ArgumentError (negative array size):
Array.new(-1)
# Raises ArgumentError (negative array size):
Array.new(-1, :default)
# Raises ArgumentError (negative array size):
Array.new(-1) { |n| }

Raises an exception if the single argument is neither Array-convertible nor Integer-convertible.

# Raises TypeError (no implicit conversion of Symbol into Integer):
Array.new(:foo)
[ GitHub ]

  
# File 'array.c', line 1066

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 1131

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

Tries to convert object to an Array.

When object is an Array-convertible object (implements #to_ary), returns the Array object created by converting it:

class ToAryReturnsArray < Set
  def to_ary
    self.to_a
  end
end
as = ToAryReturnsArray.new([:foo, :bar, :baz])
Array.try_convert(as) # => [:foo, :bar, :baz]

Returns nil if object is not Array-convertible:

Array.try_convert(:foo) # => nil
[ GitHub ]

  
# File 'array.c', line 966

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 the array is zero, false otherwise:

[].empty? # => true
[:foo, 'bar', 2].empty? # => false
[ GitHub ]

  
# File 'array.c', line 2888

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

Instance Method Details

#&(other_ary) ⇒ Array

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

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

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

See also #uniq.

[ GitHub ]

  
# File 'array.c', line 5733

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

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

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

    hash = ary_make_hash(ary2);

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

    return ary3;
}

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

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

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

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

  
# File 'array.c', line 5196

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

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

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

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

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

#+(other_ary) ⇒ Array

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

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

Note that

x += y

is the same as

x = x + y

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

See also #concat.

[ GitHub ]

  
# File 'array.c', line 5104

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

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

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

#-(other_ary) ⇒ Array

Array Difference

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

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

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

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

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

See also #difference.

[ GitHub ]

  
# File 'array.c', line 5623

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]
a1 = a << :baz
a1 # => [:foo, "bar", 2, :baz]
a1.equal?(a) # => true # Returned self

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 1260

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

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

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

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

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

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

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

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

  
# File 'array.c', line 5524

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

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

#==(other_ary) ⇒ Boolean

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

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

  
# File 'array.c', line 5357

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? #slice(index) ⇒ Object? #slice(start, length) ⇒ Object? #slice(range) ⇒ Object?
Also known as: #slice

Returns elements from self; does not modify self.

  • Arguments #index, start, and #length, if given, must be Integer-convertible objects.

  • Argument range, if given, must be a Range object.


When a single 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:

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

When two 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:

a = [:foo, 'bar', 2]
a[a.size, 0] # => []
a[a.size, 50] # => []

If #length is negative, returns nil:

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

When a single 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:

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

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]
a[0..-4] # => []

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

Raises an exception if given a single argument that is not an Integer-convertible object or a Range object:

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

Raises an exception if given two arguments that are not both Integer-convertible objects:

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

  
# File 'array.c', line 1848

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.

  • Arguments #index, start, and #length, if given, must be Integer-convertible objects.

  • Argument range, if given, must be a Range object.

  • If object is an Array-convertible object it will be converted to an Array.


When #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 start and #length are given and object is not an Array-convertible object, 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 is given and object is an Array-convertible object, 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"]

Raises an exception if given a single argument that is not an Integer-convertible object or a Range:

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

Raises an exception if given two arguments that are not both Integer-convertible objects:

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

Raises an exception if a negative #index is out of range:

a = [:foo, 'bar', 2]
# Raises IndexError (index -4 too small for array; minimum: -3):
a[-4] = 'two'

Raises an exception if start is too small for the array:

a = [:foo, 'bar', 2]
# Raises IndexError (index -5 too small for array; minimum: -3):
a[-5, 2] = 'foo'

Raises an exception if #length is negative:

a = [:foo, 'bar', 2]
# Raises IndexError (negative length (-1)):
a[1, -1] = 'foo'
[ GitHub ]

  
# File 'array.c', line 2581

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

See also Enumerable#all?

[ GitHub ]

  
# File 'array.c', line 7382

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

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

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

See also Enumerable#any?

[ GitHub ]

  
# File 'array.c', line 7346

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) ⇒ element_ary?

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

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

See also #rassoc

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

  
# File 'array.c', line 5260

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

Argument #index must be an Integer-convertible object.

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

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

Raises an exception if #index is not an Integer-convertible object:

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

  
# File 'array.c', line 1910

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

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

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>

Raises an exception if the block returns an invalid value:

a = 'abcde'.split('').shuffle
# Raises TypeError (wrong argument type Symbol (must be numeric, true, false or nil)):
a.bsearch {|element| :foo }
[ GitHub ]

  
# File 'array.c', line 3836

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_indexEnumerator

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 3856

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

#clearArray

Removes all elements from self.

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

  
# File 'array.c', line 4966

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 #mapEnumerator #collect {|element| ... } ⇒ Array #collectEnumerator

Alias for #map.

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

Alias for #map!.

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

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

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

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

Examples:

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

  
# File 'array.c', line 6881

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

#compactArray

Returns a copy of self with all nil elements removed.

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

  
# File 'array.c', line 6193

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

#compact!Array?

Removes nil elements from the array.

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

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

  
# File 'array.c', line 6160

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

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

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

    return ary;
}

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

Appends the elements of other_arys to self.

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

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

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

See also #+.

[ GitHub ]

  
# File 'array.c', line 5152

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

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

Returns the number of elements.

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

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

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

  
# File 'array.c', line 6222

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

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

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

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

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

    return LONG2NUM(n);
}

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

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

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

Returns nil if the loop has finished without getting interrupted.

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

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

  
# File 'array.c', line 6617

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 7690

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]
deleted_obj = a.delete('bar')
a # => [:foo, 2]
deleted_obj.equal?(s2) # => true # Returned self

Returns nil if no elements removed:

a = [:foo, 'bar', 2]
a.delete(:nosuch) # => nil

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]
deleted_obj.object_id == s2.object_id # => true

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 4343

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

The given #index must be an Integer-convertible object.


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:

a = [:foo, 'bar', 2]
a.delete_at(5) # => 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:

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

Raises an exception if index is not an Integer-convertible object:

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

  
# File 'array.c', line 4458

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

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

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

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

See also #reject!

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

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

  
# File 'array.c', line 4743

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

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

Array Difference

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

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

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

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

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

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

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

See also #-.

[ GitHub ]

  
# File 'array.c', line 5680

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

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

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

    ALLOCV_END(t0);

    return ary_diff;
}

#dig(idx, ...) ⇒ Object

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

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

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

  
# File 'array.c', line 7508

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

#drop(n) ⇒ Array

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

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

See also #take

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

  
# File 'array.c', line 7294

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

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

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

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

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

See also #take_while

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

  
# File 'array.c', line 7326

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

Iterates over array elements.


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

a = [:foo, 'bar', 2]
a1 = a.each {|element|  puts "#{element.class} #{element}" }
a1.equal?(a) # => true # Returned self

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') }
a # => []

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

  
# File 'array.c', line 2734

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_indexEnumerator

Iterates over array indexes.


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

a = [:foo, 'bar', 2]
a1 = a.each_index {|index|  puts "#{index} #{a[index]}" }
a1.equal?(a) # => true # Returned self

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 }
a # => []

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

  
# File 'array.c', line 2789

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

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

[ GitHub ]

  
# File 'array.c', line 5393

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.

Argument #index must be an Integer-convertible object


With the single 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"
a.fetch(50, nil) # => nil

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"

Raises an exception if #index is not an Integer-convertible object.

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

Raises an exception if #index is out of range and neither default_value nor a block given:

a = [:foo, 'bar', 2]
# Raises IndexError (index 50 outside of array bounds: -3...3):
a.fetch(50)
[ GitHub ]

  
# File 'array.c', line 2090

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

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

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

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

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

A start of nil is equivalent to zero.

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

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

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

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

  
# File 'array.c', line 5017

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 #selectEnumerator #filter {|element| ... } ⇒ Array #filterEnumerator
Also known as: #select

filter is an alias for #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>
[ GitHub ]

  
# File 'array.c', line 4163

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 #filter! {|element| ... } ⇒ self? #filter!Enumerator
Also known as: #select!

filter! is an alias for #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]
a1 = a.select! {|element| element.to_s.start_with?('b') }
a1 # => ["bar", :bam]
a1.equal?(a) # => true # Returned self

Returns nil if no elements were removed:

a = [:foo, 'bar', 2, :bam]
a.select! { |element| element.kind_of?(Object) } # => nil

Returns a new Enumerator if no block given:

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

  
# File 'array.c', line 4252

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? #indexEnumerator #find_index(object) ⇒ Integer? #find_index {|element| ... } ⇒ Integer? #find_indexEnumerator

Alias for #index.

#firstObject? #first(n) ⇒ Array

Returns elements from self; does not modify self. See also #last.

Argument n, if given, must be an Integer-convertible object.


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:

[].first # => nil

When argument n is given, returns the first n elements in a new Array:

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

If n >= ary.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) # []

Raises an exception if n is negative:

a = [:foo, 'bar', 2]
# Raises ArgumentError (negative array size):
a.first(-1)

Raises an exception if n is not an Integer-convertible object:

a = [:foo, 'bar', 2]
# Raises TypeError (no implicit conversion of String into Integer):
a.first(:X)
[ GitHub ]

  
# File 'array.c', line 1963

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

#flattenArray #flatten(level) ⇒ Array

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

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

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

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

  
# File 'array.c', line 6400

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

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

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

    return result;
}

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

Flattens self in place.

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

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

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

  
# File 'array.c', line 6356

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

#hashInteger

Compute a hash-code for this array.

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

See also Object#hash.

[ GitHub ]

  
# File 'array.c', line 5415

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

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

#include?(object) ⇒ Boolean

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

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

  
# File 'array.c', line 5444

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? #indexEnumerator #find_index(object) ⇒ Integer? #find_index {|element| ... } ⇒ Integer? #find_indexEnumerator
Also known as: #find_index

#find_index is an alias for index. See also #rindex.

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:

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

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:

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

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

When both an argument and a block given, gives a warning (warning: given block not used) and ignores the block:

a = [:foo, 'bar', 2, 'bar']
index = a.index('bar') { raise 'Cannot happen' }
index # => 1
[ GitHub ]

  
# File 'array.c', line 2173

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

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

#replace(other_ary) ⇒ Array #initialize_copy(other_ary) ⇒ Array

Alias for #replace.

#insert(index, *objects) ⇒ self

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

Argument #index must be an Integer-convertible object.


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

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

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]

Raises an exception if #index is not an Integer-convertible object:

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

Raises an exception if #index is too small (#indexself.size < 0</tt>):

a = [:foo, 'bar', 2]
# Raises IndexError (index -5 too small for array; minimum: -4):
a.insert(-5, :bat, :bam)
[ GitHub ]

  
# File 'array.c', line 2658

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

#inspectString #to_sString

Alias for #to_s.

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

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

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

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

See also #&.

[ GitHub ]

  
# File 'array.c', line 5785

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

Argument separator, if given, must be a String-convertible object.


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

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

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

Raises an exception if separator is not a String-convertible object:

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

Raises an exception if any element lacks instance method #to_s:

a = [:foo, 'bar', 2, BasicObject.new]
# Raises NoMethodError (undefined method `to_s' for #<BasicObject>):
a.join
[ GitHub ]

  
# File 'array.c', line 3091

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

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

    return rb_ary_join(ary, sep);
}

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

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

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

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 4282

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

#lastObject? #last(n) ⇒ Array

Returns elements from self; self is not modified. See also #first.

Argument n, if given, must be an Integer-convertible object.


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:

[].last # => nil

When argument n is given, returns the last n elements in a new Array:

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

If n >= ary.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) # []

Raises an exception if n is negative:

a = [:foo, 'bar', 2]
# Raises ArgumentError (negative array size):
a.last(-1)

Raises an exception if n is not an Integer-convertible object:

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

  
# File 'array.c', line 2023

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

#lengthInteger Also known as: #size

Returns the count of elements in the array:

a = [:foo, 'bar', 2]
a.length # => 3
[].length # => 0
[ GitHub ]

  
# File 'array.c', line 2871

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

#map {|element| ... } ⇒ Array #mapEnumerator #collect {|element| ... } ⇒ Array #collectEnumerator
Also known as: #collect

map is an alias for #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.collect {|element| element.class }
a1 # => [Symbol, String, Integer]

Returns a new Enumerator if no block given:

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

  
# File 'array.c', line 3972

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 #collect! {|element| ... } ⇒ self #collect!Enumerator
Also known as: #collect!

map! is an alias for #collect!.

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

a = [:foo, 'bar', 2]
a1 = a.collect! { |element| element.class }
a1 # => [Symbol, String, Integer]
a1.equal?(a) # => true # Returned self

Returns a new Enumerator if no block given:

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

  
# File 'array.c', line 4011

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

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

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

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

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

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

  
# File 'array.c', line 5933

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

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

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

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

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

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

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

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

  
# File 'array.c', line 5986

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

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

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

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

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

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

[ GitHub ]

  
# File 'array.c', line 6028

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

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

See also Enumerable#none?

[ GitHub ]

  
# File 'array.c', line 7418

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

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

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

See also Enumerable#one?

[ GitHub ]

  
# File 'array.c', line 7454

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

{Float}        | <code>Array</code>   |
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}       | <code>Array</code>   |
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.        | <code>Array</code>   |
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 {|p| ... } ⇒ Array #permutationEnumerator #permutation(n) {|p| ... } ⇒ Array #permutation(n) ⇒ Enumerator

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

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

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

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

Examples:

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

  
# File 'array.c', line 6788

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

#popObject? #pop(n) ⇒ Array

Removes and returns trailing elements.

See also:

  • #push: Appends trailing elements.

  • #shift: Removes and returns leading elements.

  • #unshift: Prepends leading elements.

Argument n, if given, must be an Integer-convertible object (implements to_int).


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

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

Returns nil if the array is empty:

a = []
a.pop # => nil

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

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

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

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

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

Raises an exception if n is negative:

a = [:foo, 'bar', 2]
# Raises ArgumentError (negative array size):
a1 = a.pop(-1)

Raises an exception if n is not Integer-convertible (implements to_int):

a = [:foo, 'bar', 2]
# Raises TypeError (no implicit conversion of String into Integer):
a1 = a.pop('x')
[ GitHub ]

  
# File 'array.c', line 1401

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

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

prepend is an alias for #unshift.

Prepends leading elements.

See also:

  • #push: Appends trailing elements.

  • #pop: Removes and returns trailing elements.

  • #shift: Removes and returns leading elements.

Prepends the given objects to self:

a = [:foo, 'bar', 2]
a1 = a.unshift(:bam, :bat)
a1 # => [:bam, :bat, :foo, "bar", 2]
a1.equal?(a) # => true # Returned self
[ GitHub ]

  
# File 'array.c', line 1677

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_ary, ...) ⇒ Array #product(other_ary, ...) {|p| ... } ⇒ Array

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

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

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

[1,2,3].product([4,5])     #=> [[1,4],[1,5],[2,4],[2,5],[3,4],[3,5]]
[1,2].product([1,2])       #=> [[1,1],[1,2],[2,1],[2,2]]
[1,2].product([3,4],[5,6]) #=> [[1,3,5],[1,3,6],[1,4,5],[1,4,6],
                           #     [2,3,5],[2,3,6],[2,4,5],[2,4,6]]
[1,2].product()            #=> [[1],[2]]
[1,2].product([])          #=> []
[ GitHub ]

  
# File 'array.c', line 7136

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

#append is an alias for Array#push.

Appends trailing elements.

See also:

  • #pop: Removes and returns trailing elements.

  • #shift: Removes and returns leading elements.

  • #unshift: Prepends leading elements.

Appends each argument in objects to self; returns self:

a = [:foo, 'bar', 2]
a1 = a.push(:baz, :bat)
a1 # => [:foo, "bar", 2, :baz, :bat]
a1.equal?(a) # => true # Returned self

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

  
# File 'array.c', line 1310

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

#rassoc(obj) ⇒ element_ary?

Searches through the array whose elements are also arrays.

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

Returns the first contained array that matches obj.

See also #assoc.

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

  
# File 'array.c', line 5293

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

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

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

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

See also #delete_if

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

[ GitHub ]

  
# File 'array.c', line 4714

static VALUE
rb_ary_reject(VALUE ary)
{
    VALUE rejected_ary;

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

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

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

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

See also Enumerable#reject and #delete_if.

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

[ GitHub ]

  
# File 'array.c', line 4693

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

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

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

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

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

Examples:

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

  
# File 'array.c', line 7080

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

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

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

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

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

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

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

Examples:

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

  
# File 'array.c', line 6986

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

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

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

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

#replace(other_ary) ⇒ Array #initialize_copy(other_ary) ⇒ Array
Also known as: #initialize_copy

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

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

  
# File 'array.c', line 4915

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

#reverseArray

Returns a new Array whose elements are in reverse order:

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

  
# File 'array.c', line 3315

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']
a1 = a.reverse!
a1 # => ["two", "bar", "foo"]
a1.equal?(a) # => true # Returned self
[ GitHub ]

  
# File 'array.c', line 3299

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

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

Iterates backwards over array elements.


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

a = [:foo, 'bar', 2]
a1 = a.reverse_each {|element|  puts "#{element.class} #{element}" }
a1.equal?(a) # => true # Returned self

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') }
a # => []

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

  
# File 'array.c', line 2843

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? #rindexEnumerator

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:

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

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:

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

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

When both an argument and a block given, gives a warning (warning: given block not used) and ignores the block:

a = [:foo, 'bar', 2, 'bar']
index = a.rindex('bar') { raise 'Cannot happen' }
index # => 3
[ GitHub ]

  
# File 'array.c', line 2249

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

#rotateArray #rotate(count) ⇒ Array

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

Argument #count, if given, must be an Integer-convertible object.


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 #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 % ary.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 #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 % ary.size as the count:

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

Raises an exception if #count is not an Integer-convertible object:

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

  
# File 'array.c', line 3491

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.

Argument #count, if given, must be an Integer-convertible object.


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

a = [:foo, 'bar', 2, 'bar']
a1 = a.rotate!
a1 # => ["bar", 2, "bar", :foo]
a1.equal?(a1) # => true # Retruned self

When given a non-negative #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 % ary.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 #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 % ary.size as the count:

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

Raises an exception if #count is not an Integer-convertible object:

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

  
# File 'array.c', line 3426

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

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

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

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

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

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

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

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

  
# File 'array.rb', line 59

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

#select {|element| ... } ⇒ Array #selectEnumerator #filter {|element| ... } ⇒ Array #filterEnumerator

Alias for #filter.

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

Alias for #filter!.

#shiftObject? #shift(n) ⇒ Array

Removes and returns leading elements.

See also:

  • #push: Appends trailing elements.

  • #pop: Removes and returns trailing elements.

  • #unshift: Prepends leading elements.

Argument n, if given, must be an Integer-convertible object


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:

[].shift # => nil

When 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]
a # => []

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

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

Raises an exception if n is negative:

a = [:foo, 'bar', 2]
# Raises ArgumentError (negative array size):
a1 = a.shift(-1)

Raises an exception if n is not an Integer-convertible object:

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

  
# File 'array.c', line 1509

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

#shuffleArray #shuffle(random: rng) ⇒ Array

Returns a new array with elements of self shuffled.

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

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

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

  
# File 'array.rb', line 32

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

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

Shuffles elements in self in place.

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

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

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

  
# File 'array.rb', line 15

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

#lengthInteger #sizeInteger

Alias for #length.

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

Alias for #[].

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

Removes and returns elements from self.

  • Argument n, if given must be an Integer object.

  • Arguments start and #length, if given must be Integer objects.

  • Argument range, if given, must be a Range object.


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:

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

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:

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

If #length is negative, returns nil:

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

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:

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

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

a = [:foo, 'bar', 2]
a.slice!(4..1) # => nil
a.slice!(4..0) # => nil
a.slice!(4..-1) # => 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]

Raises an exception if given a single argument that is not an Integer or a Range:

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

Raises an exception if given two arguments that are not both Integers:

a = [:foo, 'bar', 2]
# Raises TypeError (no implicit conversion of Symbol into Integer):
a.slice!(:foo, 3)
# Raises TypeError (no implicit conversion of Symbol into Integer):
a.slice!(1, :bar)
[ GitHub ]

  
# File 'array.c', line 4602

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

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

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

See also Enumerable#sort_by.


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

Raises an exception if the block returns a non-Integer:

a = 'abcde'.split('').shuffle
# Raises ArgumentError (comparison of Symbol with 0 failed):
a1 = a.sort {|a, b| :foo }
[ GitHub ]

  
# File 'array.c', line 3726

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

Raises an exception if the block returns a non-Integer:

a = 'abcde'.split('').shuffle
# Raises ArgumentError (comparison of Symbol with 0 failed):
a1 = a.sort! {|a, b| :foo }
[ GitHub ]

  
# File 'array.c', line 3617

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 3936

static VALUE
rb_ary_sort_by_bang(VALUE ary)
{
    VALUE sorted;

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

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

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

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

If ary is empty, it returns init.

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

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

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

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

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

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

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

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

[ GitHub ]

  
# File 'array.c', line 7580

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

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

    block_given = rb_block_given_p();

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

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

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

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

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

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

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

      not_float:
        v = DBL2NUM(f);
    }

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

#take(n) ⇒ Array

Returns first n elements from the array.

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

See also #drop

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

  
# File 'array.c', line 7239

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

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

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

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

See also #drop_while

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

  
# File 'array.c', line 7266

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_aself, Array

When self is an instance of Array, returns self:

a = [:foo, 'bar', 2]
a.instance_of?(Array) # => true
a1 = a.to_a
a1.equal?(a) # => true # Returned self

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 3175

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_aryself

Returns self:

a = [:foo, 'bar', 2]
a1 = a.to_ary
a1.equal?(a) # => true # Returned self
[ GitHub ]

  
# File 'array.c', line 3256

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

#to_hHash #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"}

Raises an exception if no block is given and any element in self is not a 2-element Array:

# Raises TypeError (wrong element type Symbol at 0 (expected array):
[:foo].to_h
# Raises ArgumentError (wrong array length at 0 (expected 2, was 1)):
[[:foo]].to_h

Raises an exception if for some 2-element Array element in self, element.first would be an invalid hash key:

# Raises NoMethodError (undefined method `hash' for #<BasicObject:>):
[[BasicObject.new, 0]].to_h
[ GitHub ]

  
# File 'array.c', line 3222

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

#inspectString #to_sString
Also known as: #inspect

to_s is an alias for #inspect.

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

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

Raises an exception if any element lacks instance method #inspect:

a = [:foo, 'bar', 2, BasicObject.new]
a.inspect
# Raises NoMethodError (undefined method `inspect' for #<BasicObject>)
[ GitHub ]

  
# File 'array.c', line 3142

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

#transposeArray

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

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

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

[ GitHub ]

  
# File 'array.c', line 4874

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

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

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

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

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

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

See also #|.

[ GitHub ]

  
# File 'array.c', line 5881

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

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

Returns a new array by removing duplicate values in self.

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

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

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

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

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

  
# File 'array.c', line 6123

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

    if (RARRAY_LEN(ary) <= 1) {
        hash = 0;
        uniq = rb_ary_dup(ary);
    }
    else if (rb_block_given_p()) {
	hash = ary_make_hash_by(ary);
	uniq = rb_hash_values(hash);
    }
    else {
	hash = ary_make_hash(ary);
	uniq = rb_hash_values(hash);
    }
    RBASIC_SET_CLASS(uniq, rb_obj_class(ary));
    if (hash) {
        ary_recycle_hash(hash);
    }

    return uniq;
}

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

Removes duplicate elements from self.

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

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

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

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

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

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

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

  
# File 'array.c', line 6071

static VALUE
rb_ary_uniq_bang(VALUE ary)
{
    VALUE hash;
    long hash_size;

    rb_ary_modify_check(ary);
    if (RARRAY_LEN(ary) <= 1)
        return Qnil;
    if (rb_block_given_p())
	hash = ary_make_hash_by(ary);
    else
	hash = ary_make_hash(ary);

    hash_size = RHASH_SIZE(hash);
    if (RARRAY_LEN(ary) == hash_size) {
	return Qnil;
    }
    rb_ary_modify_check(ary);
    ARY_SET_LEN(ary, 0);
    if (ARY_SHARED_P(ary) && !ARY_EMBED_P(ary)) {
	rb_ary_unshare(ary);
	FL_SET_EMBED(ary);
    }
    ary_resize_capa(ary, hash_size);
    rb_hash_foreach(hash, push_value, ary);
    ary_recycle_hash(hash);

    return ary;
}

#unshift(*objects) ⇒ self #prepend(*objects) ⇒ self

Alias for #prepend.

#values_at(*indexes) ⇒ Array

Returns a new Array whose elements are the elements of self at the given indexes.

Each #index given in indexes must be an Integer-convertible object.


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:

[].values_at # => []

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]

Raises an exception if any #index is not an Integer-convertible object:

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

  
# File 'array.c', line 4127

static VALUE
rb_ary_values_at(int argc, VALUE *argv, VALUE ary)
{
    long i, olen = RARRAY_LEN(ary);
    VALUE result = rb_ary_new_capa(argc);
    for (i = 0; i < argc; ++i) {
	append_values_at_single(result, ary, olen, argv[i]);
    }
    RB_GC_GUARD(ary);
    return result;
}

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

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

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

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

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

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

  
# File 'array.c', line 4803

static VALUE
rb_ary_zip(int argc, VALUE *argv, VALUE ary)
{
    int i, j;
    long len = RARRAY_LEN(ary);
    VALUE result = Qnil;

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

    if (rb_block_given_p()) {
	int arity = rb_block_arity();

	if (arity > 1) {
	    VALUE work, *tmp;

	    tmp = ALLOCV_N(VALUE, work, argc+1);

	    for (i=0; i<RARRAY_LEN(ary); i++) {
		tmp[0] = RARRAY_AREF(ary, i);
		for (j=0; j<argc; j++) {
		    tmp[j+1] = rb_ary_elt(argv[j], i);
		}
		rb_yield_values2(argc+1, tmp);
	    }

	    if (work) ALLOCV_END(work);
	}
	else {
	    for (i=0; i<RARRAY_LEN(ary); i++) {
		VALUE tmp = rb_ary_new2(argc+1);

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

	for (i=0; i<len; i++) {
	    VALUE tmp = rb_ary_new_capa(argc+1);

	    rb_ary_push(tmp, RARRAY_AREF(ary, i));
	    for (j=0; j<argc; j++) {
		rb_ary_push(tmp, rb_ary_elt(argv[j], i));
	    }
	    rb_ary_push(result, tmp);
	}
    }

    return result;
}

#|(other_ary) ⇒ Array

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

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

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

See also #union.

[ GitHub ]

  
# File 'array.c', line 5844

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