Class: Array

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

Overview

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

Class Method Summary collapse

Instance Method Summary collapse

Methods included from Enumerable

#all?, #any?, #detect, #each_cons, #each_slice, #each_with_index, #entries, #enum_cons, #enum_slice, #enum_with_index, #find, #find_all, #grep, #group_by, #inject, #max, #max_by, #member?, #min, #min_by, #minmax, #minmax_by, #none?, #one?, #partition, #reduce, #sort_by

Constructor Details

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

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

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

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

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

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

copy = Array.new(squares)

Overloads:



287
288
289
 
# File 'array.c', line 287

static VALUE
rb_ary_initialize(argc, argv, ary)
int argc;

Class Method Details

.[] ⇒ Object

Returns a new array populated with the given objects.

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



352
353
354
 
# File 'array.c', line 352

static VALUE
rb_ary_s_create(argc, argv, klass)
int argc;

Instance Method Details

#&(other_array) ⇒ Object

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

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



2873
2874
2875
 
# File 'array.c', line 2873

static VALUE
rb_ary_and(ary1, ary2)
VALUE ary1, ary2;

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

Repetition—With a String argument, equivalent to self.join(str). Otherwise, returns a new array built by concatenating the int copies of self.

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

Overloads:



2508
2509
2510
 
# File 'array.c', line 2508

static VALUE
rb_ary_times(ary, times)
VALUE ary, times;

#+(other_array) ⇒ 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 ]

Returns:



2455
2456
2457
 
# File 'array.c', line 2455

VALUE
rb_ary_plus(x, y)
VALUE x, y;

#-(other_array) ⇒ Array

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

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

Returns:



2844
2845
2846
 
# File 'array.c', line 2844

static VALUE
rb_ary_diff(ary1, ary2)
VALUE ary1, ary2;

#<<(obj) ⇒ Array

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

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

Returns:



465
466
467
 
# File 'array.c', line 465

VALUE
rb_ary_push(ary, item)
VALUE ary;

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

Comparison—Returns an integer (-1, 0, or +1) if this array is less than, equal to, or greater than other_array. Each object in each array is compared (using <=>). If any value isn’t equal, then that inequality is the return value. If all the values found are equal, then the return is based on a comparison of the array lengths. Thus, two arrays are “equal” according to Array#<=> if and only if they have the same length and the value of each element is equal to the value of the corresponding element in the other array.

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

Returns:

  • (-1, 0, +1) 


2797
2798
2799
 
# File 'array.c', line 2797

VALUE
rb_ary_cmp(ary1, ary2)
VALUE ary1, ary2;

#==(other_array) ⇒ 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 the other array.

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

Returns:

  • (Boolean) 


2638
2639
2640
 
# File 'array.c', line 2638

static VALUE
rb_ary_equal(ary1, ary2)
VALUE ary1, ary2;

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

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

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

Overloads:



763
764
765
 
# File 'array.c', line 763

VALUE
rb_ary_aref(argc, argv, ary)
int argc;

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

Element Assignment—Sets the element at index, or replaces a subarray starting at start and continuing for length elements, or replaces a subarray specified by range. If indices are greater than the current capacity of the array, the array grows automatically. A negative indices will count backward from the end of the array. Inserts elements if length is zero. If nil is used in the second and third form, deletes elements from self. An IndexError is raised if a negative index points past the beginning of the array. See also Array#push, and Array#unshift.

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

Overloads:



1156
1157
1158
 
# File 'array.c', line 1156

static VALUE
rb_ary_aset(argc, argv, ary)
int argc;

#assoc(obj) ⇒ Array?

Searches through an array whose elements are also arrays comparing obj with the first element of each contained array using obj.==. Returns the first contained array that matches (that is, the first associated array), or nil if no match is found. See also Array#rassoc.

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

Returns:



2561
2562
2563
 
# File 'array.c', line 2561

VALUE
rb_ary_assoc(ary, key)
VALUE ary, key;

#at(index) ⇒ Object?

Returns the element at index. A negative index counts from the end of self. Returns nil if the index is out of range. See also Array#[]. (Array#at is slightly faster than Array#[], as it does not accept ranges and so on.)

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

