Class: Array
Relationships & Source Files | |
Super Chains via Extension / Inclusion / Inheritance | |
Instance Chain:
self,
::Enumerable
|
|
Inherits: | Object |
Defined in: | array.c, array.rb, pack.rb |
Overview
An Array is an ordered, integer-indexed collection of objects, called elements. Any object (even another array) may be an array element, and an array can contain objects of different types.
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 and only 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 and only 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.
Although the effective index into an array is always an integer, some methods (both within and outside of class Array) accept one or more non-integer arguments that are integer-convertible objects
.
Creating Arrays
You can create an Array object explicitly with:
-
An
array literal
:[1, 'one', :one, [2, 'two', :two]]
-
A
%w or %W: string-array Literal
:%w[foo bar baz] # => ["foo", "bar", "baz"] %w[1 % *] # => ["1", "%", "*"]
-
A
%i pr %I: symbol-array Literal
:%i[foo bar baz] # => [:foo, :bar, :baz] %i[1 % *] # => [:"1", :%, :*]
-
Method Kernel.Array:
Array(["a", "b"]) # => ["a", "b"] Array(1..5) # => [1, 2, 3, 4, 5] Array(key: :value) # => [[:key, :value]] Array(nil) # => [] Array(1) # => [1] Array({:a => "a", :b => "b"}) # => [[:a, "a"], [:b, "b"]]
-
Method .new:
Array.new # => [] Array.new(3) # => [nil, nil, nil] Array.new(4) {Hash.new} # => [{}, {}, {}, {}] Array.new(3, true) # => [true, true, true]
Note that the last example above populates the array with references to the same object. This is recommended only in cases where that object is a natively immutable object such as a symbol, a numeric,
nil
,true
, orfalse
.Another way to create an array with various objects, using a block; this usage is safe for mutable objects such as hashes, strings or other arrays:
Array.new(4) {|i| i.to_s } # => ["0", "1", "2", "3"]
Here is a way to create a multi-dimensional array:
Array.new(3) {Array.new(3)} # => [[nil, nil, nil], [nil, nil, nil], [nil, nil, nil]]
A number of Ruby methods, both in the core and in the standard library, provide instance method #to_a, which converts an object to an array.
-
OptionParser#to_a
-
Set#to_a
-
Benchmark::Tms#to_a
-
CSV::Table#to_a
-
Gem::List#to_a
-
Gem::NameTuple#to_a
-
Gem::Platform#to_a
-
Gem::RequestSet::Lockfile::Tokenizer#to_a
-
Gem::SourceList#to_a
-
OpenSSL::X509::Extension#to_a
-
OpenSSL::X509::Name#to_a
-
Racc::ISet#to_a
-
Rinda::RingFinger#to_a
-
Ripper::Lexer::Elem#to_a
-
YAML::DBM#to_a
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]
What’s Here
First, what’s elsewhere. Class Array:
-
Inherits from
class Object
. -
Includes
module Enumerable
, which provides dozens of additional methods.
Here, class Array provides methods that are useful for:
-
{Array@Methods+for+Creating+an+Array Creating an }
-
Querying
-
Comparing
-
Fetching
-
Assigning
-
Deleting
-
Combining
-
Iterating
-
Converting
-
And more.…
Methods for Creating an Array
-
.[]: Returns a new array populated with given objects.
-
.new: Returns a new array.
-
.try_convert: Returns a new array created from a given object.
Methods for Querying
-
#empty?: Returns whether there are no elements.
-
#all?: Returns whether all elements meet a given criterion.
-
#any?: Returns whether any element meets a given criterion.
-
#one?: Returns whether exactly one element #== a given object.
-
#count: Returns the count of elements that meet a given criterion.
-
#find_index, #index: Returns the index of the first element that meets a given criterion.
-
#rindex: Returns the index of the last element that meets a given criterion.
-
#hash: Returns the integer hash code.
Methods for Comparing
-
#<=>: Returns -1, 0, or 1 * as
self
is less than, equal to, or greater than a given object. -
#==: Returns whether each element in
self
is #== to the corresponding element in a given object. -
#eql?: Returns whether each element in
self
is #eql? to the corresponding element in a given object.
Methods for Fetching
These methods do not modify self
.
-
#[]: Returns one or more elements.
-
#fetch: Returns the element at a given offset.
-
#first: Returns one or more leading elements.
-
#last: Returns one or more trailing elements.
-
#max: Returns one or more maximum-valued elements, as determined by #<=> or a given block.
-
#min: Returns one or more minimum-valued elements, as determined by #<=> or a given block.
-
#minmax: Returns the minimum-valued and maximum-valued elements, as determined by #<=> or a given block.
-
#assoc: Returns the first element that is an array whose first element #== a given object.
-
#rassoc: Returns the first element that is an array whose second element #== a given object.
-
#at: Returns the element at a given offset.
-
#values_at: Returns the elements at given offsets.
-
#dig: Returns the object in nested objects that is specified by a given index and additional arguments.
-
#drop: Returns trailing elements as determined by a given index.
-
#take: Returns leading elements as determined by a given index.
-
#drop_while: Returns trailing elements as determined by a given block.
-
#take_while: Returns leading elements as determined by a given block.
-
#slice: Returns consecutive elements as determined by a given argument.
-
#sort: Returns all elements in an order determined by #<=> or a given block.
-
#reverse: Returns all elements in reverse order.
-
#compact: Returns an array containing all non-
nil
elements. -
#select, #filter: Returns an array containing elements selected by a given block.
-
#uniq: Returns an array containing non-duplicate elements.
-
#rotate: Returns all elements with some rotated from one end to the other.
-
#bsearch: Returns an element selected via a binary search as determined by a given block.
-
#bsearch_index: Returns the index of an element selected via a binary search as determined by a given block.
-
#sample: Returns one or more random elements.
-
#shuffle: Returns elements in a random order.
Methods for Assigning
These methods add, replace, or reorder elements in self
.
-
#[]=: Assigns specified elements with a given object.
-
#insert: Inserts given objects at a given offset; does not replace elements.
-
#concat: Appends all elements from given arrays.
-
#fill: Replaces specified elements with specified objects.
-
#replace: Replaces the content of
self
with the content of a given array. -
#reverse!: Replaces
self
with its elements reversed. -
#rotate!: Replaces
self
with its elements rotated. -
#shuffle!: Replaces
self
with its elements in random order. -
#sort!: Replaces
self
with its elements sorted, as determined by #<=> or a given block. -
#sort_by!: Replaces
self
with its elements sorted, as determined by a given block.
Methods for Deleting
Each of these methods removes elements from self
:
-
#pop: Removes and returns the last element.
-
#shift: Removes and returns the first element.
-
#compact!: Removes all
nil
elements. -
#delete: Removes elements equal to a given object.
-
#delete_at: Removes the element at a given offset.
-
#delete_if: Removes elements specified by a given block.
-
#keep_if: Removes elements not specified by a given block.
-
#reject!: Removes elements specified by a given block.
-
#select!, #filter!: Removes elements not specified by a given block.
-
#slice!: Removes and returns a sequence of elements.
-
#uniq!: Removes duplicates.
Methods for Combining
-
#&: Returns an array containing elements found both in
self
and a given array. -
#intersection: Returns an array containing elements found both in
self
and in each given array. -
#+: Returns an array containing all elements of
self
followed by all elements of a given array. -
#-: Returns an array containing all elements of
self
that are not found in a given array. -
#|: Returns an array containing all elements of
self
and all elements of a given array, duplicates removed. -
#union: Returns an array containing all elements of
self
and all elements of given arrays, duplicates removed. -
#difference: Returns an array containing all elements of
self
that are not found in any of the given arrays.. -
#product: Returns or yields all combinations of elements from
self
and given arrays.
Methods for Iterating
-
#each: Passes each element to a given block.
-
#reverse_each: Passes each element, in reverse order, to a given block.
-
#each_index: Passes each element index to a given block.
-
#cycle: Calls a given block with each element, then does so again, for a specified number of times, or forever.
-
#combination: Calls a given block with combinations of elements of
self
; a combination does not use the same element more than once. -
#permutation: Calls a given block with permutations of elements of
self
; a permutation does not use the same element more than once. -
#repeated_combination: Calls a given block with combinations of elements of
self
; a combination may use the same element more than once. -
#repeated_permutation: Calls a given block with permutations of elements of
self
; a permutation may use the same element more than once.
Methods for Converting
-
#map, #collect: Returns an array containing the block return-value for each element.
-
#map!, #collect!: Replaces each element with a block return-value.
-
#flatten: Returns an array that is a recursive flattening of
self
. -
#flatten!: Replaces each nested array in
self
with the elements from that array. -
#inspect, #to_s: Returns a new
::String
containing the elements. -
#join: Returns a newsString containing the elements joined by the field separator.
-
#to_a: Returns
self
or a new array containing all elements. -
#to_ary: Returns
self
. -
#to_h: Returns a new hash formed from the elements.
-
#transpose: Transposes
self
, which must be an array of arrays. -
#zip: Returns a new array of arrays containing
self
and given arrays; follow the link for details.
Other Methods
-
#*: Returns one of the following:
-
With integer argument
n
, a new array that is the concatenation ofn
copies ofself
. -
With string argument
field_separator
, a new string that is equivalent tojoin(field_separator)
.
-
-
#abbrev
: Returns a hash of unambiguous abbreviations for elements. -
#pack: Packs the elements into a binary sequence.
-
#sum: Returns a sum of elements according to either
+
or a given block.
Class Method Summary
-
.[](*args)
Returns a new array populated with the given objects.
-
.try_convert(object) ⇒ Object, ...
If
object
is an Array object, returnsobject
. - .new(*args) constructor Internal use only
Instance Attribute Summary
-
#empty? ⇒ Boolean
readonly
Returns
true
if the count of elements inself
is zero,false
otherwise.
Instance Method Summary
- #&(other_array) ⇒ Array
-
#*(n) ⇒ Array
When non-negative argument
::Integer
n
is given, returns a new Array built by concatenating then
copies ofself
: -
#+(other_array) ⇒ Array
Returns a new Array containing all elements of
array
followed by all elements ofother_array
: -
#-(other_array) ⇒ Array
Returns a new Array containing only those elements from
array
that are not found in Arrayother_array
; items are compared using #eql?; the order fromarray
is preserved: -
#<<(object) ⇒ self
Appends
object
toself
; returnsself
: -
#<=>(other_array) ⇒ 1, 0
Returns -1, 0, or 1 as
self
is less than, equal to, or greater thanother_array
. -
#==(other_array) ⇒ Boolean
Returns
true
if botharray.size == other_array.size
and for each indexi
inarray
,array[i] == other_array[i]
: -
#[](index) ⇒ Object?
(also: #slice)
Returns elements from
self
; does not modifyself
. -
#[]=(index, object) ⇒ Object
Assigns elements in
self
; returns the givenobject
. -
#all? ⇒ Boolean
Returns
true
if all elements ofself
meet a given criterion. -
#any? ⇒ Boolean
Returns
true
if any element ofself
meets a given criterion. -
#append(*objects) ⇒ self
Alias for #push.
-
#assoc(obj) ⇒ Array?
Returns the first element in
self
that is an Array whose first element #==obj
: - #at(index) ⇒ Object
-
#bsearch {|element| ... } ⇒ Object
Returns an element from
self
selected by a binary search. -
#bsearch_index {|element| ... } ⇒ Integer?
Searches
self
as described at method #bsearch, but returns the index of the found element instead of the element itself. -
#clear ⇒ self
Removes all elements from
self
: -
#map {|element| ... } ⇒ Array
Alias for #map.
-
#map! {|element| ... } ⇒ self
Alias for #map!.
-
#combination(n) {|element| ... } ⇒ self
Calls the block, if given, with combinations of elements of
self
; returnsself
. -
#compact ⇒ Array
Returns a new Array containing all non-
nil
elements fromself
: -
#compact! ⇒ self?
Removes all
nil
elements fromself
. -
#concat(*other_arrays) ⇒ self
Adds to
array
all elements from each Array inother_arrays
; returnsself
: -
#count ⇒ Integer
Returns a count of specified elements.
- #cycle {|element| ... } ⇒ nil
-
#delete(obj) ⇒ deleted_object
Removes zero or more elements from
self
. - #delete_at(index) ⇒ deleted_object?
-
#delete_if {|element| ... } ⇒ self
Removes each element in
self
for which the block returns a truthy value; returnsself
: -
#difference(*other_arrays) ⇒ Array
Returns a new Array containing only those elements from
self
that are not found in any of the Arraysother_arrays
; items are compared using #eql?; order fromself
is preserved: -
#dig(index, *identifiers) ⇒ Object
Finds and returns the object in nested objects that is specified by #index and
identifiers
. -
#drop(n) ⇒ Array
Returns a new Array containing all but the first
n
element ofself
, wheren
is a non-negative Integer; does not modifyself
. -
#drop_while {|element| ... } ⇒ Array
Returns a new Array containing zero or more trailing elements of
self
; does not modifyself
. -
#each {|element| ... } ⇒ self
Iterates over array elements.
-
#each_index {|index| ... } ⇒ self
Iterates over array indexes.
-
#eql?(other_array) ⇒ Boolean
Returns
true
ifself
andother_array
are the same size, and if, for each indexi
inself
,self[i].eql? other_array[i]
: -
#fetch(index) ⇒ element
Returns the element at offset #index.
-
#fill(obj) ⇒ self
Replaces specified elements in
self
with specified objects; returnsself
. -
#select {|element| ... } ⇒ Array
(also: #select)
Calls the block, if given, with each element of
self
; returns a new Array containing those elements ofself
for which the block returns a truthy value: -
#select! {|element| ... } ⇒ self?
(also: #select!)
Calls the block, if given with each element of
self
; removes fromself
those elements for which the block returnsfalse
ornil
. -
#index(object) ⇒ Integer?
Alias for #index.
-
#first ⇒ Object?
Returns elements from
self
; does not modifyself
. -
#flatten ⇒ Array
Returns a new Array that is a recursive flattening of
self
: - Each non-Array element is unchanged. -
#flatten! ⇒ self?
Replaces each nested Array in
self
with the elements from that Array; returnsself
if any changes,nil
otherwise. -
#hash ⇒ Integer
Returns the integer hash value for
self
. -
#include?(obj) ⇒ Boolean
Returns
true
if for some indexi
inself
,obj == self[i]
; otherwisefalse
: -
#index(object) ⇒ Integer?
(also: #find_index)
Returns the index of a specified element.
-
#new ⇒ Array
constructor
Returns a new Array.
-
#initialize_copy(other_array) ⇒ self
Alias for #replace.
-
#insert(index, *objects) ⇒ self
Inserts given
objects
before or after the element at::Integer
indexoffset
; returnsself
. -
#inspect ⇒ String
Alias for #to_s.
-
#intersect?(other_ary) ⇒ Boolean
Returns
true
if the array andother_ary
have at least one element in common, otherwise returnsfalse
: - #intersection(*other_arrays) ⇒ Array
-
#join(->new_string)
Returns the new
::String
formed by joining the array elements after conversion. -
#keep_if {|element| ... } ⇒ self
Retains those elements for which the block returns a truthy value; deletes all other elements; returns
self
: -
#last ⇒ Object?
Returns elements from
self
;self
is not modified. -
#length ⇒ Integer
(also: #size)
Returns the count of elements in
self
. -
#map {|element| ... } ⇒ Array
(also: #collect)
Calls the block, if given, with each element of
self
; returns a new Array whose elements are the return values from the block: -
#map! {|element| ... } ⇒ self
(also: #collect!)
Calls the block, if given, with each element; replaces the element with the block’s return value:
-
#max ⇒ element
Returns one of the following:
-
#min ⇒ element
Returns one of the following:
-
#minmax ⇒ Array, max_val
Returns a new 2-element Array containing the minimum and maximum values from
self
, either per method #<=> or per a given block:. -
#none? ⇒ Boolean
Returns
true
if no element ofself
meet a given criterion. -
#one? ⇒ Boolean
Returns
true
if exactly one element ofself
meets a given criterion. -
#pack(template, buffer: nil) ⇒ String
Formats each element in
self
into a binary string; returns that string. -
#permutation {|element| ... } ⇒ self
When invoked with a block, yield all permutations of elements of
self
; returnsself
. -
#pop ⇒ Object?
Removes and returns trailing elements.
-
#prepend(*objects) ⇒ self
(also: #unshift)
Prepends the given
objects
toself
: -
#product(*other_arrays) ⇒ Array
Computes and returns or yields all combinations of elements from all the Arrays, including both
self
andother_arrays
: -
#push(*objects) ⇒ self
(also: #append)
Appends trailing elements.
-
#rassoc(obj) ⇒ Array?
Returns the first element in
self
that is an Array whose second element #==obj
: -
#reject {|element| ... } ⇒ Array
Returns a new Array whose elements are all those from
self
for which the block returnsfalse
ornil
: -
#reject! {|element| ... } ⇒ self?
Removes each element for which the block returns a truthy value.
-
#repeated_combination(n) {|combination| ... } ⇒ self
Calls the block with each repeated combination of length
n
of the elements ofself
; each combination is an Array; returnsself
. -
#repeated_permutation(n) {|permutation| ... } ⇒ self
Calls the block with each repeated permutation of length
n
of the elements ofself
; each permutation is an Array; returnsself
. -
#replace(other_array) ⇒ self
(also: #initialize_copy)
Replaces the content of
self
with the content ofother_array
; returnsself
: -
#reverse ⇒ Array
Returns a new Array with the elements of
self
in reverse order: -
#reverse! ⇒ self
Reverses
self
in place: -
#reverse_each {|element| ... } ⇒ self
Iterates backwards over array elements.
-
#rindex(object) ⇒ Integer?
Returns the index of the last element for which
object == element
. -
#rotate ⇒ Array
Returns a new Array formed from
self
with elements rotated from one end to the other. -
#rotate! ⇒ self
Rotates
self
in place by moving elements from one end to the other; returnsself
. -
#sample(random: Random) ⇒ Object
Returns random elements from
self
. -
#select {|element| ... } ⇒ Array
Alias for #filter.
-
#select! {|element| ... } ⇒ self?
Alias for #filter!.
-
#shift ⇒ Object?
Removes and returns leading elements.
-
#shuffle(random: Random) ⇒ Array
Returns a new array with elements of
self
shuffled. -
#shuffle!(random: Random) ⇒ Array
Shuffles the elements of
self
in place. -
#size ⇒ Integer
Alias for #length.
-
#slice(index) ⇒ Object?
Alias for #[].
-
#slice!(n) ⇒ Object?
Removes and returns elements from
self
. -
#sort ⇒ Array
Returns a new Array whose elements are those from
self
, sorted. -
#sort! ⇒ self
Returns
self
with its elements sorted in place. -
#sort_by! {|element| ... } ⇒ self
Sorts the elements of
self
in place, using an ordering determined by the block; returns self. -
#sum(init = 0) ⇒ Object
When no block is given, returns the object equivalent to:
-
#take(n) ⇒ Array
Returns a new Array containing the first
n
element ofself
, wheren
is a non-negative Integer; does not modifyself
. -
#take_while {|element| ... } ⇒ Array
Returns a new Array containing zero or more leading elements of
self
; does not modifyself
. -
#to_a ⇒ self, Array
When
self
is an instance of Array, returnsself
: -
#to_ary ⇒ self
Returns
self
. -
#to_h ⇒ Hash
Returns a new
::Hash
formed fromself
. - #to_s ⇒ String (also: #inspect)
-
#transpose ⇒ Array
Transposes the rows and columns in an Array of Arrays; the nested Arrays must all be the same size:
-
#union(*other_arrays) ⇒ Array
Returns a new Array that is the union of
self
and all given Arraysother_arrays
; duplicates are removed; order is preserved; items are compared using #eql?: -
#uniq ⇒ Array
Returns a new Array containing those elements from
self
that are not duplicates, the first occurrence always being retained. -
#uniq! ⇒ self?
Removes duplicate elements from
self
, the first occurrence always being retained; returnsself
if any elements removed,nil
otherwise. -
#unshift(*objects) ⇒ self
Alias for #prepend.
- #values_at(*indexes) ⇒ Array
-
#zip(*other_arrays) ⇒ Array
When no block given, returns a new Array
new_array
of sizeself.size
whose elements are Arrays. -
#|(other_array) ⇒ Array
Returns the union of
array
and Arrayother_array
; duplicates are removed; order is preserved; items are compared using #eql?: - #deconstruct Internal use only
::Enumerable
- Included
#all? | Returns whether every element meets a given criterion. |
#any? | Returns whether any element meets a given criterion. |
#chain | Returns an enumerator object generated from this enumerator and given enumerables. |
#chunk | Each element in the returned enumerator is a 2-element array consisting of: |
#chunk_while | Creates an enumerator for each chunked elements. |
#collect | Alias for Enumerable#map. |
#collect_concat | Alias for Enumerable#flat_map. |
#compact | Returns an array of all non- |
#count | Returns the count of elements, based on an argument or block criterion, if given. |
#cycle | When called with positive integer argument |
#detect | Alias for Enumerable#find. |
#drop | For positive integer |
#drop_while | Calls the block with successive elements as long as the block returns a truthy value; returns an array of all elements after that point: |
#each_cons | Calls the block with each successive overlapped |
#each_entry | Calls the given block with each element, converting multiple values from yield to an array; returns |
#each_slice | Calls the block with each successive disjoint |
#each_with_index | With a block given, calls the block with each element and its index; returns |
#each_with_object | Calls the block once for each element, passing both the element and the given object: |
#entries | Alias for Enumerable#to_a. |
#filter | Returns an array containing elements selected by the block. |
#filter_map | Returns an array containing truthy elements returned by the block. |
#find | Returns the first element for which the block returns a truthy value. |
#find_all | Alias for Enumerable#filter. |
#find_index | Returns the index of the first element that meets a specified criterion, or |
#first | Returns the first element or elements. |
#flat_map | Returns an array of flattened objects returned by the block. |
#grep | Returns an array of objects based elements of |
#grep_v | Returns an array of objects based on elements of |
#group_by | With a block given returns a hash: |
#include? | Alias for Enumerable#member?. |
#inject | Returns an object formed from operands via either: |
#lazy | Returns an |
#map | Returns an array of objects returned by the block. |
#max | Returns the element with the maximum element according to a given criterion. |
#max_by | Returns the elements for which the block returns the maximum values. |
#member? | Returns whether for any element |
#min | Returns the element with the minimum element according to a given criterion. |
#min_by | Returns the elements for which the block returns the minimum values. |
#minmax | Returns a 2-element array containing the minimum and maximum elements according to a given criterion. |
#minmax_by | Returns a 2-element array containing the elements for which the block returns minimum and maximum values: |
#none? | Returns whether no element meets a given criterion. |
#one? | Returns whether exactly one element meets a given criterion. |
#partition | With a block given, returns an array of two arrays: |
#reduce | Alias for Enumerable#inject. |
#reject | Returns an array of objects rejected by the block. |
#reverse_each | With a block given, calls the block with each element, but in reverse order; returns |
#select | Alias for Enumerable#filter. |
#slice_after | Creates an enumerator for each chunked elements. |
#slice_before | With argument |
#slice_when | Creates an enumerator for each chunked elements. |
#sort | Returns an array containing the sorted elements of |
#sort_by | With a block given, returns an array of elements of |
#sum | With no block given, returns the sum of |
#take | For non-negative integer |
#take_while | Calls the block with successive elements as long as the block returns a truthy value; returns an array of all elements up to that point: |
#tally | Returns a hash containing the counts of equal elements: |
#to_a | Returns an array containing the items in |
#to_h | When |
#to_set | Makes a set from the enumerable object with given arguments. |
#uniq | With no block, returns a new array containing only unique elements; the array has no two elements |
#zip | With no block given, returns a new array |
Constructor Details
.new(*args)
# File 'array.c', line 1013
static VALUE rb_ary_s_new(int argc, VALUE *argv, VALUE klass) { VALUE ary; if (klass == rb_cArray) { long size = 0; if (argc > 0 && FIXNUM_P(argv[0])) { size = FIX2LONG(argv[0]); if (size < 0) size = 0; } ary = ary_new(klass, size); rb_obj_call_init_kw(ary, argc, argv, RB_PASS_CALLED_KEYWORDS); } else { ary = rb_class_new_instance_pass_kw(argc, argv, klass); } return ary; }
#new ⇒ Array
#new(array) ⇒ Array
#new(size) ⇒ Array
#new(size, default_value) ⇒ Array
#new(size) {|index| ... } ⇒ Array
Array
#new(array) ⇒ Array
#new(size) ⇒ Array
#new(size, default_value) ⇒ Array
#new(size) {|index| ... } ⇒ Array
Returns a new Array.
With no block and no arguments, returns a new empty Array object.
With no block and a single Array argument array
, returns a new Array formed from array
:
a = Array.new([:foo, 'bar', 2])
a.class # => Array
a # => [:foo, "bar", 2]
With no block and a single ::Integer
argument #size, returns a new Array of the given size whose elements are all nil
:
a = Array.new(3)
a # => [nil, nil, nil]
With no block and arguments #size and default_value
, returns an Array of the given size; each element is that same default_value
:
a = Array.new(3, 'x')
a # => ['x', 'x', 'x']
With a block and argument #size, returns an Array of the given size; the block is called with each successive integer #index; the element for that #index is the return value from the block:
a = Array.new(3) {|index| "Element #{index}" }
a # => ["Element 0", "Element 1", "Element 2"]
Raises ArgumentError if #size is negative.
With a block and no argument, or a single argument 0
, ignores the block and returns a new empty Array.
# File 'array.c', line 1084
static VALUE rb_ary_initialize(int argc, VALUE *argv, VALUE ary) { long len; VALUE size, val; rb_ary_modify(ary); if (argc == 0) { rb_ary_reset(ary); assert(ARY_EMBED_P(ary)); assert(ARY_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/]
# File 'array.c', line 1146
static VALUE rb_ary_s_create(int argc, VALUE *argv, VALUE klass) { VALUE ary = ary_new(klass, argc); if (argc > 0 && argv) { ary_memcpy(ary, 0, argc, argv); ARY_SET_LEN(ary, argc); } return ary; }
.try_convert(object) ⇒ Object, ...
If object
is an Array object, returns object
.
Otherwise if object
responds to :to_ary
, calls object.to_ary
and returns the result.
Returns nil
if object
does not respond to :to_ary
Raises an exception unless object.to_ary
returns an Array object.
# File 'array.c', line 1006
static VALUE rb_ary_s_try_convert(VALUE dummy, VALUE ary) { return rb_check_array_type(ary); }
Instance Attribute Details
#empty? ⇒ Boolean
(readonly)
Returns true
if the count of elements in self
is zero, false
otherwise.
# File 'array.c', line 2685
static VALUE rb_ary_empty_p(VALUE ary) { return RBOOL(RARRAY_LEN(ary) == 0); }
Instance Method Details
#&(other_array) ⇒ Array
Returns a new Array containing each element found in both array
and Array other_array
; duplicates are omitted; items are compared using #eql? (items must also implement #hash correctly):
[0, 1, 2, 3] & [1, 2] # => [1, 2]
[0, 1, 0, 1] & [0, 1] # => [0, 1]
Preserves order from array
:
[0, 1, 2] & [3, 2, 1, 0] # => [0, 1, 2]
Related: #intersection.
# File 'array.c', line 5485
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); } } return ary3; }
#*(n) ⇒ Array
#*(string_separator) ⇒ String
Array
#*(string_separator) ⇒ String
When non-negative argument ::Integer
n
is given, returns a new Array built by concatenating the n
copies of self
:
a = ['x', 'y']
a * 3 # => ["x", "y", "x", "y", "x", "y"]
When String argument string_separator
is given, equivalent to array.join(string_separator)
:
[0, [0, 1], {foo: 0}] * ', ' # => "0, 0, 1, {:foo=>0}"
# File 'array.c', line 4962
static VALUE rb_ary_times(VALUE ary, VALUE times) { VALUE ary2, tmp; const VALUE *ptr; long t, len; tmp = rb_check_string_type(times); if (!NIL_P(tmp)) { return rb_ary_join(ary, tmp); } len = NUM2LONG(times); if (len == 0) { ary2 = ary_new(rb_cArray, 0); goto out; } if (len < 0) { rb_raise(rb_eArgError, "negative argument"); } if (ARY_MAX_SIZE/len < RARRAY_LEN(ary)) { rb_raise(rb_eArgError, "argument too big"); } len *= RARRAY_LEN(ary); ary2 = ary_new(rb_cArray, len); ARY_SET_LEN(ary2, len); ptr = RARRAY_CONST_PTR(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(ary2)); t *= 2; } if (t < len) { ary_memcpy(ary2, t, len-t, RARRAY_CONST_PTR(ary2)); } } out: return ary2; }
#+(other_array) ⇒ Array
Returns a new Array containing all elements of array
followed by all elements of other_array
:
a = [0, 1] + [2, 3]
a # => [0, 1, 2, 3]
Related: #concat.
# File 'array.c', line 4878
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(x)); ary_memcpy(z, xlen, ylen, RARRAY_CONST_PTR(y)); ARY_SET_LEN(z, len); return z; }
#-(other_array) ⇒ Array
Returns a new Array containing only those elements from array
that are not found in Array other_array
; items are compared using #eql?; the order from array
is preserved:
[0, 1, 1, 2, 1, 1, 3, 1, 1] - [1] # => [0, 2, 3]
[0, 1, 2, 3] - [3, 0] # => [1, 2]
[0, 1, 2] - [4] # => [0, 1, 2]
Related: #difference.
# File 'array.c', line 5383
VALUE rb_ary_diff(VALUE ary1, VALUE ary2) { VALUE ary3; VALUE hash; long i; ary2 = to_ary(ary2); if (RARRAY_LEN(ary2) == 0) { return ary_make_shared_copy(ary1); } 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)); } return ary3; }
#<<(object) ⇒ self
Appends object
to self
; returns self
:
a = [:foo, 'bar', 2]
a << :baz # => [:foo, "bar", 2, :baz]
Appends object
as one element, even if it is another Array:
a = [:foo, 'bar', 2]
a1 = a << [3, 4]
a1 # => [:foo, "bar", 2, [3, 4]]
# File 'array.c', line 1337
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(ary, ptr, { RB_OBJ_WRITE(target_ary, &ptr[idx], item); }); ARY_SET_LEN(ary, idx + 1); ary_verify(ary); return ary; }
#<=>(other_array) ⇒ 1
, 0
Returns -1, 0, or 1 as self
is less than, equal to, or greater than other_array
. For each index i
in self
, evaluates result = self[i] <=> other_array[i]
.
Returns -1 if any result is -1:
[0, 1, 2] <=> [0, 1, 3] # => -1
Returns 1 if any result is 1:
[0, 1, 2] <=> [0, 1, 1] # => 1
When all results are zero:
-
Returns -1 if
array
is smaller thanother_array
:[0, 1, 2] <=> [0, 1, 2, 3] # => -1
-
Returns 1 if
array
is larger thanother_array
:[0, 1, 2] <=> [0, 1] # => 1
-
Returns 0 if
array
andother_array
are the same size:[0, 1, 2] <=> [0, 1, 2] # => 0
# File 'array.c', line 5302
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 (!UNDEF_P(v)) return v; len = RARRAY_LEN(ary1) - RARRAY_LEN(ary2); if (len == 0) return INT2FIX(0); if (len > 0) return INT2FIX(1); return INT2FIX(-1); }
#==(other_array) ⇒ Boolean
Returns true
if both array.size == other_array.size
and for each index i
in array
, array[i] == other_array[i]
:
a0 = [:foo, 'bar', 2]
a1 = [:foo, 'bar', 2.0]
a1 == a0 # => true
[] == [] # => true
Otherwise, returns false
.
This method is different from method #eql?, which compares elements using Object#eql?.
# File 'array.c', line 5119
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(ary1) == RARRAY_CONST_PTR(ary2)) return Qtrue; return rb_exec_recursive_paired(recursive_equal, ary1, ary2, ary2); }
#[](index) ⇒ Object?
#[](start, length) ⇒ Object?
#[](range) ⇒ Object?
#[](aseq) ⇒ Object?
#slice(index) ⇒ Object?
#slice(start, length) ⇒ Object?
#slice(range) ⇒ Object?
#slice(aseq) ⇒ Object?
Also known as: #slice
Returns elements from self
; does not modify self
.
When a single ::Integer
argument #index is given, returns the element at offset #index:
a = [:foo, 'bar', 2]
a[0] # => :foo
a[2] # => 2
a # => [:foo, "bar", 2]
If #index is negative, counts relative to the end of self
:
a = [:foo, 'bar', 2]
a[-1] # => 2
a[-2] # => "bar"
If #index is out of range, returns nil
.
When two ::Integer
arguments start
and #length are given, returns a new Array of size #length containing successive elements beginning at offset start
:
a = [:foo, 'bar', 2]
a[0, 2] # => [:foo, "bar"]
a[1, 2] # => ["bar", 2]
If start + length
is greater than self.length
, returns all elements from offset start
to the end:
a = [:foo, 'bar', 2]
a[0, 4] # => [:foo, "bar", 2]
a[1, 3] # => ["bar", 2]
a[2, 2] # => [2]
If start == self.size
and length >= 0
, returns a new empty Array.
If #length is negative, returns nil
.
When a single ::Range
argument range
is given, treats range.min
as start
above and range.size
as #length above:
a = [:foo, 'bar', 2]
a[0..1] # => [:foo, "bar"]
a[1..2] # => ["bar", 2]
Special case: If range.start == a.size
, returns a new empty Array.
If range.end
is negative, calculates the end index from the end:
a = [:foo, 'bar', 2]
a[0..-1] # => [:foo, "bar", 2]
a[0..-2] # => [:foo, "bar"]
a[0..-3] # => [:foo]
If range.start
is negative, calculates the start index from the end:
a = [:foo, 'bar', 2]
a[-1..2] # => [2]
a[-2..2] # => ["bar", 2]
a[-3..2] # => [:foo, "bar", 2]
If range.start
is larger than the array size, returns nil
.
a = [:foo, 'bar', 2]
a[4..1] # => nil
a[4..0] # => nil
a[4..-1] # => nil
When a single ::Enumerator::ArithmeticSequence
argument aseq
is given, returns an Array of elements corresponding to the indexes produced by the sequence.
a = ['--', 'data1', '--', 'data2', '--', 'data3']
a[(1..).step(2)] # => ["data1", "data2", "data3"]
Unlike slicing with range, if the start or the end of the arithmetic sequence is larger than array size, throws ::RangeError
.
a = ['--', 'data1', '--', 'data2', '--', 'data3']
a[(1..11).step(2)]
# RangeError (((1..11).step(2)) out of range)
a[(7..).step(2)]
# RangeError (((7..).step(2)) out of range)
If given a single argument, and its type is not one of the listed, tries to convert it to ::Integer
, and raises if it is impossible:
a = [:foo, 'bar', 2]
# Raises TypeError (no implicit conversion of Symbol into Integer):
a[:foo]
# File 'array.c', line 1826
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]); }
Assigns elements in self
; returns the given object
.
When Integer argument #index is given, assigns object
to an element in self
.
If #index is non-negative, assigns object
the element at offset #index:
a = [:foo, 'bar', 2]
a[0] = 'foo' # => "foo"
a # => ["foo", "bar", 2]
If #index is greater than self.length
, extends the array:
a = [:foo, 'bar', 2]
a[7] = 'foo' # => "foo"
a # => [:foo, "bar", 2, nil, nil, nil, nil, "foo"]
If #index is negative, counts backwards from the end of the array:
a = [:foo, 'bar', 2]
a[-1] = 'two' # => "two"
a # => [:foo, "bar", "two"]
When Integer arguments start
and #length are given and object
is not an Array, removes length - 1
elements beginning at offset start
, and assigns object
at offset start
:
a = [:foo, 'bar', 2]
a[0, 2] = 'foo' # => "foo"
a # => ["foo", 2]
If start
is negative, counts backwards from the end of the array:
a = [:foo, 'bar', 2]
a[-2, 2] = 'foo' # => "foo"
a # => [:foo, "foo"]
If start
is non-negative and outside the array ( >= self.size
), extends the array with nil
, assigns object
at offset start
, and ignores #length:
a = [:foo, 'bar', 2]
a[6, 50] = 'foo' # => "foo"
a # => [:foo, "bar", 2, nil, nil, nil, "foo"]
If #length is zero, shifts elements at and following offset start
and assigns object
at offset start
:
a = [:foo, 'bar', 2]
a[1, 0] = 'foo' # => "foo"
a # => [:foo, "foo", "bar", 2]
If #length is too large for the existing array, does not extend the array:
a = [:foo, 'bar', 2]
a[1, 5] = 'foo' # => "foo"
a # => [:foo, "foo"]
When Range argument range
is given and object
is an Array, removes length - 1
elements beginning at offset start
, and assigns object
at offset start
:
a = [:foo, 'bar', 2]
a[0..1] = 'foo' # => "foo"
a # => ["foo", 2]
if range.begin
is negative, counts backwards from the end of the array:
a = [:foo, 'bar', 2]
a[-2..2] = 'foo' # => "foo"
a # => [:foo, "foo"]
If the array length is less than range.begin
, assigns object
at offset range.begin
, and ignores #length:
a = [:foo, 'bar', 2]
a[6..50] = 'foo' # => "foo"
a # => [:foo, "bar", 2, nil, nil, nil, "foo"]
If range.end
is zero, shifts elements at and following offset start
and assigns object
at offset start
:
a = [:foo, 'bar', 2]
a[1..0] = 'foo' # => "foo"
a # => [:foo, "foo", "bar", 2]
If range.end
is negative, assigns object
at offset start
, retains range.end.abs -1
elements past that, and removes those beyond:
a = [:foo, 'bar', 2]
a[1..-1] = 'foo' # => "foo"
a # => [:foo, "foo"]
a = [:foo, 'bar', 2]
a[1..-2] = 'foo' # => "foo"
a # => [:foo, "foo", 2]
a = [:foo, 'bar', 2]
a[1..-3] = 'foo' # => "foo"
a # => [:foo, "foo", "bar", 2]
a = [:foo, 'bar', 2]
If range.end
is too large for the existing array, replaces array elements, but does not extend the array with nil
values:
a = [:foo, 'bar', 2]
a[1..5] = 'foo' # => "foo"
a # => [:foo, "foo"]
# File 'array.c', line 2392
static VALUE rb_ary_aset(int argc, VALUE *argv, VALUE ary) { long offset, beg, len; rb_check_arity(argc, 2, 3); rb_ary_modify_check(ary); if (argc == 3) { beg = NUM2LONG(argv[0]); len = NUM2LONG(argv[1]); return ary_aset_by_rb_ary_splice(ary, beg, len, argv[2]); } if (FIXNUM_P(argv[0])) { offset = FIX2LONG(argv[0]); return ary_aset_by_rb_ary_store(ary, offset, argv[1]); } if (rb_range_beg_len(argv[0], &beg, &len, RARRAY_LEN(ary), 1)) { /* check if idx is Range */ return ary_aset_by_rb_ary_splice(ary, beg, len, argv[1]); } offset = NUM2LONG(argv[0]); return ary_aset_by_rb_ary_store(ary, offset, argv[1]); }
#all? ⇒ Boolean
#all? {|element| ... } ⇒ Boolean
#all?(obj) ⇒ Boolean
Boolean
#all? {|element| ... } ⇒ Boolean
#all?(obj) ⇒ Boolean
Returns true
if all elements of self
meet a given criterion.
If self
has no element, returns true
and argument or block are not used.
With no block given and no argument, returns true
if self
contains only truthy elements, false
otherwise:
[0, 1, :foo].all? # => true
[0, nil, 2].all? # => false
[].all? # => true
With a block given and no argument, calls the block with each element in self
; returns true
if the block returns only truthy values, false
otherwise:
[0, 1, 2].all? { |element| element < 3 } # => true
[0, 1, 2].all? { |element| element < 2 } # => false
If argument obj
is given, returns true
if obj.===
every element, false
otherwise:
['food', 'fool', 'foot'].all?(/foo/) # => true
['food', 'drink'].all?(/bar/) # => false
[].all?(/foo/) # => true
[0, 0, 0].all?(0) # => true
[0, 1, 2].all?(1) # => false
Related: Enumerable#all?
# File 'array.c', line 7739
static VALUE rb_ary_all_p(int argc, VALUE *argv, VALUE ary) { long i, len = RARRAY_LEN(ary); rb_check_arity(argc, 0, 1); if (!len) return Qtrue; if (argc) { if (rb_block_given_p()) { rb_warn("given block not used"); } for (i = 0; i < RARRAY_LEN(ary); ++i) { if (!RTEST(rb_funcall(argv[0], idEqq, 1, RARRAY_AREF(ary, i)))) return Qfalse; } } else if (!rb_block_given_p()) { for (i = 0; i < len; ++i) { if (!RTEST(RARRAY_AREF(ary, i))) return Qfalse; } } else { for (i = 0; i < RARRAY_LEN(ary); ++i) { if (!RTEST(rb_yield(RARRAY_AREF(ary, i)))) return Qfalse; } } return Qtrue; }
#any? ⇒ Boolean
#any? {|element| ... } ⇒ Boolean
#any?(obj) ⇒ Boolean
Boolean
#any? {|element| ... } ⇒ Boolean
#any?(obj) ⇒ Boolean
Returns true
if any element of self
meets a given criterion.
If self
has no element, returns false
and argument or block are not used.
With no block given and no argument, returns true
if self
has any truthy element, false
otherwise:
[nil, 0, false].any? # => true
[nil, false].any? # => false
[].any? # => false
With a block given and no argument, calls the block with each element in self
; returns true
if the block returns any truthy value, false
otherwise:
[0, 1, 2].any? {|element| element > 1 } # => true
[0, 1, 2].any? {|element| element > 2 } # => false
If argument obj
is given, returns true
if obj
.===
any element, false
otherwise:
['food', 'drink'].any?(/foo/) # => true
['food', 'drink'].any?(/bar/) # => false
[].any?(/foo/) # => false
[0, 1, 2].any?(1) # => true
[0, 1, 2].any?(3) # => false
Related: Enumerable#any?
# File 'array.c', line 7676
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
self
#append(*objects) ⇒ self
Alias for #push.
#assoc(obj) ⇒ Array
?
# File 'array.c', line 5021
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
# File 'array.c', line 1880
VALUE rb_ary_at(VALUE ary, VALUE pos) { return rb_ary_entry(ary, NUM2LONG(pos)); }
#bsearch {|element| ... } ⇒ Object
#bsearch ⇒ Enumerator
Returns an element from self
selected by a binary search.
See Binary Searching
.
# File 'array.c', line 3492
static VALUE rb_ary_bsearch(VALUE ary) { VALUE index_result = rb_ary_bsearch_index(ary); if (FIXNUM_P(index_result)) { return rb_ary_entry(ary, FIX2LONG(index_result)); } return index_result; }
#bsearch_index {|element| ... } ⇒ Integer?
#bsearch_index ⇒ Enumerator
Searches self
as described at method #bsearch, but returns the index of the found element instead of the element itself.
# File 'array.c', line 3512
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 (!RTEST(v)) { 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 = 0; break; case -1: smaller = 1; } } else { rb_raise(rb_eTypeError, "wrong argument type %"PRIsVALUE " (must be numeric, true, false or nil)", rb_obj_class(v)); } if (smaller) { high = mid; } else { low = mid + 1; } } if (!satisfied) return Qnil; return INT2FIX(low); }
#clear ⇒ self
Removes all elements from self
:
a = [:foo, 'bar', 2]
a.clear # => []
# File 'array.c', line 4584
VALUE rb_ary_clear(VALUE ary) { rb_ary_modify_check(ary); if (ARY_SHARED_P(ary)) { if (!ARY_EMBED_P(ary)) { rb_ary_unshare(ary); FL_SET_EMBED(ary); ARY_SET_EMBED_LEN(ary, 0); } } else { ARY_SET_LEN(ary, 0); if (ARY_DEFAULT_SIZE * 2 < ARY_CAPA(ary)) { ary_resize_capa(ary, ARY_DEFAULT_SIZE * 2); } } ary_verify(ary); return ary; }
#map {|element| ... } ⇒ Array
#map ⇒ Enumerator
Array
#map ⇒ Enumerator
Alias for #map.
#map! {|element| ... } ⇒ self
#map! ⇒ Enumerator
self
#map! ⇒ Enumerator
Alias for #map!.
#combination(n) {|element| ... } ⇒ self
#combination(n) ⇒ Enumerator
self
#combination(n) ⇒ Enumerator
Calls the block, if given, with combinations of elements of self
; returns self
. The order of combinations is indeterminate.
When a block and an in-range positive ::Integer
argument n
(0 < n <= self.size
) are given, calls the block with all n
-tuple combinations of self
.
Example:
a = [0, 1, 2]
a.combination(2) {|combination| p combination }
Output:
[0, 1]
[0, 2]
[1, 2]
Another example:
a = [0, 1, 2]
a.combination(3) {|combination| p combination }
Output:
[0, 1, 2]
When n
is zero, calls the block once with a new empty Array:
a = [0, 1, 2]
a1 = a.combination(0) {|combination| p combination }
Output:
[]
When n
is out of range (negative or larger than self.size
), does not call the block:
a = [0, 1, 2]
a.combination(-1) {|combination| fail 'Cannot happen' }
a.combination(4) {|combination| fail 'Cannot happen' }
Returns a new ::Enumerator
if no block given:
a = [0, 1, 2]
a.combination(2) # => #<Enumerator: [0, 1, 2]:combination(2)>
# File 'array.c', line 7053
static VALUE rb_ary_combination(VALUE ary, VALUE num) { long i, n, len; n = NUM2LONG(num); RETURN_SIZED_ENUMERATOR(ary, 1, &num, rb_ary_combination_size); len = RARRAY_LEN(ary); if (n < 0 || len < n) { /* yield nothing */ } else if (n == 0) { rb_yield(rb_ary_new2(0)); } else if (n == 1) { for (i = 0; i < RARRAY_LEN(ary); i++) { rb_yield(rb_ary_new3(1, RARRAY_AREF(ary, i))); } } else { VALUE ary0 = ary_make_shared_copy(ary); /* private defensive copy of ary */ volatile VALUE t0; long *stack = ALLOCV_N(long, t0, n+1); RBASIC_CLEAR_CLASS(ary0); combinate0(len, n, stack, ary0); ALLOCV_END(t0); RBASIC_SET_CLASS_RAW(ary0, rb_cArray); } return ary; }
#compact ⇒ Array
Returns a new Array containing all non-nil
elements from self
:
a = [nil, 0, nil, 1, nil, 2, nil]
a.compact # => [0, 1, 2]
# File 'array.c', line 6239
static VALUE rb_ary_compact(VALUE ary) { ary = rb_ary_dup(ary); rb_ary_compact_bang(ary); return ary; }
#compact! ⇒ self
?
Removes all nil
elements from self
.
Returns self
if any elements removed, otherwise nil
.
# File 'array.c', line 6206
static VALUE rb_ary_compact_bang(VALUE ary) { VALUE *p, *t, *end; long n; rb_ary_modify(ary); p = t = (VALUE *)RARRAY_CONST_PTR(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(ary); if (RARRAY_LEN(ary) == n) { return Qnil; } ary_resize_smaller(ary, n); return ary; }
#concat(*other_arrays) ⇒ self
Adds to array
all elements from each Array in other_arrays
; returns self
:
a = [0, 1]
a.concat([2, 3], [4, 5]) # => [0, 1, 2, 3, 4, 5]
# File 'array.c', line 4917
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_hidden_new(argc); for (i = 0; i < argc; i++) { rb_ary_concat(args, argv[i]); } ary_append(ary, args); } ary_verify(ary); return ary; }
Returns a count of specified elements.
With no argument and no block, returns the count of all elements:
[0, 1, 2].count # => 3
[].count # => 0
With argument obj
, returns the count of elements #== to obj
:
[0, 1, 2, 0.0].count(0) # => 2
[0, 1, 2].count(3) # => 0
With no argument and a block given, calls the block with each element; returns the count of elements for which the block returns a truthy value:
[0, 1, 2, 3].count {|element| element > 1} # => 2
With argument obj
and a block given, issues a warning, ignores the block, and returns the count of elements #== to obj
.
# File 'array.c', line 6274
static VALUE rb_ary_count(int argc, VALUE *argv, VALUE ary) { long i, n = 0; if (rb_check_arity(argc, 0, 1) == 0) { VALUE v; if (!rb_block_given_p()) return LONG2NUM(RARRAY_LEN(ary)); for (i = 0; i < RARRAY_LEN(ary); i++) { v = RARRAY_AREF(ary, i); if (RTEST(rb_yield(v))) n++; } } else { VALUE obj = argv[0]; if (rb_block_given_p()) { rb_warn("given block not used"); } for (i = 0; i < RARRAY_LEN(ary); i++) { if (rb_equal(RARRAY_AREF(ary, i), obj)) n++; } } return LONG2NUM(n); }
#cycle {|element| ... } ⇒ nil
#cycle(count) {|element| ... } ⇒ nil
#cycle ⇒ Enumerator
#cycle(count) ⇒ Enumerator
nil
#cycle(count) {|element| ... } ⇒ nil
#cycle ⇒ Enumerator
#cycle(count) ⇒ Enumerator
When called with positive ::Integer
argument #count and a block, calls the block with each element, then does so again, until it has done so #count times; returns nil
:
output = []
[0, 1].cycle(2) {|element| output.push(element) } # => nil
output # => [0, 1, 0, 1]
If #count is zero or negative, does not call the block:
[0, 1].cycle(0) {|element| fail 'Cannot happen' } # => nil
[0, 1].cycle(-1) {|element| fail 'Cannot happen' } # => nil
When a block is given, and argument is omitted or nil
, cycles forever:
# Prints 0 and 1 forever.
[0, 1].cycle {|element| puts element }
[0, 1].cycle(nil) {|element| puts element }
When no block is given, returns a new ::Enumerator
:
[0, 1].cycle(2) # => #<Enumerator: [0, 1]:cycle(2)>
[0, 1].cycle # => # => #<Enumerator: [0, 1]:cycle>
[0, 1].cycle.first(5) # => [0, 1, 0, 1, 0]
# File 'array.c', line 6711
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
# File 'array.c', line 8102
static VALUE rb_ary_deconstruct(VALUE ary) { return ary; }
#delete(obj) ⇒ deleted_object
#delete(obj) {|nosuch| ... } ⇒ deleted_object
, block_return
deleted_object
#delete(obj) {|nosuch| ... } ⇒ deleted_object
, block_return
Removes zero or more elements from self
.
When no block is given, removes from self
each element ele
such that ele == obj
; returns the last deleted element:
s1 = 'bar'; s2 = 'bar'
a = [:foo, s1, 2, s2]
a.delete('bar') # => "bar"
a # => [:foo, 2]
Returns nil
if no elements removed.
When a block is given, removes from self
each element ele
such that ele == obj
.
If any such elements are found, ignores the block and returns the last deleted element:
s1 = 'bar'; s2 = 'bar'
a = [:foo, s1, 2, s2]
deleted_obj = a.delete('bar') {|obj| fail 'Cannot happen' }
a # => [:foo, 2]
If no such elements are found, returns the block’s return value:
a = [:foo, 'bar', 2]
a.delete(:nosuch) {|obj| "#{obj} not found" } # => "nosuch not found"
# File 'array.c', line 3972
VALUE rb_ary_delete(VALUE ary, VALUE item) { VALUE v = item; long i1, i2; for (i1 = i2 = 0; i1 < RARRAY_LEN(ary); i1++) { VALUE e = RARRAY_AREF(ary, i1); if (rb_equal(e, item)) { v = e; continue; } if (i1 != i2) { rb_ary_store(ary, i2, e); } i2++; } if (RARRAY_LEN(ary) == i2) { if (rb_block_given_p()) { return rb_yield(item); } return Qnil; } ary_resize_smaller(ary, i2); ary_verify(ary); return v; }
#delete_at(index) ⇒ deleted_object
?
Deletes an element from self
, per the given ::Integer
#index.
When #index is non-negative, deletes the element at offset #index:
a = [:foo, 'bar', 2]
a.delete_at(1) # => "bar"
a # => [:foo, 2]
If index is too large, returns nil
.
When #index is negative, counts backward from the end of the array:
a = [:foo, 'bar', 2]
a.delete_at(-2) # => "bar"
a # => [:foo, 2]
If #index is too small (far from zero), returns nil.
# File 'array.c', line 4071
static VALUE rb_ary_delete_at_m(VALUE ary, VALUE pos) { return rb_ary_delete_at(ary, NUM2LONG(pos)); }
#delete_if {|element| ... } ⇒ self
#delete_if ⇒ Enumerator
self
#delete_if ⇒ Enumerator
Removes each element in self
for which the block returns a truthy value; returns self
:
a = [:foo, 'bar', 2, 'bat']
a.delete_if {|element| element.to_s.start_with?('b') } # => [:foo, 2]
Returns a new ::Enumerator
if no block given:
a = [:foo, 'bar', 2]
a.delete_if # => #<Enumerator: [:foo, "bar", 2]:delete_if>
# File 'array.c', line 4329
static VALUE rb_ary_delete_if(VALUE ary) { ary_verify(ary); RETURN_SIZED_ENUMERATOR(ary, 0, 0, ary_enum_length); ary_reject_bang(ary); return ary; }
#difference(*other_arrays) ⇒ Array
Returns a new Array containing only those elements from self
that are not found in any of the Arrays other_arrays
; items are compared using #eql?; order from self
is preserved:
[0, 1, 1, 2, 1, 1, 3, 1, 1].difference([1]) # => [0, 2, 3]
[0, 1, 2, 3].difference([3, 0], [1, 3]) # => [2]
[0, 1, 2].difference([4]) # => [0, 1, 2]
Returns a copy of self
if no arguments given.
Related: #-.
# File 'array.c', line 5429
static VALUE rb_ary_difference_multi(int argc, VALUE *argv, VALUE ary) { VALUE ary_diff; long i, length; volatile VALUE t0; bool *is_hash = ALLOCV_N(bool, t0, argc); ary_diff = rb_ary_new(); length = RARRAY_LEN(ary); for (i = 0; i < argc; i++) { argv[i] = to_ary(argv[i]); is_hash[i] = (length > SMALL_ARRAY_LEN && RARRAY_LEN(argv[i]) > SMALL_ARRAY_LEN); if (is_hash[i]) argv[i] = ary_make_hash(argv[i]); } for (i = 0; i < RARRAY_LEN(ary); i++) { int j; VALUE elt = rb_ary_elt(ary, i); for (j = 0; j < argc; j++) { if (is_hash[j]) { if (rb_hash_stlike_lookup(argv[j], RARRAY_AREF(ary, i), NULL)) break; } else { if (rb_ary_includes_by_eql(argv[j], elt)) break; } } if (j == argc) rb_ary_push(ary_diff, elt); } ALLOCV_END(t0); return ary_diff; }
#dig(index, *identifiers) ⇒ Object
Finds and returns the object in nested objects that is specified by #index and identifiers
. The nested objects may be instances of various classes. See Dig Methods
.
Examples:
a = [:foo, [:, :baz, [:bat, :bam]]]
a.dig(1) # => [:bar, :baz, [:bat, :bam]]
a.dig(1, 2) # => [:bat, :bam]
a.dig(1, 2, 0) # => :bat
a.dig(1, 2, 3) # => nil
# File 'array.c', line 7920
static VALUE rb_ary_dig(int argc, VALUE *argv, VALUE self) { rb_check_arity(argc, 1, UNLIMITED_ARGUMENTS); self = rb_ary_at(self, *argv); if (!--argc) return self; ++argv; return rb_obj_dig(argc, argv, self, Qnil); }
#drop(n) ⇒ Array
Returns a new Array containing all but the first n
element of self
, where n
is a non-negative Integer; does not modify self
.
Examples:
a = [0, 1, 2, 3, 4, 5]
a.drop(0) # => [0, 1, 2, 3, 4, 5]
a.drop(1) # => [1, 2, 3, 4, 5]
a.drop(2) # => [2, 3, 4, 5]
# File 'array.c', line 7593
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 (NIL_P(result)) result = rb_ary_new(); return result; }
#drop_while {|element| ... } ⇒ Array
#drop_while ⇒ Enumerator
Array
#drop_while ⇒ Enumerator
Returns a new Array containing zero or more trailing elements of self
; does not modify self
.
With a block given, calls the block with each successive element of self
; stops if the block returns false
or nil
; returns a new Array omitting those elements for which the block returned a truthy value:
a = [0, 1, 2, 3, 4, 5]
a.drop_while {|element| element < 3 } # => [3, 4, 5]
With no block given, returns a new ::Enumerator
:
[0, 1].drop_while # => # => #<Enumerator: [0, 1]:drop_while>
# File 'array.c', line 7628
static VALUE rb_ary_drop_while(VALUE ary) { long i; RETURN_ENUMERATOR(ary, 0, 0); for (i = 0; i < RARRAY_LEN(ary); i++) { if (!RTEST(rb_yield(RARRAY_AREF(ary, i)))) break; } return rb_ary_drop(ary, LONG2FIX(i)); }
#each {|element| ... } ⇒ self
#each ⇒ Enumerator
self
#each ⇒ Enumerator
Iterates over array elements.
When a block given, passes each successive array element to the block; returns self
:
a = [:foo, 'bar', 2]
a.each {|element| puts "#{element.class} #{element}" }
Output:
Symbol foo
String
Integer 2
Allows the array to be modified during iteration:
a = [:foo, 'bar', 2]
a.each {|element| puts element; a.clear if element.to_s.start_with?('b') }
Output:
foo
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
Integer 2
Related: #each_index, #reverse_each.
# File 'array.c', line 2531
VALUE rb_ary_each(VALUE ary) { long i; ary_verify(ary); RETURN_SIZED_ENUMERATOR(ary, 0, 0, ary_enum_length); for (i=0; i<RARRAY_LEN(ary); i++) { rb_yield(RARRAY_AREF(ary, i)); } return ary; }
#each_index {|index| ... } ⇒ self
#each_index ⇒ Enumerator
self
#each_index ⇒ Enumerator
Iterates over array indexes.
When a block given, passes each successive array index to the block; returns self
:
a = [:foo, 'bar', 2]
a.each_index {|index| puts "#{index} #{a[index]}" }
Output:
0 foo
1
2 2
Allows the array to be modified during iteration:
a = [:foo, 'bar', 2]
a.each_index {|index| puts index; a.clear if index > 0 }
Output:
0
1
When no block given, returns a new ::Enumerator
:
a = [:foo, 'bar', 2]
e = a.each_index
e # => #<Enumerator: [:foo, "bar", 2]:each_index>
a1 = e.each {|index| puts "#{index} #{a[index]}"}
Output:
0 foo
1
2 2
Related: #each, #reverse_each.
# File 'array.c', line 2588
static VALUE rb_ary_each_index(VALUE ary) { long i; RETURN_SIZED_ENUMERATOR(ary, 0, 0, ary_enum_length); for (i=0; i<RARRAY_LEN(ary); i++) { rb_yield(LONG2NUM(i)); } return ary; }
#eql?(other_array) ⇒ Boolean
Returns true
if self
and other_array
are the same size, and if, for each index i
in self
, self[i].eql? other_array[i]
:
a0 = [:foo, 'bar', 2]
a1 = [:foo, 'bar', 2]
a1.eql?(a0) # => true
Otherwise, returns false
.
This method is different from method #==, which compares using method Object#==
.
# File 'array.c', line 5164
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(ary1) == RARRAY_CONST_PTR(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
element
#fetch(index, default_value) ⇒ element
#fetch(index) {|index| ... } ⇒ element
Returns the element at offset #index.
With the single ::Integer
argument #index, returns the element at offset #index:
a = [:foo, 'bar', 2]
a.fetch(1) # => "bar"
If #index is negative, counts from the end of the array:
a = [:foo, 'bar', 2]
a.fetch(-1) # => 2
a.fetch(-2) # => "bar"
With arguments #index and default_value
, returns the element at offset #index if index is in range, otherwise returns default_value
:
a = [:foo, 'bar', 2]
a.fetch(1, nil) # => "bar"
With argument #index and a block, returns the element at offset #index if index is in range (and the block is not called); otherwise calls the block with index and returns its return value:
a = [:foo, 'bar', 2]
a.fetch(1) {|index| raise 'Cannot happen' } # => "bar"
a.fetch(50) {|index| "Value for #{index}" } # => "Value for 50"
# File 'array.c', line 1961
static VALUE rb_ary_fetch(int argc, VALUE *argv, VALUE ary) { VALUE pos, ifnone; long block_given; long idx; rb_scan_args(argc, argv, "11", &pos, &ifnone); block_given = rb_block_given_p(); if (block_given && argc == 2) { rb_warn("block supersedes default value argument"); } idx = NUM2LONG(pos); if (idx < 0) { idx += RARRAY_LEN(ary); } if (idx < 0 || RARRAY_LEN(ary) <= idx) { if (block_given) return rb_yield(pos); if (argc == 1) { rb_raise(rb_eIndexError, "index %ld outside of array bounds: %ld...%ld", idx - (idx < 0 ? RARRAY_LEN(ary) : 0), -RARRAY_LEN(ary), RARRAY_LEN(ary)); } return ifnone; } return RARRAY_AREF(ary, idx); }
#fill(obj) ⇒ self
#fill(obj, start) ⇒ self
#fill(obj, start, length) ⇒ self
#fill(obj, range) ⇒ self
#fill {|index| ... } ⇒ self
#fill(start) {|index| ... } ⇒ self
#fill(start, length) {|index| ... } ⇒ self
#fill(range) {|index| ... } ⇒ self
self
#fill(obj, start) ⇒ self
#fill(obj, start, length) ⇒ self
#fill(obj, range) ⇒ self
#fill {|index| ... } ⇒ self
#fill(start) {|index| ... } ⇒ self
#fill(start, length) {|index| ... } ⇒ self
#fill(range) {|index| ... } ⇒ self
Replaces specified elements in self
with specified objects; returns self
.
With argument obj
and no block given, replaces all elements with that one object:
a = ['a', 'b', 'c', 'd']
a # => ["a", "b", "c", "d"]
a.fill(:X) # => [:X, :X, :X, :X]
With arguments obj
and ::Integer
start
, and no block given, replaces elements based on the given start.
If start
is in range (0 <= start < array.size
), replaces all elements from offset start
through the end:
a = ['a', 'b', 'c', 'd']
a.fill(:X, 2) # => ["a", "b", :X, :X]
If start
is too large (start >= array.size
), does nothing:
a = ['a', 'b', 'c', 'd']
a.fill(:X, 4) # => ["a", "b", "c", "d"]
a = ['a', 'b', 'c', 'd']
a.fill(:X, 5) # => ["a", "b", "c", "d"]
If start
is negative, counts from the end (starting index is start + array.size
):
a = ['a', 'b', 'c', 'd']
a.fill(:X, -2) # => ["a", "b", :X, :X]
If start
is too small (less than and far from zero), replaces all elements:
a = ['a', 'b', 'c', 'd']
a.fill(:X, -6) # => [:X, :X, :X, :X]
a = ['a', 'b', 'c', 'd']
a.fill(:X, -50) # => [:X, :X, :X, :X]
With arguments obj
, ::Integer
start
, and ::Integer
#length, and no block given, replaces elements based on the given start
and #length.
If start
is in range, replaces #length elements beginning at offset start
:
a = ['a', 'b', 'c', 'd']
a.fill(:X, 1, 1) # => ["a", :X, "c", "d"]
If start
is negative, counts from the end:
a = ['a', 'b', 'c', 'd']
a.fill(:X, -2, 1) # => ["a", "b", :X, "d"]
If start
is large (start >= array.size
), extends self
with nil
:
a = ['a', 'b', 'c', 'd']
a.fill(:X, 5, 0) # => ["a", "b", "c", "d", nil]
a = ['a', 'b', 'c', 'd']
a.fill(:X, 5, 2) # => ["a", "b", "c", "d", nil, :X, :X]
If #length is zero or negative, replaces no elements:
a = ['a', 'b', 'c', 'd']
a.fill(:X, 1, 0) # => ["a", "b", "c", "d"]
a.fill(:X, 1, -1) # => ["a", "b", "c", "d"]
With arguments obj
and ::Range
range
, and no block given, replaces elements based on the given range.
If the range is positive and ascending (0 < range.begin <= range.end
), replaces elements from range.begin
to range.end
:
a = ['a', 'b', 'c', 'd']
a.fill(:X, (1..1)) # => ["a", :X, "c", "d"]
If range.first
is negative, replaces no elements:
a = ['a', 'b', 'c', 'd']
a.fill(:X, (-1..1)) # => ["a", "b", "c", "d"]
If range.last
is negative, counts from the end:
a = ['a', 'b', 'c', 'd']
a.fill(:X, (0..-2)) # => [:X, :X, :X, "d"]
a = ['a', 'b', 'c', 'd']
a.fill(:X, (1..-2)) # => ["a", :X, :X, "d"]
If range.last
and range.last
are both negative, both count from the end of the array:
a = ['a', 'b', 'c', 'd']
a.fill(:X, (-1..-1)) # => ["a", "b", "c", :X]
a = ['a', 'b', 'c', 'd']
a.fill(:X, (-2..-2)) # => ["a", "b", :X, "d"]
With no arguments and a block given, calls the block with each index; replaces the corresponding element with the block’s return value:
a = ['a', 'b', 'c', 'd']
a.fill { |index| "new_#{index}" } # => ["new_0", "new_1", "new_2", "new_3"]
With argument start
and a block given, calls the block with each index from offset start
to the end; replaces the corresponding element with the block’s return value.
If start is in range (0 <= start < array.size
), replaces from offset start
to the end:
a = ['a', 'b', 'c', 'd']
a.fill(1) { |index| "new_#{index}" } # => ["a", "new_1", "new_2", "new_3"]
If start
is too large(start >= array.size
), does nothing:
a = ['a', 'b', 'c', 'd']
a.fill(4) { |index| fail 'Cannot happen' } # => ["a", "b", "c", "d"]
a = ['a', 'b', 'c', 'd']
a.fill(4) { |index| fail 'Cannot happen' } # => ["a", "b", "c", "d"]
If start
is negative, counts from the end:
a = ['a', 'b', 'c', 'd']
a.fill(-2) { |index| "new_#{index}" } # => ["a", "b", "new_2", "new_3"]
If start is too small (start <= -array.size
, replaces all elements:
a = ['a', 'b', 'c', 'd']
a.fill(-6) { |index| "new_#{index}" } # => ["new_0", "new_1", "new_2", "new_3"]
a = ['a', 'b', 'c', 'd']
a.fill(-50) { |index| "new_#{index}" } # => ["new_0", "new_1", "new_2", "new_3"]
With arguments start
and #length, and a block given, calls the block for each index specified by start length; replaces the corresponding element with the block’s return value.
If start
is in range, replaces #length elements beginning at offset start
:
a = ['a', 'b', 'c', 'd']
a.fill(1, 1) { |index| "new_#{index}" } # => ["a", "new_1", "c", "d"]
If start is negative, counts from the end:
a = ['a', 'b', 'c', 'd']
a.fill(-2, 1) { |index| "new_#{index}" } # => ["a", "b", "new_2", "d"]
If start
is large (start >= array.size
), extends self
with nil
:
a = ['a', 'b', 'c', 'd']
a.fill(5, 0) { |index| "new_#{index}" } # => ["a", "b", "c", "d", nil]
a = ['a', 'b', 'c', 'd']
a.fill(5, 2) { |index| "new_#{index}" } # => ["a", "b", "c", "d", nil, "new_5", "new_6"]
If #length is zero or less, replaces no elements:
a = ['a', 'b', 'c', 'd']
a.fill(1, 0) { |index| "new_#{index}" } # => ["a", "b", "c", "d"]
a.fill(1, -1) { |index| "new_#{index}" } # => ["a", "b", "c", "d"]
With arguments obj
and range
, and a block given, calls the block with each index in the given range; replaces the corresponding element with the block’s return value.
If the range is positive and ascending (range 0 < range.begin <= range.end
, replaces elements from range.begin
to range.end
:
a = ['a', 'b', 'c', 'd']
a.fill(1..1) { |index| "new_#{index}" } # => ["a", "new_1", "c", "d"]
If range.first
is negative, does nothing:
a = ['a', 'b', 'c', 'd']
a.fill(-1..1) { |index| fail 'Cannot happen' } # => ["a", "b", "c", "d"]
If range.last
is negative, counts from the end:
a = ['a', 'b', 'c', 'd']
a.fill(0..-2) { |index| "new_#{index}" } # => ["new_0", "new_1", "new_2", "d"]
a = ['a', 'b', 'c', 'd']
a.fill(1..-2) { |index| "new_#{index}" } # => ["a", "new_1", "new_2", "d"]
If range.first
and range.last
are both negative, both count from the end:
a = ['a', 'b', 'c', 'd']
a.fill(-1..-1) { |index| "new_#{index}" } # => ["a", "b", "c", "new_3"]
a = ['a', 'b', 'c', 'd']
a.fill(-2..-2) { |index| "new_#{index}" } # => ["a", "b", "new_2", "d"]
# File 'array.c', line 4801
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 (UNDEF_P(item)) { VALUE v; long i; for (i=beg; i<end; i++) { v = rb_yield(LONG2NUM(i)); if (i>=RARRAY_LEN(ary)) break; ARY_SET(ary, i, v); } } else { ary_memfill(ary, beg, len, item); } return ary; }
#select {|element| ... } ⇒ Array
#select ⇒ Enumerator
Also known as: #select
Array
#select ⇒ Enumerator
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>
# File 'array.c', line 3801
static VALUE rb_ary_select(VALUE ary) { VALUE result; long i; RETURN_SIZED_ENUMERATOR(ary, 0, 0, ary_enum_length); result = rb_ary_new2(RARRAY_LEN(ary)); for (i = 0; i < RARRAY_LEN(ary); i++) { if (RTEST(rb_yield(RARRAY_AREF(ary, i)))) { rb_ary_push(result, rb_ary_elt(ary, i)); } } return result; }
#select! {|element| ... } ⇒ self
?
#select! ⇒ Enumerator
Also known as: #select!
self
?
#select! ⇒ Enumerator
Calls the block, if given with each element of self
; removes from self
those elements for which the block returns false
or nil
.
Returns self
if any elements were removed:
a = [:foo, 'bar', 2, :bam]
a.select! {|element| element.to_s.start_with?('b') } # => ["bar", :bam]
Returns nil
if no elements were removed.
Returns a new ::Enumerator
if no block given:
a = [:foo, 'bar', 2, :bam]
a.select! # => #<Enumerator: [:foo, "bar", 2, :bam]:select!>
# File 'array.c', line 3884
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); }
Alias for #index.
#first ⇒ Object?
#first(n) ⇒ Array
Array
Returns elements from self
; does not modify self
.
When no argument is given, returns the first element:
a = [:foo, 'bar', 2]
a.first # => :foo
a # => [:foo, "bar", 2]
If self
is empty, returns nil
.
When non-negative ::Integer
argument n
is given, returns the first n
elements in a new Array:
a = [:foo, 'bar', 2]
a.first(2) # => [:foo, "bar"]
If n >= array.size
, returns all elements:
a = [:foo, 'bar', 2]
a.first(50) # => [:foo, "bar", 2]
If n == 0
returns an new empty Array:
a = [:foo, 'bar', 2]
a.first(0) # []
Related: #last.
# File 'array.rb', line 101
def first n = unspecified = true if Primitive.mandatory_only? Primitive.attr! :leaf Primitive.cexpr! %q{ ary_first(self) } else if unspecified Primitive.cexpr! %q{ ary_first(self) } else Primitive.cexpr! %q{ ary_take_first_or_last_n(self, NUM2LONG(n), ARY_TAKE_FIRST) } end end end
#flatten ⇒ Array
#flatten(level) ⇒ Array
Array
#flatten(level) ⇒ Array
Returns a new Array that is a recursive flattening of self
:
-
Each non-Array element is unchanged.
-
Each Array is replaced by its individual elements.
With non-negative ::Integer
argument level
, flattens recursively through level
levels:
a = [ 0, [ 1, [2, 3], 4 ], 5 ]
a.flatten(0) # => [0, [1, [2, 3], 4], 5]
a = [ 0, [ 1, [2, 3], 4 ], 5 ]
a.flatten(1) # => [0, 1, [2, 3], 4, 5]
a = [ 0, [ 1, [2, 3], 4 ], 5 ]
a.flatten(2) # => [0, 1, 2, 3, 4, 5]
a = [ 0, [ 1, [2, 3], 4 ], 5 ]
a.flatten(3) # => [0, 1, 2, 3, 4, 5]
With no argument, a nil
argument, or with negative argument level
, flattens all levels:
a = [ 0, [ 1, [2, 3], 4 ], 5 ]
a.flatten # => [0, 1, 2, 3, 4, 5]
[0, 1, 2].flatten # => [0, 1, 2]
a = [ 0, [ 1, [2, 3], 4 ], 5 ]
a.flatten(-1) # => [0, 1, 2, 3, 4, 5]
a = [ 0, [ 1, [2, 3], 4 ], 5 ]
a.flatten(-2) # => [0, 1, 2, 3, 4, 5]
[0, 1, 2].flatten(-1) # => [0, 1, 2]
# File 'array.c', line 6475
static VALUE rb_ary_flatten(int argc, VALUE *argv, VALUE ary) { int level = -1; VALUE result; if (rb_check_arity(argc, 0, 1) && !NIL_P(argv[0])) { level = NUM2INT(argv[0]); if (level == 0) return ary_make_shared_copy(ary); } result = flatten(ary, level); if (result == ary) { result = ary_make_shared_copy(ary); } return result; }
#flatten! ⇒ self
?
#flatten!(level) ⇒ self
?
self
?
#flatten!(level) ⇒ self
?
Replaces each nested Array in self
with the elements from that Array; returns self
if any changes, nil
otherwise.
With non-negative ::Integer
argument level
, flattens recursively through level
levels:
a = [ 0, [ 1, [2, 3], 4 ], 5 ]
a.flatten!(1) # => [0, 1, [2, 3], 4, 5]
a = [ 0, [ 1, [2, 3], 4 ], 5 ]
a.flatten!(2) # => [0, 1, 2, 3, 4, 5]
a = [ 0, [ 1, [2, 3], 4 ], 5 ]
a.flatten!(3) # => [0, 1, 2, 3, 4, 5]
[0, 1, 2].flatten!(1) # => nil
With no argument, a nil
argument, or with negative argument level
, flattens all levels:
a = [ 0, [ 1, [2, 3], 4 ], 5 ]
a.flatten! # => [0, 1, 2, 3, 4, 5]
[0, 1, 2].flatten! # => nil
a = [ 0, [ 1, [2, 3], 4 ], 5 ]
a.flatten!(-1) # => [0, 1, 2, 3, 4, 5]
a = [ 0, [ 1, [2, 3], 4 ], 5 ]
a.flatten!(-2) # => [0, 1, 2, 3, 4, 5]
[0, 1, 2].flatten!(-1) # => nil
# File 'array.c', line 6420
static VALUE rb_ary_flatten_bang(int argc, VALUE *argv, VALUE ary) { int mod = 0, level = -1; VALUE result, lv; lv = (rb_check_arity(argc, 0, 1) ? argv[0] : Qnil); rb_ary_modify_check(ary); if (!NIL_P(lv)) level = NUM2INT(lv); if (level == 0) return Qnil; result = flatten(ary, level); if (result == ary) { return Qnil; } if (!(mod = ARY_EMBED_P(result))) rb_obj_freeze(result); rb_ary_replace(ary, result); if (mod) ARY_SET_EMBED_LEN(result, 0); return ary; }
#hash ⇒ Integer
Returns the integer hash value for self
.
Two arrays with the same content will have the same hash code (and will compare using eql?):
[0, 1, 2].hash == [0, 1, 2].hash # => true
[0, 1, 2].hash == [0, 1, 3].hash # => false
# File 'array.c', line 5204
static VALUE rb_ary_hash(VALUE ary) { return rb_ary_hash_values(RARRAY_LEN(ary), RARRAY_CONST_PTR(ary)); }
#include?(obj) ⇒ Boolean
Returns true
if for some index i
in self
, obj == self[i]
; otherwise false
:
[0, 1, 2].include?(2) # => true
[0, 1, 2].include?(3) # => false
# File 'array.c', line 5221
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; }
Also known as: #find_index
Returns the index of a specified element.
When argument object
is given but no block, returns the index of the first element element
for which object == element
:
a = [:foo, 'bar', 2, 'bar']
a.index('bar') # => 1
Returns nil
if no such element found.
When both argument object
and a block are given, calls the block with each successive element; returns the index of the first element for which the block returns a truthy value:
a = [:foo, 'bar', 2, 'bar']
a.index {|element| element == 'bar' } # => 1
Returns nil
if the block never returns a truthy value.
When neither an argument nor a block is given, returns a new ::Enumerator
:
a = [:foo, 'bar', 2]
e = a.index
e # => #<Enumerator: [:foo, "bar", 2]:index>
e.each {|element| element == 'bar' } # => 1
Related: #rindex.
# File 'array.c', line 2025
static VALUE rb_ary_index(int argc, VALUE *argv, VALUE ary) { VALUE val; long i; if (argc == 0) { RETURN_ENUMERATOR(ary, 0, 0); for (i=0; i<RARRAY_LEN(ary); i++) { if (RTEST(rb_yield(RARRAY_AREF(ary, i)))) { return LONG2NUM(i); } } return Qnil; } rb_check_arity(argc, 0, 1); val = argv[0]; if (rb_block_given_p()) rb_warn("given block not used"); for (i=0; i<RARRAY_LEN(ary); i++) { VALUE e = RARRAY_AREF(ary, i); if (rb_equal(e, val)) { return LONG2NUM(i); } } return Qnil; }
#replace(other_array) ⇒ self
#initialize_copy(other_array) ⇒ self
self
#initialize_copy(other_array) ⇒ self
Alias for #replace.
#insert(index, *objects) ⇒ self
Inserts given objects
before or after the element at ::Integer
index offset
; returns self
.
When #index is non-negative, inserts all given objects
before the element at offset #index:
a = [:foo, 'bar', 2]
a.insert(1, :bat, :bam) # => [:foo, :bat, :bam, "bar", 2]
Extends the array if #index is beyond the array (index >= self.size
):
a = [:foo, 'bar', 2]
a.insert(5, :bat, :bam)
a # => [:foo, "bar", 2, nil, nil, :bat, :bam]
Does nothing if no objects given:
a = [:foo, 'bar', 2]
a.insert(1)
a.insert(50)
a.insert(-50)
a # => [:foo, "bar", 2]
When #index is negative, inserts all given objects
after the element at offset #indexself.size</tt>:
a = [:foo, 'bar', 2]
a.insert(-2, :bat, :bam)
a # => [:foo, "bar", :bat, :bam, 2]
# File 'array.c', line 2453
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; }
Alias for #to_s.
#intersect?(other_ary) ⇒ Boolean
# File 'array.c', line 5679
static VALUE rb_ary_intersect_p(VALUE ary1, VALUE ary2) { VALUE hash, v, result, shorter, longer; st_data_t vv; long i; ary2 = to_ary(ary2); if (RARRAY_LEN(ary1) == 0 || RARRAY_LEN(ary2) == 0) return Qfalse; 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)) return Qtrue; } return Qfalse; } shorter = ary1; longer = ary2; if (RARRAY_LEN(ary1) > RARRAY_LEN(ary2)) { longer = ary1; shorter = ary2; } hash = ary_make_hash(shorter); result = Qfalse; for (i=0; i<RARRAY_LEN(longer); i++) { v = RARRAY_AREF(longer, i); vv = (st_data_t)v; if (rb_hash_stlike_lookup(hash, vv, 0)) { result = Qtrue; break; } } return result; }
#intersection(*other_arrays) ⇒ Array
Returns a new Array containing each element found both in self
and in all of the given Arrays other_arrays
; duplicates are omitted; items are compared using #eql? (items must also implement #hash correctly):
[0, 1, 2, 3].intersection([0, 1, 2], [0, 1, 3]) # => [0, 1]
[0, 0, 1, 1, 2, 3].intersection([0, 1, 2], [0, 1, 3]) # => [0, 1]
Preserves order from self
:
[0, 1, 2].intersection([2, 1, 0]) # => [0, 1, 2]
Returns a copy of self
if no arguments given.
Related: #&.
# File 'array.c', line 5540
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
ifelement
is not akind_of?(Array)
. -
Uses recursive
element.join(separator)
ifelement
is akind_of?(Array)
.
With no argument, joins using the output field separator, $,
:
a = [:foo, 'bar', 2]
$, # => nil
a.join # => "foobar2"
With string argument separator
, joins using that separator:
a = [:foo, 'bar', 2]
a.join("\n") # => "foo\nbar\n2"
Joins recursively for nested Arrays:
a = [:foo, [:, [:baz, :bat]]]
a.join # => "foobarbazbat"
# File 'array.c', line 2872
static VALUE rb_ary_join_m(int argc, VALUE *argv, VALUE ary) { VALUE sep; if (rb_check_arity(argc, 0, 1) == 0 || NIL_P(sep = argv[0])) { sep = rb_output_fs; if (!NIL_P(sep)) { rb_category_warn(RB_WARN_CATEGORY_DEPRECATED, "$, is set to non-nil value"); } } return rb_ary_join(ary, sep); }
#keep_if {|element| ... } ⇒ self
#keep_if ⇒ new_enumeration
self
#keep_if ⇒ new_enumeration
Retains those elements for which the block returns a truthy value; deletes all other elements; returns self
:
a = [:foo, 'bar', 2, :bam]
a.keep_if {|element| element.to_s.start_with?('b') } # => ["bar", :bam]
Returns a new ::Enumerator
if no block given:
a = [:foo, 'bar', 2, :bam]
a.keep_if # => #<Enumerator: [:foo, "bar", 2, :bam]:keep_if>
# File 'array.c', line 3915
static VALUE rb_ary_keep_if(VALUE ary) { RETURN_SIZED_ENUMERATOR(ary, 0, 0, ary_enum_length); rb_ary_select_bang(ary); return ary; }
#last ⇒ Object?
#last(n) ⇒ Array
Array
Returns elements from self
; self
is not modified.
When no argument is given, returns the last element:
a = [:foo, 'bar', 2]
a.last # => 2
a # => [:foo, "bar", 2]
If self
is empty, returns nil
.
When non-negative ::Integer
argument n
is given, returns the last n
elements in a new Array:
a = [:foo, 'bar', 2]
a.last(2) # => ["bar", 2]
If n >= array.size
, returns all elements:
a = [:foo, 'bar', 2]
a.last(50) # => [:foo, "bar", 2]
If n == 0
, returns an new empty Array:
a = [:foo, 'bar', 2]
a.last(0) # []
Related: #first.
# File 'array.rb', line 145
def last n = unspecified = true if Primitive.mandatory_only? Primitive.attr! :leaf Primitive.cexpr! %q{ ary_last(self) } else if unspecified Primitive.cexpr! %q{ ary_last(self) } else Primitive.cexpr! %q{ ary_take_first_or_last_n(self, NUM2LONG(n), ARY_TAKE_LAST) } end end end
#length ⇒ Integer Also known as: #size
Returns the count of elements in self
.
# File 'array.c', line 2670
static VALUE rb_ary_length(VALUE ary) { long len = RARRAY_LEN(ary); return LONG2NUM(len); }
#map {|element| ... } ⇒ Array
#map ⇒ Enumerator
Also known as: #collect
Array
#map ⇒ Enumerator
Calls the block, if given, with each element of self
; returns a new Array whose elements are the return values from the block:
a = [:foo, 'bar', 2]
a1 = a.map {|element| element.class }
a1 # => [Symbol, String, Integer]
Returns a new ::Enumerator
if no block given:
a = [:foo, 'bar', 2]
a1 = a.map
a1 # => #<Enumerator: [:foo, "bar", 2]:map>
# File 'array.c', line 3624
static VALUE rb_ary_collect(VALUE ary) { long i; VALUE collect; RETURN_SIZED_ENUMERATOR(ary, 0, 0, ary_enum_length); collect = rb_ary_new2(RARRAY_LEN(ary)); for (i = 0; i < RARRAY_LEN(ary); i++) { rb_ary_push(collect, rb_yield(RARRAY_AREF(ary, i))); } return collect; }
#map! {|element| ... } ⇒ self
#map! ⇒ Enumerator
Also known as: #collect!
self
#map! ⇒ Enumerator
Calls the block, if given, with each element; replaces the element with the block’s return value:
a = [:foo, 'bar', 2]
a.map! { |element| element.class } # => [Symbol, String, Integer]
Returns a new ::Enumerator
if no block given:
a = [:foo, 'bar', 2]
a1 = a.map!
a1 # => #<Enumerator: [:foo, "bar", 2]:map!>
# File 'array.c', line 3658
static VALUE rb_ary_collect_bang(VALUE ary) { long i; RETURN_SIZED_ENUMERATOR(ary, 0, 0, ary_enum_length); rb_ary_modify(ary); for (i = 0; i < RARRAY_LEN(ary); i++) { rb_ary_store(ary, i, rb_yield(RARRAY_AREF(ary, i))); } return ary; }
#max ⇒ element
#max {|a, b| ... } ⇒ element
#max(n) ⇒ Array
#max(n) {|a, b| ... } ⇒ Array
element
#max {|a, b| ... } ⇒ element
#max(n) ⇒ Array
#max(n) {|a, b| ... } ⇒ Array
Returns one of the following:
-
The maximum-valued element from
self
. -
A new Array of maximum-valued elements selected from
self
.
When no block is given, each element in self
must respond to method #<=> with an ::Integer
.
With no argument and no block, returns the element in self
having the maximum value per method #<=>:
[0, 1, 2].max # => 2
With an argument ::Integer
n
and no block, returns a new Array with at most n
elements, in descending order per method #<=>:
[0, 1, 2, 3].max(3) # => [3, 2, 1]
[0, 1, 2, 3].max(6) # => [3, 2, 1, 0]
When a block is given, the block must return an ::Integer
.
With a block and no argument, calls the block self.size-1
times to compare elements; returns the element having the maximum value per the block:
['0', '00', '000'].max {|a, b| a.size <=> b.size } # => "000"
With an argument n
and a block, returns a new Array with at most n
elements, in descending order per the block:
['0', '00', '000'].max(2) {|a, b| a.size <=> b.size } # => ["000", "00"]
# File 'array.c', line 5847
static VALUE rb_ary_max(int argc, VALUE *argv, VALUE ary) { VALUE result = Qundef, v; VALUE num; long i; if (rb_check_arity(argc, 0, 1) && !NIL_P(num = argv[0])) return rb_nmin_run(ary, num, 0, 1, 1); const long n = RARRAY_LEN(ary); if (rb_block_given_p()) { for (i = 0; i < RARRAY_LEN(ary); i++) { v = RARRAY_AREF(ary, i); if (UNDEF_P(result) || rb_cmpint(rb_yield_values(2, v, result), v, result) > 0) { result = v; } } } else if (n > 0) { result = RARRAY_AREF(ary, 0); if (n > 1) { if (FIXNUM_P(result) && CMP_OPTIMIZABLE(INTEGER)) { return ary_max_opt_fixnum(ary, 1, result); } else if (STRING_P(result) && CMP_OPTIMIZABLE(STRING)) { return ary_max_opt_string(ary, 1, result); } else if (RB_FLOAT_TYPE_P(result) && CMP_OPTIMIZABLE(FLOAT)) { return ary_max_opt_float(ary, 1, result); } else { return ary_max_generic(ary, 1, result); } } } if (UNDEF_P(result)) return Qnil; return result; }
#min ⇒ element
#min {|a, b| ... } ⇒ element
#min(n) ⇒ Array
#min(n) {|a, b| ... } ⇒ Array
element
#min {|a, b| ... } ⇒ element
#min(n) ⇒ Array
#min(n) {|a, b| ... } ⇒ Array
Returns one of the following:
-
The minimum-valued element from
self
. -
A new Array of minimum-valued elements selected from
self
.
When no block is given, each element in self
must respond to method #<=> with an ::Integer
.
With no argument and no block, returns the element in self
having the minimum value per method #<=>:
[0, 1, 2].min # => 0
With Integer argument n
and no block, returns a new Array with at most n
elements, in ascending order per method #<=>:
[0, 1, 2, 3].min(3) # => [0, 1, 2]
[0, 1, 2, 3].min(6) # => [0, 1, 2, 3]
When a block is given, the block must return an ::Integer
.
With a block and no argument, calls the block self.size-1
times to compare elements; returns the element having the minimum value per the block:
['0', '00', '000'].min { |a, b| a.size <=> b.size } # => "0"
With an argument n
and a block, returns a new Array with at most n
elements, in ascending order per the block:
['0', '00', '000'].min(2) {|a, b| a.size <=> b.size } # => ["0", "00"]
# File 'array.c', line 6015
static VALUE rb_ary_min(int argc, VALUE *argv, VALUE ary) { VALUE result = Qundef, v; VALUE num; long i; if (rb_check_arity(argc, 0, 1) && !NIL_P(num = argv[0])) return rb_nmin_run(ary, num, 0, 0, 1); const long n = RARRAY_LEN(ary); if (rb_block_given_p()) { for (i = 0; i < RARRAY_LEN(ary); i++) { v = RARRAY_AREF(ary, i); if (UNDEF_P(result) || rb_cmpint(rb_yield_values(2, v, result), v, result) < 0) { result = v; } } } else if (n > 0) { result = RARRAY_AREF(ary, 0); if (n > 1) { if (FIXNUM_P(result) && CMP_OPTIMIZABLE(INTEGER)) { return ary_min_opt_fixnum(ary, 1, result); } else if (STRING_P(result) && CMP_OPTIMIZABLE(STRING)) { return ary_min_opt_string(ary, 1, result); } else if (RB_FLOAT_TYPE_P(result) && CMP_OPTIMIZABLE(FLOAT)) { return ary_min_opt_float(ary, 1, result); } else { return ary_min_generic(ary, 1, result); } } } if (UNDEF_P(result)) return Qnil; return result; }
#minmax ⇒ Array
, max_val
#minmax {|a, b| ... } ⇒ Array
, max_val
Array
, max_val
#minmax {|a, b| ... } ⇒ Array
, max_val
Returns a new 2-element Array containing the minimum and maximum values from self
, either per method #<=> or per a given block:.
When no block is given, each element in self
must respond to method #<=> with an Integer; returns a new 2-element Array containing the minimum and maximum values from self
, per method #<=>:
[0, 1, 2].minmax # => [0, 2]
When a block is given, the block must return an Integer; the block is called self.size-1
times to compare elements; returns a new 2-element Array containing the minimum and maximum values from self
, per the block:
['0', '00', '000'].minmax {|a, b| a.size <=> b.size } # => ["0", "000"]
# File 'array.c', line 6078
static VALUE rb_ary_minmax(VALUE ary) { if (rb_block_given_p()) { return rb_call_super(0, NULL); } return rb_assoc_new(rb_ary_min(0, 0, ary), rb_ary_max(0, 0, ary)); }
#none? ⇒ Boolean
#none? {|element| ... } ⇒ Boolean
#none?(obj) ⇒ Boolean
Boolean
#none? {|element| ... } ⇒ Boolean
#none?(obj) ⇒ Boolean
Returns true
if no element of self
meet a given criterion.
With no block given and no argument, returns true
if self
has no truthy elements, false
otherwise:
[nil, false].none? # => true
[nil, 0, false].none? # => false
[].none? # => true
With a block given and no argument, calls the block with each element in self
; returns true
if the block returns no truthy value, false
otherwise:
[0, 1, 2].none? {|element| element > 3 } # => true
[0, 1, 2].none? {|element| element > 1 } # => false
If argument obj
is given, returns true
if obj.===
no element, false
otherwise:
['food', 'drink'].none?(/bar/) # => true
['food', 'drink'].none?(/foo/) # => false
[].none?(/foo/) # => true
[0, 1, 2].none?(3) # => true
[0, 1, 2].none?(1) # => false
Related: Enumerable#none?
# File 'array.c', line 7799
static VALUE rb_ary_none_p(int argc, VALUE *argv, VALUE ary) { long i, len = RARRAY_LEN(ary); rb_check_arity(argc, 0, 1); if (!len) return Qtrue; if (argc) { if (rb_block_given_p()) { rb_warn("given block not used"); } for (i = 0; i < RARRAY_LEN(ary); ++i) { if (RTEST(rb_funcall(argv[0], idEqq, 1, RARRAY_AREF(ary, i)))) return Qfalse; } } else if (!rb_block_given_p()) { for (i = 0; i < len; ++i) { if (RTEST(RARRAY_AREF(ary, i))) return Qfalse; } } else { for (i = 0; i < RARRAY_LEN(ary); ++i) { if (RTEST(rb_yield(RARRAY_AREF(ary, i)))) return Qfalse; } } return Qtrue; }
#one? ⇒ Boolean
#one? {|element| ... } ⇒ Boolean
#one?(obj) ⇒ Boolean
Boolean
#one? {|element| ... } ⇒ Boolean
#one?(obj) ⇒ Boolean
Returns true
if exactly one element of self
meets a given criterion.
With no block given and no argument, returns true
if self
has exactly one truthy element, false
otherwise:
[nil, 0].one? # => true
[0, 0].one? # => false
[nil, nil].one? # => false
[].one? # => false
With a block given and no argument, calls the block with each element in self
; returns true
if the block a truthy value for exactly one element, false
otherwise:
[0, 1, 2].one? {|element| element > 0 } # => false
[0, 1, 2].one? {|element| element > 1 } # => true
[0, 1, 2].one? {|element| element > 2 } # => false
If argument obj
is given, returns true
if obj.===
exactly one element, false
otherwise:
[0, 1, 2].one?(0) # => true
[0, 0, 1].one?(0) # => false
[1, 1, 2].one?(0) # => false
['food', 'drink'].one?(/bar/) # => false
['food', 'drink'].one?(/foo/) # => true
[].one?(/foo/) # => false
Related: Enumerable#one?
# File 'array.c', line 7863
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(template, buffer: nil) ⇒ String
Formats each element in self
into a binary string; returns that string. See Packed Data
.
# File 'pack.rb', line 7
def pack(fmt, buffer: nil) Primitive.pack_pack(fmt, buffer) end
#permutation {|element| ... } ⇒ self
#permutation(n) {|element| ... } ⇒ self
#permutation ⇒ Enumerator
#permutation(n) ⇒ Enumerator
self
#permutation(n) {|element| ... } ⇒ self
#permutation ⇒ Enumerator
#permutation(n) ⇒ Enumerator
When invoked with a block, yield all permutations of elements of self
; returns self
. The order of permutations is indeterminate.
When a block and an in-range positive ::Integer
argument n
(0 < n <= self.size
) are given, calls the block with all n
-tuple permutations of self
.
Example:
a = [0, 1, 2]
a.permutation(2) {|permutation| p permutation }
Output:
[0, 1]
[0, 2]
[1, 0]
[1, 2]
[2, 0]
[2, 1]
Another example:
a = [0, 1, 2]
a.permutation(3) {|permutation| p permutation }
Output:
[0, 1, 2]
[0, 2, 1]
[1, 0, 2]
[1, 2, 0]
[2, 0, 1]
[2, 1, 0]
When n
is zero, calls the block once with a new empty Array:
a = [0, 1, 2]
a.permutation(0) {|permutation| p permutation }
Output:
[]
When n
is out of range (negative or larger than self.size
), does not call the block:
a = [0, 1, 2]
a.permutation(-1) {|permutation| fail 'Cannot happen' }
a.permutation(4) {|permutation| fail 'Cannot happen' }
When a block given but no argument, behaves the same as a.permutation(a.size)
:
a = [0, 1, 2]
a.permutation {|permutation| p permutation }
Output:
[0, 1, 2]
[0, 2, 1]
[1, 0, 2]
[1, 2, 0]
[2, 0, 1]
[2, 1, 0]
Returns a new ::Enumerator
if no block given:
a = [0, 1, 2]
a.permutation # => #<Enumerator: [0, 1, 2]:permutation>
a.permutation(2) # => #<Enumerator: [0, 1, 2]:permutation(2)>
# File 'array.c', line 6931
static VALUE rb_ary_permutation(int argc, VALUE *argv, VALUE ary) { long r, n, i; n = RARRAY_LEN(ary); /* Array length */ RETURN_SIZED_ENUMERATOR(ary, argc, argv, rb_ary_permutation_size); /* Return enumerator if no block */ r = n; if (rb_check_arity(argc, 0, 1) && !NIL_P(argv[0])) r = NUM2LONG(argv[0]); /* Permutation size from argument */ if (r < 0 || n < r) { /* no permutations: yield nothing */ } else if (r == 0) { /* exactly one permutation: the zero-length array */ rb_yield(rb_ary_new2(0)); } else if (r == 1) { /* this is a special, easy case */ for (i = 0; i < RARRAY_LEN(ary); i++) { rb_yield(rb_ary_new3(1, RARRAY_AREF(ary, i))); } } else { /* this is the general case */ volatile VALUE t0; long *p = ALLOCV_N(long, t0, r+roomof(n, sizeof(long))); char *used = (char*)(p + r); VALUE ary0 = ary_make_shared_copy(ary); /* private defensive copy of ary */ RBASIC_CLEAR_CLASS(ary0); MEMZERO(used, char, n); /* initialize array */ permute0(n, r, p, used, ary0); /* compute and yield permutations */ ALLOCV_END(t0); RBASIC_SET_CLASS_RAW(ary0, rb_cArray); } return ary; }
#pop ⇒ Object?
#pop(n) ⇒ Array
Array
Removes and returns trailing elements.
When no argument is given and self
is not empty, removes and returns the last element:
a = [:foo, 'bar', 2]
a.pop # => 2
a # => [:foo, "bar"]
Returns nil
if the array is empty.
When a non-negative ::Integer
argument n
is given and is in range,
removes and returns the last n
elements in a new Array:
a = [:foo, 'bar', 2]
a.pop(2) # => ["bar", 2]
If n
is positive and out of range, removes and returns all elements:
a = [:foo, 'bar', 2]
a.pop(50) # => [:foo, "bar", 2]
# File 'array.c', line 1436
static VALUE rb_ary_pop_m(int argc, VALUE *argv, VALUE ary) { VALUE result; if (argc == 0) { return rb_ary_pop(ary); } rb_ary_modify_check(ary); result = ary_take_first_or_last(argc, argv, ary, ARY_TAKE_LAST); ARY_INCREASE_LEN(ary, -RARRAY_LEN(result)); ary_verify(ary); return result; }
#prepend(*objects) ⇒ self
Also known as: #unshift
# File 'array.c', line 1651
VALUE rb_ary_unshift_m(int argc, VALUE *argv, VALUE ary) { long len = RARRAY_LEN(ary); VALUE target_ary; if (argc == 0) { rb_ary_modify_check(ary); return ary; } target_ary = ary_ensure_room_for_unshift(ary, argc); ary_memcpy0(ary, 0, argc, argv, target_ary); ARY_SET_LEN(ary, len + argc); return ary; }
#product(*other_arrays) ⇒ Array
#product(*other_arrays) {|combination| ... } ⇒ self
Array
#product(*other_arrays) {|combination| ... } ⇒ self
Computes and returns or yields all combinations of elements from all the Arrays, including both self
and other_arrays
:
-
The number of combinations is the product of the sizes of all the arrays, including both
self
andother_arrays
. -
The order of the returned combinations is indeterminate.
When no block is given, returns the combinations as an Array of Arrays:
a = [0, 1, 2]
a1 = [3, 4]
a2 = [5, 6]
p = a.product(a1)
p.size # => 6 # a.size * a1.size
p # => [[0, 3], [0, 4], [1, 3], [1, 4], [2, 3], [2, 4]]
p = a.product(a1, a2)
p.size # => 12 # a.size * a1.size * a2.size
p # => [[0, 3, 5], [0, 3, 6], [0, 4, 5], [0, 4, 6], [1, 3, 5], [1, 3, 6], [1, 4, 5], [1, 4, 6], [2, 3, 5], [2, 3, 6], [2, 4, 5], [2, 4, 6]]
If any argument is an empty Array, returns an empty Array.
If no argument is given, returns an Array of 1-element Arrays, each containing an element of self
:
a.product # => [[0], [1], [2]]
When a block is given, yields each combination as an Array; returns self
:
a.product(a1) {|combination| p combination }
Output:
[0, 3]
[0, 4]
[1, 3]
[1, 4]
[2, 3]
[2, 4]
If any argument is an empty Array, does not call the block:
a.product(a1, a2, []) {|combination| fail 'Cannot happen' }
If no argument is given, yields each element of self
as a 1-element Array:
a.product {|combination| p combination }
Output:
[0]
[1]
[2]
# File 'array.c', line 7425
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 = rb_ary_hidden_new(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, RARRAY_SHARED_ROOT_FLAG); rb_yield(subarray); if (!FL_TEST(t0, RARRAY_SHARED_ROOT_FLAG)) { rb_raise(rb_eRuntimeError, "product reentered"); } else { FL_UNSET(t0, RARRAY_SHARED_ROOT_FLAG); } } 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: ALLOCV_END(t1); return NIL_P(result) ? ary : result; }
#push(*objects) ⇒ self
Also known as: #append
Appends trailing elements.
Appends each argument in objects
to self
; returns self
:
a = [:foo, 'bar', 2]
a.push(:baz, :bat) # => [:foo, "bar", 2, :baz, :bat]
Appends each argument as one element, even if it is another Array:
a = [:foo, 'bar', 2]
a1 = a.push([:baz, :bat], [:bam, :bad])
a1 # => [:foo, "bar", 2, [:baz, :bat], [:bam, :bad]]
# File 'array.c', line 1380
static VALUE rb_ary_push_m(int argc, VALUE *argv, VALUE ary) { return rb_ary_cat(ary, argv, argc); }
#rassoc(obj) ⇒ Array
?
# File 'array.c', line 5051
VALUE rb_ary_rassoc(VALUE ary, VALUE value) { long i; VALUE v; for (i = 0; i < RARRAY_LEN(ary); ++i) { v = rb_check_array_type(RARRAY_AREF(ary, i)); if (RB_TYPE_P(v, T_ARRAY) && RARRAY_LEN(v) > 1 && rb_equal(RARRAY_AREF(v, 1), value)) return v; } return Qnil; }
#reject {|element| ... } ⇒ Array
#reject ⇒ Enumerator
Array
#reject ⇒ Enumerator
Returns a new Array whose elements are all those from self
for which the block returns false
or nil
:
a = [:foo, 'bar', 2, 'bat']
a1 = a.reject {|element| element.to_s.start_with?('b') }
a1 # => [:foo, 2]
Returns a new ::Enumerator
if no block given:
a = [:foo, 'bar', 2]
a.reject # => #<Enumerator: [:foo, "bar", 2]:reject>
# File 'array.c', line 4300
static VALUE rb_ary_reject(VALUE ary) { VALUE rejected_ary; RETURN_SIZED_ENUMERATOR(ary, 0, 0, ary_enum_length); rejected_ary = rb_ary_new(); ary_reject(ary, rejected_ary); return rejected_ary; }
#reject! {|element| ... } ⇒ self
?
#reject! ⇒ Enumerator
self
?
#reject! ⇒ Enumerator
Removes each element for which the block returns a truthy value.
Returns self
if any elements removed:
a = [:foo, 'bar', 2, 'bat']
a.reject! {|element| element.to_s.start_with?('b') } # => [:foo, 2]
Returns nil
if no elements removed.
Returns a new ::Enumerator
if no block given:
a = [:foo, 'bar', 2]
a.reject! # => #<Enumerator: [:foo, "bar", 2]:reject!>
# File 'array.c', line 4273
static VALUE rb_ary_reject_bang(VALUE ary) { RETURN_SIZED_ENUMERATOR(ary, 0, 0, ary_enum_length); rb_ary_modify(ary); return ary_reject_bang(ary); }
#repeated_combination(n) {|combination| ... } ⇒ self
#repeated_combination(n) ⇒ Enumerator
self
#repeated_combination(n) ⇒ Enumerator
Calls the block with each repeated combination of length n
of the elements of self
; each combination is an Array; returns self
. The order of the combinations is indeterminate.
When a block and a positive ::Integer
argument n
are given, calls the block with each n
-tuple repeated combination of the elements of self
. The number of combinations is (n+1)(n+2)/2
.
n
= 1:
a = [0, 1, 2]
a.repeated_combination(1) {|combination| p combination }
Output:
[0]
[1]
[2]
n
= 2:
a.repeated_combination(2) {|combination| p combination }
Output:
[0, 0]
[0, 1]
[0, 2]
[1, 1]
[1, 2]
[2, 2]
If n
is zero, calls the block once with an empty Array.
If n
is negative, does not call the block:
a.repeated_combination(-1) {|combination| fail 'Cannot happen' }
Returns a new ::Enumerator
if no block given:
a = [0, 1, 2]
a.repeated_combination(2) # => #<Enumerator: [0, 1, 2]:combination(2)>
Using Enumerators, it’s convenient to show the combinations and counts for some values of n
:
e = a.repeated_combination(0)
e.size # => 1
e.to_a # => [[]]
e = a.repeated_combination(1)
e.size # => 3
e.to_a # => [[0], [1], [2]]
e = a.repeated_combination(2)
e.size # => 6
e.to_a # => [[0, 0], [0, 1], [0, 2], [1, 1], [1, 2], [2, 2]]
# File 'array.c', line 7330
static VALUE rb_ary_repeated_combination(VALUE ary, VALUE num) { long n, i, len; n = NUM2LONG(num); /* Combination size from argument */ RETURN_SIZED_ENUMERATOR(ary, 1, &num, rb_ary_repeated_combination_size); /* Return enumerator if no block */ len = RARRAY_LEN(ary); if (n < 0) { /* yield nothing */ } else if (n == 0) { rb_yield(rb_ary_new2(0)); } else if (n == 1) { for (i = 0; i < RARRAY_LEN(ary); i++) { rb_yield(rb_ary_new3(1, RARRAY_AREF(ary, i))); } } else if (len == 0) { /* yield nothing */ } else { volatile VALUE t0; long *p = ALLOCV_N(long, t0, n); VALUE ary0 = ary_make_shared_copy(ary); /* private defensive copy of ary */ RBASIC_CLEAR_CLASS(ary0); rcombinate0(len, n, p, n, ary0); /* compute and yield repeated combinations */ ALLOCV_END(t0); RBASIC_SET_CLASS_RAW(ary0, rb_cArray); } return ary; }
#repeated_permutation(n) {|permutation| ... } ⇒ self
#repeated_permutation(n) ⇒ Enumerator
self
#repeated_permutation(n) ⇒ Enumerator
Calls the block with each repeated permutation of length n
of the elements of self
; each permutation is an Array; returns self
. The order of the permutations is indeterminate.
When a block and a positive ::Integer
argument n
are given, calls the block with each n
-tuple repeated permutation of the elements of self
. The number of permutations is self.size**n
.
n
= 1:
a = [0, 1, 2]
a.repeated_permutation(1) {|permutation| p permutation }
Output:
[0]
[1]
[2]
n
= 2:
a.repeated_permutation(2) {|permutation| p permutation }
Output:
[0, 0]
[0, 1]
[0, 2]
[1, 0]
[1, 1]
[1, 2]
[2, 0]
[2, 1]
[2, 2]
If n
is zero, calls the block once with an empty Array.
If n
is negative, does not call the block:
a.repeated_permutation(-1) {|permutation| fail 'Cannot happen' }
Returns a new ::Enumerator
if no block given:
a = [0, 1, 2]
a.repeated_permutation(2) # => #<Enumerator: [0, 1, 2]:permutation(2)>
Using Enumerators, it’s convenient to show the permutations and counts for some values of n
:
e = a.repeated_permutation(0)
e.size # => 1
e.to_a # => [[]]
e = a.repeated_permutation(1)
e.size # => 3
e.to_a # => [[0], [1], [2]]
e = a.repeated_permutation(2)
e.size # => 9
e.to_a # => [[0, 0], [0, 1], [0, 2], [1, 0], [1, 1], [1, 2], [2, 0], [2, 1], [2, 2]]
# File 'array.c', line 7200
static VALUE rb_ary_repeated_permutation(VALUE ary, VALUE num) { long r, n, i; n = RARRAY_LEN(ary); /* Array length */ RETURN_SIZED_ENUMERATOR(ary, 1, &num, rb_ary_repeated_permutation_size); /* Return Enumerator if no block */ r = NUM2LONG(num); /* Permutation size from argument */ if (r < 0) { /* no permutations: yield nothing */ } else if (r == 0) { /* exactly one permutation: the zero-length array */ rb_yield(rb_ary_new2(0)); } else if (r == 1) { /* this is a special, easy case */ for (i = 0; i < RARRAY_LEN(ary); i++) { rb_yield(rb_ary_new3(1, RARRAY_AREF(ary, i))); } } else { /* this is the general case */ volatile VALUE t0; long *p = ALLOCV_N(long, t0, r); VALUE ary0 = ary_make_shared_copy(ary); /* private defensive copy of ary */ RBASIC_CLEAR_CLASS(ary0); rpermute0(n, r, p, ary0); /* compute and yield repeated permutations */ ALLOCV_END(t0); RBASIC_SET_CLASS_RAW(ary0, rb_cArray); } return ary; }
#replace(other_array) ⇒ self
Also known as: #initialize_copy
Replaces the content of self
with the content of other_array
; returns self
:
a = [:foo, 'bar', 2]
a.replace(['foo', :, 3]) # => ["foo", :bar, 3]
# File 'array.c', line 4530
VALUE rb_ary_replace(VALUE copy, VALUE orig) { rb_ary_modify_check(copy); orig = to_ary(orig); if (copy == orig) return copy; rb_ary_reset(copy); /* orig has enough space to embed the contents of orig. */ if (RARRAY_LEN(orig) <= ary_embed_capa(copy)) { assert(ARY_EMBED_P(copy)); ary_memcpy(copy, 0, RARRAY_LEN(orig), RARRAY_CONST_PTR(orig)); ARY_SET_EMBED_LEN(copy, RARRAY_LEN(orig)); } /* orig is embedded but copy does not have enough space to embed the * contents of orig. */ else if (ARY_EMBED_P(orig)) { long len = ARY_EMBED_LEN(orig); VALUE *ptr = ary_heap_alloc(len); FL_UNSET_EMBED(copy); ARY_SET_PTR(copy, ptr); ARY_SET_LEN(copy, len); ARY_SET_CAPA(copy, len); // No allocation and exception expected that could leave `copy` in a // bad state from the edits above. ary_memcpy(copy, 0, len, RARRAY_CONST_PTR(orig)); } /* Otherwise, orig is on heap and copy does not have enough space to embed * the contents of orig. */ else { VALUE shared_root = ary_make_shared(orig); FL_UNSET_EMBED(copy); ARY_SET_PTR(copy, ARY_HEAP_PTR(orig)); ARY_SET_LEN(copy, ARY_HEAP_LEN(orig)); rb_ary_set_shared(copy, shared_root); } ary_verify(copy); return copy; }
#reverse ⇒ Array
Returns a new Array with the elements of self
in reverse order:
a = ['foo', 'bar', 'two']
a1 = a.reverse
a1 # => ["two", "bar", "foo"]
# File 'array.c', line 3079
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(ary); VALUE *p2 = (VALUE *)RARRAY_CONST_PTR(dup) + len - 1; do *p2-- = *p1++; while (--len > 0); } ARY_SET_LEN(dup, RARRAY_LEN(ary)); return dup; }
#reverse! ⇒ self
Reverses self
in place:
a = ['foo', 'bar', 'two']
a.reverse! # => ["two", "bar", "foo"]
# File 'array.c', line 3061
static VALUE rb_ary_reverse_bang(VALUE ary) { return rb_ary_reverse(ary); }
#reverse_each {|element| ... } ⇒ self
#reverse_each ⇒ Enumerator
self
#reverse_each ⇒ Enumerator
Iterates backwards over array elements.
When a block given, passes, in reverse order, each element to the block; returns self
:
a = [:foo, 'bar', 2]
a.reverse_each {|element| puts "#{element.class} #{element}" }
Output:
Integer 2
String
Symbol foo
Allows the array to be modified during iteration:
a = [:foo, 'bar', 2]
a.reverse_each {|element| puts element; a.clear if element.to_s.start_with?('b') }
Output:
2
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
Symbol foo
Related: #each, #each_index.
# File 'array.c', line 2645
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; }
Returns the index of the last element for which object == element
.
When argument object
is given but no block, returns the index of the last such element found:
a = [:foo, 'bar', 2, 'bar']
a.rindex('bar') # => 3
Returns nil
if no such object found.
When a block is given but no argument, calls the block with each successive element; returns the index of the last element for which the block returns a truthy value:
a = [:foo, 'bar', 2, 'bar']
a.rindex {|element| element == 'bar' } # => 3
Returns nil
if the block never returns a truthy value.
When neither an argument nor a block is given, returns a new ::Enumerator
:
a = [:foo, 'bar', 2, 'bar']
e = a.rindex
e # => #<Enumerator: [:foo, "bar", 2, "bar"]:rindex>
e.each {|element| element == 'bar' } # => 3
Related: #index.
# File 'array.c', line 2086
static VALUE rb_ary_rindex(int argc, VALUE *argv, VALUE ary) { VALUE val; long i = RARRAY_LEN(ary), len; if (argc == 0) { RETURN_ENUMERATOR(ary, 0, 0); while (i--) { if (RTEST(rb_yield(RARRAY_AREF(ary, i)))) return LONG2NUM(i); if (i > (len = RARRAY_LEN(ary))) { i = len; } } return Qnil; } rb_check_arity(argc, 0, 1); val = argv[0]; if (rb_block_given_p()) rb_warn("given block not used"); while (i--) { VALUE e = RARRAY_AREF(ary, i); if (rb_equal(e, val)) { return LONG2NUM(i); } if (i > RARRAY_LEN(ary)) { break; } } return Qnil; }
#rotate ⇒ Array
#rotate(count) ⇒ Array
Array
#rotate(count) ⇒ Array
Returns a new Array formed from self
with elements rotated from one end to the other.
When no argument given, returns a new Array that is like self
, except that the first element has been rotated to the last position:
a = [:foo, 'bar', 2, 'bar']
a1 = a.rotate
a1 # => ["bar", 2, "bar", :foo]
When given a non-negative ::Integer
#count, returns a new Array with #count elements rotated from the beginning to the end:
a = [:foo, 'bar', 2]
a1 = a.rotate(2)
a1 # => [2, :foo, "bar"]
If #count is large, uses count % array.size
as the count:
a = [:foo, 'bar', 2]
a1 = a.rotate(20)
a1 # => [2, :foo, "bar"]
If #count is zero, returns a copy of self
, unmodified:
a = [:foo, 'bar', 2]
a1 = a.rotate(0)
a1 # => [:foo, "bar", 2]
When given a negative ::Integer
#count, rotates in the opposite direction, from end to beginning:
a = [:foo, 'bar', 2]
a1 = a.rotate(-2)
a1 # => ["bar", 2, :foo]
If #count is small (far from zero), uses count % array.size
as the count:
a = [:foo, 'bar', 2]
a1 = a.rotate(-5)
a1 # => ["bar", 2, :foo]
# File 'array.c', line 3239
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(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
self
#rotate!(count) ⇒ self
Rotates self
in place by moving elements from one end to the other; returns self
.
When no argument given, rotates the first element to the last position:
a = [:foo, 'bar', 2, 'bar']
a.rotate! # => ["bar", 2, "bar", :foo]
When given a non-negative ::Integer
#count, rotates #count elements from the beginning to the end:
a = [:foo, 'bar', 2]
a.rotate!(2)
a # => [2, :foo, "bar"]
If #count is large, uses count % array.size
as the count:
a = [:foo, 'bar', 2]
a.rotate!(20)
a # => [2, :foo, "bar"]
If #count is zero, returns self
unmodified:
a = [:foo, 'bar', 2]
a.rotate!(0)
a # => [:foo, "bar", 2]
When given a negative ::Integer
#count, rotates in the opposite direction, from end to beginning:
a = [:foo, 'bar', 2]
a.rotate!(-2)
a # => ["bar", 2, :foo]
If #count is small (far from zero), uses count % array.size
as the count:
a = [:foo, 'bar', 2]
a.rotate!(-5)
a # => ["bar", 2, :foo]
# File 'array.c', line 3182
static VALUE rb_ary_rotate_bang(int argc, VALUE *argv, VALUE ary) { long n = (rb_check_arity(argc, 0, 1) ? NUM2LONG(argv[0]) : 1); rb_ary_rotate(ary, n); return ary; }
#sample(random: Random) ⇒ Object
#sample(n, random: Random) ⇒ Array
Array
Returns random elements from self
.
When no arguments are given, returns a random element from self
:
a = [1, 2, 3, 4, 5, 6, 7, 8, 9, 10]
a.sample # => 3
a.sample # => 8
If self
is empty, returns nil
.
When argument n
is given, returns a new Array containing n
random elements from self
:
a.sample(3) # => [8, 9, 2]
a.sample(6) # => [9, 6, 10, 3, 1, 4]
Returns no more than a.size
elements (because no new duplicates are introduced):
a.sample(a.size * 2) # => [6, 4, 1, 8, 5, 9, 10, 2, 3, 7]
But self
may contain duplicates:
a = [1, 1, 1, 2, 2, 3]
a.sample(a.size * 2) # => [1, 1, 3, 2, 1, 2]
The argument n
must be a non-negative numeric value. The order of the result array is unrelated to the order of self
. Returns a new empty Array if self
is empty.
The optional random
argument will be used as the random number generator:
a = [1, 2, 3, 4, 5, 6, 7, 8, 9, 10]
a.sample(random: Random.new(1)) #=> 6
a.sample(4, random: Random.new(1)) #=> [6, 10, 9, 2]
# File 'array.rb', line 60
def sample(n = (ary = false), random: Random) if Primitive.mandatory_only? # Primitive.cexpr! %{ rb_ary_sample(self, rb_cRandom, Qfalse, Qfalse) } Primitive.ary_sample0 else # Primitive.cexpr! %{ rb_ary_sample(self, random, n, ary) } Primitive.ary_sample(random, n, ary) end end
#select {|element| ... } ⇒ Array
#select ⇒ Enumerator
Array
#select ⇒ Enumerator
Alias for #filter.
#select! {|element| ... } ⇒ self
?
#select! ⇒ Enumerator
self
?
#select! ⇒ Enumerator
Alias for #filter!.
#shift ⇒ Object?
#shift(n) ⇒ Array
Array
Removes and returns leading elements.
When no argument is given, removes and returns the first element:
a = [:foo, 'bar', 2]
a.shift # => :foo
a # => ['bar', 2]
Returns nil
if self
is empty.
When positive ::Integer
argument n
is given, removes the first n
elements; returns those elements in a new Array:
a = [:foo, 'bar', 2]
a.shift(2) # => [:foo, 'bar']
a # => [2]
If n
is as large as or larger than self.length
, removes all elements; returns those elements in a new Array:
a = [:foo, 'bar', 2]
a.shift(3) # => [:foo, 'bar', 2]
If n
is zero, returns a new empty Array; self
is unmodified.
# File 'array.c', line 1503
static VALUE rb_ary_shift_m(int argc, VALUE *argv, VALUE ary) { VALUE result; long n; if (argc == 0) { return rb_ary_shift(ary); } rb_ary_modify_check(ary); result = ary_take_first_or_last(argc, argv, ary, ARY_TAKE_FIRST); n = RARRAY_LEN(result); rb_ary_behead(ary,n); return result; }
#shuffle(random: Random) ⇒ Array
# File 'array.rb', line 26
def shuffle(random: Random) Primitive.rb_ary_shuffle(random) end
#shuffle!(random: Random) ⇒ Array
# File 'array.rb', line 12
def shuffle!(random: Random) Primitive.rb_ary_shuffle_bang(random) end
Alias for #length.
Alias for #[].
Removes and returns elements from self
.
When the only argument is an ::Integer
n
, removes and returns the nth element in self
:
a = [:foo, 'bar', 2]
a.slice!(1) # => "bar"
a # => [:foo, 2]
If n
is negative, counts backwards from the end of self
:
a = [:foo, 'bar', 2]
a.slice!(-1) # => 2
a # => [:foo, "bar"]
If n
is out of range, returns nil
.
When the only arguments are Integers start
and #length, removes #length elements from self
beginning at offset start
; returns the deleted objects in a new Array:
a = [:foo, 'bar', 2]
a.slice!(0, 2) # => [:foo, "bar"]
a # => [2]
If start + length
exceeds the array size, removes and returns all elements from offset start
to the end:
a = [:foo, 'bar', 2]
a.slice!(1, 50) # => ["bar", 2]
a # => [:foo]
If start == a.size
and #length is non-negative, returns a new empty Array.
If #length is negative, returns nil
.
When the only argument is a ::Range
object range
, treats range.min
as start
above and range.size
as #length above:
a = [:foo, 'bar', 2]
a.slice!(1..2) # => ["bar", 2]
a # => [:foo]
If range.start == a.size
, returns a new empty Array.
If range.start
is larger than the array size, returns nil
.
If range.end
is negative, counts backwards from the end of the array:
a = [:foo, 'bar', 2]
a.slice!(0..-2) # => [:foo, "bar"]
a # => [2]
If range.start
is negative, calculates the start index backwards from the end of the array:
a = [:foo, 'bar', 2]
a.slice!(-2..2) # => ["bar", 2]
a # => [:foo]
# File 'array.c', line 4176
static VALUE rb_ary_slice_bang(int argc, VALUE *argv, VALUE ary) { VALUE arg1; long pos, len; rb_ary_modify_check(ary); rb_check_arity(argc, 1, 2); arg1 = argv[0]; if (argc == 2) { pos = NUM2LONG(argv[0]); len = NUM2LONG(argv[1]); return ary_slice_bang_by_rb_ary_splice(ary, pos, len); } if (!FIXNUM_P(arg1)) { switch (rb_range_beg_len(arg1, &pos, &len, RARRAY_LEN(ary), 0)) { case Qtrue: /* valid range */ return ary_slice_bang_by_rb_ary_splice(ary, pos, len); case Qnil: /* invalid range */ return Qnil; default: /* not a range */ break; } } return rb_ary_delete_at(ary, NUM2LONG(arg1)); }
#sort ⇒ Array
#sort {|a, b| ... } ⇒ Array
Array
#sort {|a, b| ... } ⇒ Array
Returns a new Array whose elements are those from self
, sorted.
With no block, compares elements using operator #<=> (see ::Comparable
):
a = 'abcde'.split('').shuffle
a # => ["e", "b", "d", "a", "c"]
a1 = a.sort
a1 # => ["a", "b", "c", "d", "e"]
With a block, calls the block with each element pair; for each element pair a
and b
, the block should return an integer:
-
Negative when
b
is to followa
. -
Zero when
a
andb
are equivalent. -
Positive when
a
is to followb
.
Example:
a = 'abcde'.split('').shuffle
a # => ["e", "b", "d", "a", "c"]
a1 = a.sort {|a, b| a <=> b }
a1 # => ["a", "b", "c", "d", "e"]
a2 = a.sort {|a, b| b <=> a }
a2 # => ["e", "d", "c", "b", "a"]
When the block returns zero, the order for a
and b
is indeterminate, and may be unstable:
a = 'abcde'.split('').shuffle
a # => ["e", "b", "d", "a", "c"]
a1 = a.sort {|a, b| 0 }
a1 # => ["c", "e", "b", "d", "a"]
Related: Enumerable#sort_by.
# File 'array.c', line 3472
VALUE rb_ary_sort(VALUE ary) { ary = rb_ary_dup(ary); rb_ary_sort_bang(ary); return ary; }
#sort! ⇒ self
#sort! {|a, b| ... } ⇒ self
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 followa
. -
Zero when
a
andb
are equivalent. -
Positive when
a
is to followb
.
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"]
# File 'array.c', line 3368
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.receiver = ary; 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); } if (ARY_EMBED_LEN(tmp) > ARY_CAPA(ary)) { ary_resize_capa(ary, ARY_EMBED_LEN(tmp)); } 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
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!>
# File 'array.c', line 3592
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; }
When no block is given, returns the object equivalent to:
sum = init
array.each {|element| sum += element }
sum
For example, [e1, e2, e3].sum
returns init + e1 + e2 + e3
.
Examples:
a = [0, 1, 2, 3]
a.sum # => 6
a.sum(100) # => 106
The elements need not be numeric, but must be +
-compatible with each other and with init
:
a = ['abc', 'def', 'ghi']
a.sum('jkl') # => "jklabcdefghi"
When a block is given, it is called with each element and the block’s return value (instead of the element itself) is used as the addend:
a = ['zero', 1, :two]
s = a.sum('Coerced and concatenated: ') {|element| element.to_s }
s # => "Coerced and concatenated: zero1two"
Notes:
# File 'array.c', line 7984
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; if (!FIXNUM_P(v) && !RB_BIGNUM_TYPE_P(v) && !RB_TYPE_P(v, T_RATIONAL)) { i = 0; goto init_is_a_value; } 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_BIGNUM_TYPE_P(e)) v = rb_big_plus(e, v); else if (RB_TYPE_P(e, T_RATIONAL)) { if (UNDEF_P(r)) r = e; else r = rb_rational_plus(r, e); } else goto not_exact; } v = finish_exact_sum(n, r, v, argc!=0); return v; not_exact: v = finish_exact_sum(n, r, v, i!=0); if (RB_FLOAT_TYPE_P(e)) { /* * Kahan-Babuska balancing compensated summation algorithm * See https://link.springer.com/article/10.1007/s00607-005-0139-x */ double f, c; double x, t; f = NUM2DBL(v); c = 0.0; goto has_float_value; for (; i < RARRAY_LEN(ary); i++) { e = RARRAY_AREF(ary, i); if (block_given) e = rb_yield(e); if (RB_FLOAT_TYPE_P(e)) has_float_value: x = RFLOAT_VALUE(e); else if (FIXNUM_P(e)) x = FIX2LONG(e); else if (RB_BIGNUM_TYPE_P(e)) 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; init_is_a_value: for (; i < RARRAY_LEN(ary); i++) { e = RARRAY_AREF(ary, i); if (block_given) e = rb_yield(e); has_some_value: v = rb_funcall(v, idPLUS, 1, e); } return v; }
#take(n) ⇒ Array
Returns a new Array containing the first n
element of self
, where n
is a non-negative Integer; does not modify self
.
Examples:
a = [0, 1, 2, 3, 4, 5]
a.take(1) # => [0]
a.take(2) # => [0, 1]
a.take(50) # => [0, 1, 2, 3, 4, 5]
a # => [0, 1, 2, 3, 4, 5]
# File 'array.c', line 7531
static VALUE rb_ary_take(VALUE obj, VALUE n) { long len = NUM2LONG(n); if (len < 0) { rb_raise(rb_eArgError, "attempt to take negative size"); } return rb_ary_subseq(obj, 0, len); }
#take_while {|element| ... } ⇒ Array
#take_while ⇒ Enumerator
Array
#take_while ⇒ Enumerator
Returns a new Array containing zero or more leading elements of self
; does not modify self
.
With a block given, calls the block with each successive element of self
; stops if the block returns false
or nil
; returns a new Array containing those elements for which the block returned a truthy value:
a = [0, 1, 2, 3, 4, 5]
a.take_while {|element| element < 3 } # => [0, 1, 2]
a.take_while {|element| true } # => [0, 1, 2, 3, 4, 5]
a # => [0, 1, 2, 3, 4, 5]
With no block given, returns a new ::Enumerator
:
[0, 1].take_while # => #<Enumerator: [0, 1]:take_while>
# File 'array.c', line 7564
static VALUE rb_ary_take_while(VALUE ary) { long i; RETURN_ENUMERATOR(ary, 0, 0); for (i = 0; i < RARRAY_LEN(ary); i++) { if (!RTEST(rb_yield(RARRAY_AREF(ary, i)))) break; } return rb_ary_take(ary, LONG2FIX(i)); }
#to_a ⇒ self
, Array
When self
is an instance of Array, returns self
:
a = [:foo, 'bar', 2]
a.to_a # => [:foo, "bar", 2]
Otherwise, returns a new Array containing the elements of self
:
class MyArray < Array; end
a = MyArray.new(['foo', 'bar', 'two'])
a.instance_of?(Array) # => false
a.kind_of?(Array) # => true
a1 = a.to_a
a1 # => ["foo", "bar", "two"]
a1.class # => Array # Not MyArray
# File 'array.c', line 2951
static VALUE rb_ary_to_a(VALUE ary) { if (rb_obj_class(ary) != rb_cArray) { VALUE dup = rb_ary_new2(RARRAY_LEN(ary)); rb_ary_replace(dup, ary); return dup; } return ary; }
#to_ary ⇒ self
Returns self
.
# File 'array.c', line 3018
static VALUE rb_ary_to_ary_m(VALUE ary) { return ary; }
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', :, 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"}
# File 'array.c', line 2987
static VALUE rb_ary_to_h(VALUE ary) { long i; VALUE hash = rb_hash_new_with_size(RARRAY_LEN(ary)); int block_given = rb_block_given_p(); for (i=0; i<RARRAY_LEN(ary); i++) { const VALUE e = rb_ary_elt(ary, i); const VALUE elt = block_given ? rb_yield_force_blockarg(e) : e; const VALUE key_value_pair = rb_check_array_type(elt); if (NIL_P(key_value_pair)) { rb_raise(rb_eTypeError, "wrong element type %"PRIsVALUE" at %ld (expected array)", rb_obj_class(elt), i); } if (RARRAY_LEN(key_value_pair) != 2) { rb_raise(rb_eArgError, "wrong array length at %ld (expected 2, was %ld)", i, RARRAY_LEN(key_value_pair)); } rb_hash_aset(hash, RARRAY_AREF(key_value_pair, 0), RARRAY_AREF(key_value_pair, 1)); } return hash; }
#to_s ⇒ String Also known as: #inspect
# File 'array.c', line 2917
static VALUE rb_ary_inspect(VALUE ary) { if (RARRAY_LEN(ary) == 0) return rb_usascii_str_new2("[]"); return rb_exec_recursive(inspect_ary, ary, 0); }
#transpose ⇒ Array
Transposes the rows and columns in an Array of Arrays; the nested Arrays must all be the same size:
a = [[:a0, :a1], [:b0, :b1], [:c0, :c1]]
a.transpose # => [[:a0, :b0, :c0], [:a1, :b1, :c1]]
# File 'array.c', line 4491
static VALUE rb_ary_transpose(VALUE ary) { long elen = -1, alen, i, j; VALUE tmp, result = 0; alen = RARRAY_LEN(ary); if (alen == 0) return rb_ary_dup(ary); for (i=0; i<alen; i++) { tmp = to_ary(rb_ary_elt(ary, i)); if (elen < 0) { /* first element */ elen = RARRAY_LEN(tmp); result = rb_ary_new2(elen); for (j=0; j<elen; j++) { rb_ary_store(result, j, rb_ary_new2(alen)); } } else if (elen != RARRAY_LEN(tmp)) { rb_raise(rb_eIndexError, "element size differs (%ld should be %ld)", RARRAY_LEN(tmp), elen); } for (j=0; j<elen; j++) { rb_ary_store(rb_ary_elt(result, j), i, rb_ary_elt(tmp, j)); } } return result; }
#union(*other_arrays) ⇒ Array
Returns a new Array that is the union of self
and all given Arrays other_arrays
; duplicates are removed; order is preserved; items are compared using #eql?:
[0, 1, 2, 3].union([4, 5], [6, 7]) # => [0, 1, 2, 3, 4, 5, 6, 7]
[0, 1, 1].union([2, 1], [3, 1]) # => [0, 1, 2, 3]
[0, 1, 2, 3].union([3, 2], [1, 0]) # => [0, 1, 2, 3]
Returns a copy of self
if no arguments given.
Related: #|.
# File 'array.c', line 5634
static VALUE rb_ary_union_multi(int argc, VALUE *argv, VALUE ary) { int i; long sum; VALUE hash; 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) { VALUE 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]); return rb_hash_values(hash); }
#uniq ⇒ Array
#uniq {|element| ... } ⇒ Array
Array
#uniq {|element| ... } ⇒ Array
Returns a new Array containing those elements from self
that are not duplicates, the first occurrence always being retained.
With no block given, identifies and omits duplicates using method #eql? to compare:
a = [0, 0, 1, 1, 2, 2]
a.uniq # => [0, 1, 2]
With a block given, calls the block for each element; identifies (using method #eql?) and omits duplicate values, that is, those elements for which the block returns the same value:
a = ['a', 'aa', 'aaa', 'b', 'bb', 'bbb']
a.uniq {|element| element.size } # => ["a", "aa", "aaa"]
# File 'array.c', line 6176
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); } return uniq; }
#uniq! ⇒ self
?
#uniq! {|element| ... } ⇒ self
?
self
?
#uniq! {|element| ... } ⇒ self
?
Removes duplicate elements from self
, the first occurrence always being retained; returns self
if any elements removed, nil
otherwise.
With no block given, identifies and removes elements using method #eql? to compare.
Returns self
if any elements removed:
a = [0, 0, 1, 1, 2, 2]
a.uniq! # => [0, 1, 2]
Returns nil
if no elements removed.
With a block given, calls the block for each element; identifies (using method #eql?) and removes elements for which the block returns duplicate values.
Returns self
if any elements removed:
a = ['a', 'aa', 'aaa', 'b', 'bb', 'bbb']
a.uniq! {|element| element.size } # => ['a', 'aa', 'aaa']
Returns nil
if no elements removed.
# File 'array.c', line 6123
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); return ary; }
#prepend(*objects) ⇒ self
#unshift(*objects) ⇒ self
self
#unshift(*objects) ⇒ self
Alias for #prepend.
#values_at(*indexes) ⇒ Array
Returns a new Array whose elements are the elements of self
at the given ::Integer
or ::Range
indexes
.
For each positive #index, returns the element at offset #index:
a = [:foo, 'bar', 2]
a.values_at(0, 2) # => [:foo, 2]
a.values_at(0..1) # => [:foo, "bar"]
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]
a.values_at(1, 0..2) # => ["bar", :foo, "bar", 2]
Assigns nil
for an #index that is too large:
a = [:foo, 'bar', 2]
a.values_at(0, 3, 1, 3) # => [:foo, nil, "bar", nil]
Returns a new empty Array if no arguments given.
For each negative #index, counts backward from the end of the array:
a = [:foo, 'bar', 2]
a.values_at(-1, -3) # => [2, :foo]
Assigns nil
for an #index that is too small:
a = [:foo, 'bar', 2]
a.values_at(0, -5, 1, -6, 2) # => [:foo, nil, "bar", nil, 2]
The given indexes
may have a mixture of signs:
a = [:foo, 'bar', 2]
a.values_at(0, -2, 1, -1) # => [:foo, "bar", "bar", 2]
# File 'array.c', line 3768
static VALUE rb_ary_values_at(int argc, VALUE *argv, VALUE ary) { long i, olen = RARRAY_LEN(ary); VALUE result = rb_ary_new_capa(argc); for (i = 0; i < argc; ++i) { append_values_at_single(result, ary, olen, argv[i]); } RB_GC_GUARD(ary); return result; }
#zip(*other_arrays) ⇒ Array
#zip(*other_arrays) {|other_array| ... } ⇒ nil
Array
#zip(*other_arrays) {|other_array| ... } ⇒ nil
When no block given, returns a new Array new_array
of size self.size
whose elements are Arrays.
Each nested array new_array[n]
is of size other_arrays.size+1
, and contains:
-
The nth element of
self
. -
The nth element of each of the
other_arrays
.
If all other_arrays
and self
are the same size:
a = [:a0, :a1, :a2, :a3]
b = [:b0, :b1, :b2, :b3]
c = [:c0, :c1, :c2, :c3]
d = a.zip(b, c)
d # => [[:a0, :b0, :c0], [:a1, :b1, :c1], [:a2, :b2, :c2], [:a3, :b3, :c3]]
If any array in other_arrays
is smaller than self
, fills to self.size
with nil
:
a = [:a0, :a1, :a2, :a3]
b = [:b0, :b1, :b2]
c = [:c0, :c1]
d = a.zip(b, c)
d # => [[:a0, :b0, :c0], [:a1, :b1, :c1], [:a2, :b2, nil], [:a3, nil, nil]]
If any array in other_arrays
is larger than self
, its trailing elements are ignored:
a = [:a0, :a1, :a2, :a3]
b = [:b0, :b1, :b2, :b3, :b4]
c = [:c0, :c1, :c2, :c3, :c4, :c5]
d = a.zip(b, c)
d # => [[:a0, :b0, :c0], [:a1, :b1, :c1], [:a2, :b2, :c2], [:a3, :b3, :c3]]
When a block is given, calls the block with each of the sub-arrays (formed as above); returns nil
:
a = [:a0, :a1, :a2, :a3]
b = [:b0, :b1, :b2, :b3]
c = [:c0, :c1, :c2, :c3]
a.zip(b, c) {|sub_array| p sub_array} # => nil
Output:
[:a0, :b0, :c0]
[:a1, :b1, :c1]
[:a2, :b2, :c2]
[:a3, :b3, :c3]
# File 'array.c', line 4421
static VALUE rb_ary_zip(int argc, VALUE *argv, VALUE ary) { int i, j; long len = RARRAY_LEN(ary); VALUE result = Qnil; for (i=0; i<argc; i++) { argv[i] = take_items(argv[i], len); } if (rb_block_given_p()) { int arity = rb_block_arity(); if (arity > 1) { VALUE work, *tmp; tmp = ALLOCV_N(VALUE, work, argc+1); for (i=0; i<RARRAY_LEN(ary); i++) { tmp[0] = RARRAY_AREF(ary, i); for (j=0; j<argc; j++) { tmp[j+1] = rb_ary_elt(argv[j], i); } rb_yield_values2(argc+1, tmp); } if (work) ALLOCV_END(work); } else { for (i=0; i<RARRAY_LEN(ary); i++) { VALUE tmp = rb_ary_new2(argc+1); rb_ary_push(tmp, RARRAY_AREF(ary, i)); for (j=0; j<argc; j++) { rb_ary_push(tmp, rb_ary_elt(argv[j], i)); } rb_yield(tmp); } } } else { result = rb_ary_new_capa(len); for (i=0; i<len; i++) { VALUE tmp = rb_ary_new_capa(argc+1); rb_ary_push(tmp, RARRAY_AREF(ary, i)); for (j=0; j<argc; j++) { rb_ary_push(tmp, rb_ary_elt(argv[j], i)); } rb_ary_push(result, tmp); } } return result; }
#|(other_array) ⇒ Array
# File 'array.c', line 5599
static VALUE rb_ary_or(VALUE ary1, VALUE ary2) { VALUE hash; ary2 = to_ary(ary2); if (RARRAY_LEN(ary1) + RARRAY_LEN(ary2) <= SMALL_ARRAY_LEN) { VALUE 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); return rb_hash_values(hash); }