Returns:



821
822
823
 
# File 'array.c', line 821

static VALUE
rb_ary_at(ary, pos)
VALUE ary, pos;

#choice ⇒ Object

Choose a random element from an array.

Returns:



3300
3301
3302
 
# File 'array.c', line 3300

static VALUE
rb_ary_choice(ary)
VALUE ary;

#clear ⇒ Array

Removes all elements from self.

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

Returns:



2336
2337
2338
 
# File 'array.c', line 2336

VALUE
rb_ary_clear(ary)
VALUE ary;

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

Invokes block once for each element of self. Creates a new array containing the values returned by the block. See also Enumerable#collect.

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

Overloads:

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

    Yields:

    • (item)

    Returns:

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

    Yields:

    • (item)

    Returns:



1818
1819
1820
 
# File 'array.c', line 1818

static VALUE
rb_ary_collect(ary)
VALUE ary;

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

Invokes the block once for each element of self, replacing the element with the value returned by block. See also Enumerable#collect.

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

Overloads:

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

    Yields:

    • (item)

    Returns:

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

    Yields:

    • (item)

    Returns:



1850
1851
1852
 
# File 'array.c', line 1850

static VALUE
rb_ary_collect_bang(ary)
VALUE ary;

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

When invoked with a block, yields all combinations of length n of elements from ary and then returns ary itself. The implementation makes no guarantees about the order in which the combinations are yielded.

When invoked without a block, returns an enumerator object instead.

Examples:

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

Overloads:

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

    Yields:

    • (c)

    Returns:



3515
3516
3517
 
# File 'array.c', line 3515

static VALUE
rb_ary_combination(ary, num)
VALUE ary;

#compact ⇒ Array

Returns a copy of self with all nil elements removed.

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

Returns:



3033
3034
3035
 
# File 'array.c', line 3033

static VALUE
rb_ary_compact(ary)
VALUE ary;

#compact! ⇒ Array?

Removes nil elements from array. Returns nil if no changes were made.

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

Returns:



3000
3001
3002
 
# File 'array.c', line 3000

static VALUE
rb_ary_compact_bang(ary)
VALUE ary;

#concat(other_array) ⇒ Array

Appends the elements in other_array to self.

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

Returns:



2481
2482
2483
 
# File 'array.c', line 2481

VALUE
rb_ary_concat(x, y)
VALUE x, y;

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

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

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

Overloads:



3083
3084
3085
 
# File 'array.c', line 3083

static VALUE
rb_ary_count(argc, argv, ary)
int argc;

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

Calls block for each element repeatedly n times or forever if none or nil is given. If a non-positive number is given or the array is empty, does nothing. Returns nil if the loop has finished without getting interrupted.

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

Overloads:

  • #cycle {|obj| ... } ⇒ Object

    Yields:

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

    Yields:

    • (obj) 


3329
3330
3331
 
# File 'array.c', line 3329

static VALUE
rb_ary_cycle(argc, argv, ary)
int argc;

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

Deletes items from self that are equal to obj. If the item is not found, returns nil. If the optional code block is given, returns the result of block if the item is not found.

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

Overloads:



1968
1969
1970
 
# File 'array.c', line 1968

VALUE
rb_ary_delete(ary, item)
VALUE ary;

#delete_at(index) ⇒ Object?

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

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

Returns:



2042
2043
2044
 
# File 'array.c', line 2042

static VALUE
rb_ary_delete_at_m(ary, pos)
VALUE ary, pos;

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

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

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

Yields:

  • (item)

Returns:



2184
2185
2186
 
# File 'array.c', line 2184

static VALUE
rb_ary_delete_if(ary)
VALUE ary;

#drop(n) ⇒ Array

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

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

Returns:



3702
3703
3704
 
# File 'array.c', line 3702

static VALUE
rb_ary_drop(ary, n)
VALUE ary;

#drop_while {|arr| ... } ⇒ Array

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.

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

Yields:

  • (arr)

Returns:



3731
3732
3733
 
# File 'array.c', line 3731

static VALUE
rb_ary_drop_while(ary)
VALUE ary;

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

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

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

produces:

a -- b -- c --

Yields:

  • (item)

Returns:



1246
1247
1248
 
# File 'array.c', line 1246

VALUE
rb_ary_each(ary)
VALUE ary;

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

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

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

produces:

0 -- 1 -- 2 --

Yields:

Returns:



1274
1275
1276
 
# File 'array.c', line 1274

static VALUE
rb_ary_each_index(ary)
VALUE ary;

#empty? ⇒ Boolean

Returns true if self array contains no elements.

[].empty?   #=> true

Returns:

  • (Boolean) 


1344
1345
1346
 
# File 'array.c', line 1344

static VALUE
rb_ary_empty_p(ary)
VALUE ary;

#eql?(other) ⇒ Boolean

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

Returns:

  • (Boolean) 


2677
2678
2679
 
# File 'array.c', line 2677

static VALUE
rb_ary_eql(ary1, ary2)
VALUE ary1, ary2;

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

Tries to return the element at position index. If the index lies outside the array, the first form throws an IndexError exception, the second form returns default, and the third form returns the value of invoking the block, passing in the index. Negative values of index count from the end of the array.

a = [ 11, 22, 33, 44 ]
a.fetch(1)               #=> 22
a.fetch(-1)              #=> 44
a.fetch(4, 'cat')        #=> "cat"
a.fetch(4) { |i| i*i }   #=> 16

Overloads:



904
905
906
 
# File 'array.c', line 904

static VALUE
rb_ary_fetch(argc, argv, ary)
int argc;

#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 self.length. The last three forms fill the array with the value of the block. The block is passed the absolute index of each element to be filled.

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

Overloads:



2373
2374
2375
 
# File 'array.c', line 2373

static VALUE
rb_ary_fill(argc, argv, ary)
int argc;

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

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

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

This is an alias of #find_index.

Overloads:



952
953
954
 
# File 'array.c', line 952

static VALUE
rb_ary_index(argc, argv, ary)
int argc;

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

Returns the first element, or the first n elements, of the array. If the array is empty, the first form returns nil, and the second form returns an empty array.

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

Overloads:



843
844
845
 
# File 'array.c', line 843

static VALUE
rb_ary_first(argc, argv, ary)
int argc;

#flatten ⇒ Array #flatten(level) ⇒ Array

Returns a new array that is a one-dimensional flattening of this array (recursively). That is, for every element that is an array, extract its elements into the new array. If the optional level argument determines the level of recursion to flatten.

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

Overloads:



3229
3230
3231
 
# File 'array.c', line 3229

static VALUE
rb_ary_flatten(argc, argv, ary)
int argc;

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

Flattens self in place. Returns nil if no modifications were made (i.e., array contains no subarrays.) If the optional level argument determines the level of recursion to flatten.

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

Overloads:



3191
3192
3193
 
# File 'array.c', line 3191

static VALUE
rb_ary_flatten_bang(argc, argv, ary)
int argc;

#frozen? ⇒ Boolean

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

Returns:

  • (Boolean) 


89
90
91
 
# File 'array.c', line 89

static VALUE
rb_ary_frozen_p(ary)
VALUE ary;

#hash ⇒ Fixnum

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

Returns:



2718
2719
2720
 
# File 'array.c', line 2718

static VALUE
rb_ary_hash(ary)
VALUE ary;

#include?(obj) ⇒ Boolean

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

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

Returns:

  • (Boolean) 


2738
2739
2740
 
# File 'array.c', line 2738

VALUE
rb_ary_includes(ary, item)
VALUE ary;

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

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

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

This is an alias of #find_index.

Overloads:



952
953
954
 
# File 'array.c', line 952

static VALUE
rb_ary_index(argc, argv, ary)
int argc;

#indexes(i1, i2, ...iN) ⇒ Array #indices(i1, i2, ...iN) ⇒ Array

Deprecated; use Array#values_at.

Overloads:

  • #indexes(i1, i2, ...iN) ⇒ Array

    Returns:

  • #indices(i1, i2, ...iN) ⇒ Array

    Returns:



1032
1033
1034
 
# File 'array.c', line 1032

static VALUE
rb_ary_indexes(argc, argv, ary)
int argc;

#indexes(i1, i2, ...iN) ⇒ Array #indices(i1, i2, ...iN) ⇒ Array

Deprecated; use Array#values_at.

Overloads:

  • #indexes(i1, i2, ...iN) ⇒ Array

    Returns:

  • #indices(i1, i2, ...iN) ⇒ Array

    Returns:



1032
1033
1034
 
# File 'array.c', line 1032

static VALUE
rb_ary_indexes(argc, argv, ary)
int argc;

#replace(other_array) ⇒ Array

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

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

Returns:



2306
2307
2308
 
# File 'array.c', line 2306

static VALUE
rb_ary_replace(copy, orig)
VALUE copy, orig;

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

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

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

Returns:



1208
1209
1210
 
# File 'array.c', line 1208

static VALUE
rb_ary_insert(argc, argv, ary)
int argc;

#inspect ⇒ String

Create a printable version of array.

Returns:



1578
1579
1580
 
# File 'array.c', line 1578

static VALUE
rb_ary_inspect(ary)
VALUE ary;

#join(sep = $,) ⇒ String

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

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

Returns:



1436
1437
1438
 
# File 'array.c', line 1436

static VALUE
rb_ary_join_m(argc, argv, ary)
int argc;

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

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

[ "w", "x", "y", "z" ].last   #=> "z"

Overloads:



869
870
871
 
# File 'array.c', line 869

static VALUE
rb_ary_last(argc, argv, ary)
int argc;

#length ⇒ Integer Also known as: size

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

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

Returns:



1328
1329
1330
 
# File 'array.c', line 1328

static VALUE
rb_ary_length(ary)
VALUE ary;

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

Invokes block once for each element of self. Creates a new array containing the values returned by the block. See also Enumerable#collect.

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

Overloads:

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

    Yields:

    • (item)

    Returns:

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

    Yields:

    • (item)

    Returns:



1818
1819
1820
 
# File 'array.c', line 1818

static VALUE
rb_ary_collect(ary)
VALUE ary;

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

Invokes the block once for each element of self, replacing the element with the value returned by block. See also Enumerable#collect.

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

Overloads:

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

    Yields:

    • (item)

    Returns:

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

    Yields:

    • (item)

    Returns:



1850
1851
1852
 
# File 'array.c', line 1850

static VALUE
rb_ary_collect_bang(ary)
VALUE ary;

#nitems ⇒ Integer

Returns the number of non-nil elements in self.

May be zero.

[ 1, nil, 3, nil, 5 ].nitems   #=> 3

Returns:



3053
3054
3055
 
# File 'array.c', line 3053

static VALUE
rb_ary_nitems(ary)
VALUE ary;

#pack ⇒ Object

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

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

Directives for pack.

Directive    Meaning
---------------------------------------------------------------
    @     |  Moves to absolute position
    A     |  ASCII string (space padded, count is width)
    a     |  ASCII string (null padded, count is width)
    B     |  Bit string (descending bit order)
    b     |  Bit string (ascending bit order)
    C     |  Unsigned char
    c     |  Char
    D, d  |  Double-precision float, native format
    E     |  Double-precision float, little-endian byte order
    e     |  Single-precision float, little-endian byte order
    F, f  |  Single-precision float, native format
    G     |  Double-precision float, network (big-endian) byte order
    g     |  Single-precision float, network (big-endian) byte order
    H     |  Hex string (high nibble first)
    h     |  Hex string (low nibble first)
    I     |  Unsigned integer
    i     |  Integer
    L     |  Unsigned long
    l     |  Long
    M     |  Quoted printable, MIME encoding (see RFC2045)
    m     |  Base64 encoded string
    N     |  Long, network (big-endian) byte order
    n     |  Short, network (big-endian) byte-order
    P     |  Pointer to a structure (fixed-length string)
    p     |  Pointer to a null-terminated string
    Q, q  |  64-bit number
    S     |  Unsigned short
    s     |  Short
    U     |  UTF-8
    u     |  UU-encoded string
    V     |  Long, little-endian byte order
    v     |  Short, little-endian byte order
    w     |  BER-compressed integer\fnm
    X     |  Back up a byte
    x     |  Null byte
    Z     |  Same as ``a'', except that null is added with *



440
441
442
 
# File 'pack.c', line 440

static VALUE
pack_pack(ary, fmt)
VALUE ary, fmt;

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

When invoked with a block, yield all permutations of length n of the elements of ary, then return the array itself. If n is not specified, yield all permutations of all elements. The implementation makes no guarantees about the order in which the permutations are yielded.

When invoked without a block, return an enumerator object instead.

Examples:

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

Overloads:

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

    Yields:

    • (p)

    Returns:

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

    Yields:

    • (p)

    Returns:



3429
3430
3431
 
# File 'array.c', line 3429

static VALUE
rb_ary_permutation(argc, argv, ary)
int argc;

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

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

If a number n is given, returns an array of the last n elements (or less) just like array.slice!(-n, n) does.

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

Overloads:



531
532
533
 
# File 'array.c', line 531

static VALUE
rb_ary_pop_m(argc, argv, ary)
int argc;

#product(other_ary, ...) ⇒ Object

Returns an array of all combinations of elements from all arrays. The length of the returned array is the product of the length of ary and the argument arrays

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



3577
3578
3579
 
# File 'array.c', line 3577

static VALUE
rb_ary_product(argc, argv, ary)
int argc;

#push(obj, ...) ⇒ Array

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

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

Returns:



487
488
489
 
# File 'array.c', line 487

static VALUE
rb_ary_push_m(argc, argv, ary)
int argc;

#rassoc(key) ⇒ Array?

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

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

Returns:



2591
2592
2593
 
# File 'array.c', line 2591

VALUE
rb_ary_rassoc(ary, value)
VALUE ary, value;

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

Returns a new array containing the items in self for which the block is not true.

Yields:

  • (item)

Returns:



2163
2164
2165
 
# File 'array.c', line 2163

static VALUE
rb_ary_reject(ary)
VALUE ary;

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

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

Yields:

  • (item)

Returns:



2132
2133
2134
 
# File 'array.c', line 2132

static VALUE
rb_ary_reject_bang(ary)
VALUE ary;

#replace(other_array) ⇒ Array

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

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

Returns:



2306
2307
2308
 
# File 'array.c', line 2306

static VALUE
rb_ary_replace(copy, orig)
VALUE copy, orig;

#reverse ⇒ Array

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

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

Returns:



1670
1671
1672
 
# File 'array.c', line 1670

static VALUE
rb_ary_reverse_m(ary)
VALUE ary;

#reverse! ⇒ Array

Reverses self in place.

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

Returns:



1653
1654
1655
 
# File 'array.c', line 1653

static VALUE
rb_ary_reverse_bang(ary)
VALUE ary;

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

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

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

produces:

c b a

Yields:

  • (item) 


1302
1303
1304
 
# File 'array.c', line 1302

static VALUE
rb_ary_reverse_each(ary)
VALUE ary;

#rindex(obj) ⇒ Integer?

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

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

Returns:



993
994
995
 
# File 'array.c', line 993

static VALUE
rb_ary_rindex(argc, argv, ary)
int argc;

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

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

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

Yields:

  • (item)

Returns:



1934
1935
1936
 
# File 'array.c', line 1934

static VALUE
rb_ary_select(ary)
VALUE ary;

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

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

If a number n is given, returns an array of the first n elements (or less) just like array.slice!(0, n) does.

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

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

Overloads:



594
595
596
 
# File 'array.c', line 594

static VALUE
rb_ary_shift_m(argc, argv, ary)
int argc;

#shuffle ⇒ Array

Returns a new array with elements of this array shuffled.

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

Returns:



3283
3284
3285
3286
3287
3288
3289
 
# File 'array.c', line 3283

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

#shuffle! ⇒ Array?

Shuffles elements in self in place.

Returns:



3256
3257
3258
 
# File 'array.c', line 3256

static VALUE
rb_ary_shuffle_bang(ary)
VALUE ary;

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

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

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

Overloads:



763
764
765
 
# File 'array.c', line 763

VALUE
rb_ary_aref(argc, argv, ary)
int argc;

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

Deletes the element(s) given by an index (optionally with a length) or by a range. Returns the deleted object, subarray, or nil if the index is out of range. Equivalent to:

def slice!(*args)
  result = self[*args]
  self[*args] = nil
  result
end

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

Overloads:

  • #slice!(index) ⇒ Object?

    Returns:

  • #slice!(start, length) ⇒ nil

    Returns:

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

    Returns:

    • (nil) 


2074
2075
2076
 
# File 'array.c', line 2074

static VALUE
rb_ary_slice_bang(argc, argv, ary)
int argc;

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

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

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

Overloads:



1795
1796
1797
 
# File 'array.c', line 1795

VALUE
rb_ary_sort(ary)
VALUE ary;

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

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

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

Overloads:



1767
1768
1769
 
# File 'array.c', line 1767

VALUE
rb_ary_sort_bang(ary)
VALUE ary;

#take(n) ⇒ Array

Returns first n elements from ary.

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

Returns:



3652
3653
3654
 
# File 'array.c', line 3652

static VALUE
rb_ary_take(obj, n)
VALUE obj;

#take_while {|arr| ... } ⇒ Array

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

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

Yields:

  • (arr)

Returns:



3677
3678
3679
 
# File 'array.c', line 3677

static VALUE
rb_ary_take_while(ary)
VALUE ary;

#to_a ⇒ Array

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

Returns:



1595
1596
1597
 
# File 'array.c', line 1595

static VALUE
rb_ary_to_a(ary)
VALUE ary;

#to_ary ⇒ Array

Returns self.

Returns:



1614
1615
1616
 
# File 'array.c', line 1614

static VALUE
rb_ary_to_ary_m(ary)
VALUE ary;

#to_s ⇒ String

Returns self.join.

[ "a", "e", "i", "o" ].to_s   #=> "aeio"

Returns:



1460
1461
1462
 
# File 'array.c', line 1460

VALUE
rb_ary_to_s(ary)
VALUE ary;

#transpose ⇒ Array

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

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

Returns:



2265
2266
2267
 
# File 'array.c', line 2265

static VALUE
rb_ary_transpose(ary)
VALUE ary;

#uniq ⇒ Array

Returns a new array by removing duplicate values in self.

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

Returns:



2980
2981
2982
 
# File 'array.c', line 2980

static VALUE
rb_ary_uniq(ary)
VALUE ary;

#uniq! ⇒ Array?

Removes duplicate elements from self. Returns nil if no changes are made (that is, no duplicates are found).

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

Returns:



2947
2948
2949
 
# File 'array.c', line 2947

static VALUE
rb_ary_uniq_bang(ary)
VALUE ary;

#unshift(obj, ...) ⇒ Array

Prepends objects to the front of array. other elements up one.

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

Returns:



657
658
659
 
# File 'array.c', line 657

static VALUE
rb_ary_unshift_m(argc, argv, ary)
int argc;

#values_at(selector, ...) ⇒ Array

Returns an array containing the elements in self corresponding to the given selector(s). The selectors may be either integer indices or ranges. See also Array#select.

a = %w{ a b c d e f }
a.values_at(1, 3, 5)
a.values_at(1, 3, 5, 7)
a.values_at(-1, -3, -5, -7)
a.values_at(1..3, 2...5)

Returns:



1913
1914
1915
 
# File 'array.c', line 1913

static VALUE
rb_ary_values_at(argc, argv, ary)
int argc;

#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 self.size n-element arrays, where n is one more that the count of arguments. If the size of any argument is less than enumObj.size, nil values are supplied. If a block given, it is invoked for each output array, otherwise an array of arrays is returned.

a = [ 4, 5, 6 ]
b = [ 7, 8, 9 ]

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

Overloads:

  • #zip(arg, ...) ⇒ Array

    Returns:

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

    Yields:

    • (arr)

    Returns:

    • (nil) 


2215
2216
2217
 
# File 'array.c', line 2215

static VALUE
rb_ary_zip(argc, argv, ary)
int argc;

#|(other_array) ⇒ Array

Set Union—Returns a new array by joining this array with other_array, removing duplicates.

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

Returns:



2906
2907
2908
 
# File 'array.c', line 2906

static VALUE
rb_ary_or(ary1, ary2)
VALUE ary1, ary2;