Class: Array
Overview
Arrays are ordered, integer-indexed collections of any object.
Array indexing starts at 0, as in C or Java. A negative index is assumed to be relative to the end of the array—that is, an index of -1 indicates the last element of the array, -2 is the next to last element in the array, and so on.
Creating Arrays
A new array can be created by using the literal constructor []
. Arrays can contain different types of objects. For example, the array below contains an Integer, a String and a Float:
ary = [1, "two", 3.0] #=> [1, "two", 3.0]
An array can also be created by explicitly calling Array.new with zero, one (the initial size of the Array) or two arguments (the initial size and a default object).
ary = Array.new #=> []
Array.new(3) #=> [nil, nil, nil]
Array.new(3, true) #=> [true, true, true]
Note that the second argument populates the array with references to the same object. Therefore, it is only recommended in cases when you need to instantiate arrays with natively immutable objects such as Symbols, numbers, true or false.
To create an array with separate objects a block can be passed instead. This method is safe to use with mutable objects such as hashes, strings or other arrays:
Array.new(4) {Hash.new} #=> [{}, {}, {}, {}]
Array.new(4) {|i| i.to_s } #=> ["0", "1", "2", "3"]
This is also a quick way to build up multi-dimensional arrays:
empty_table = Array.new(3) {Array.new(3)}
#=> [[nil, nil, nil], [nil, nil, nil], [nil, nil, nil]]
An array can also be created by using the Array() method, provided by Kernel, which tries to call #to_ary, then #to_a on its argument.
Array(=> “a”, :b => “b”) #=> [[:a, “a”], [:b, “b”]]
Example Usage
In addition to the methods it mixes in through the Enumerable module, the Array class has proprietary methods for accessing, searching and otherwise manipulating arrays.
Some of the more common ones are illustrated below.
Accessing Elements
Elements in an array can be retrieved using the Array#[] method. It can take a single integer argument (a numeric index), a pair of arguments (start and length) or a range. Negative indices start counting from the end, with -1 being the last element.
arr = [1, 2, 3, 4, 5, 6]
arr[2] #=> 3
arr[100] #=> nil
arr[-3] #=> 4
arr[2, 3] #=> [3, 4, 5]
arr[1..4] #=> [2, 3, 4, 5]
arr[1..-3] #=> [2, 3, 4]
Another way to access a particular array element is by using the #at method
arr.at(0) #=> 1
The #slice method works in an identical manner to Array#[].
To raise an error for indices outside of the array bounds or else to provide a default value when that happens, you can use #fetch.
arr = ['a', 'b', 'c', 'd', 'e', 'f']
arr.fetch(100) #=> IndexError: index 100 outside of array bounds: -6...6
arr.fetch(100, "oops") #=> "oops"
The special methods #first and #last will return the first and last elements of an array, respectively.
arr.first #=> 1
arr.last #=> 6
To return the first n
elements of an array, use #take
arr.take(3) #=> [1, 2, 3]
#drop does the opposite of #take, by returning the elements after n
elements have been dropped:
arr.drop(3) #=> [4, 5, 6]
Obtaining Information about an Array
Arrays keep track of their own length at all times. To query an array about the number of elements it contains, use #length, #count or #size.
browsers = ['Chrome', 'Firefox', 'Safari', 'Opera', 'IE']
browsers.length #=> 5
browsers.count #=> 5
To check whether an array contains any elements at all
browsers.empty? #=> false
To check whether a particular item is included in the array
browsers.include?('Konqueror') #=> false
Adding Items to Arrays
Items can be added to the end of an array by using either #push or #<<
arr = [1, 2, 3, 4]
arr.push(5) #=> [1, 2, 3, 4, 5]
arr << 6 #=> [1, 2, 3, 4, 5, 6]
#unshift will add a new item to the beginning of an array.
arr.unshift(0) #=> [0, 1, 2, 3, 4, 5, 6]
With #insert you can add a new element to an array at any position.
arr.insert(3, 'apple') #=> [0, 1, 2, 'apple', 3, 4, 5, 6]
Using the #insert method, you can also insert multiple values at once:
arr.insert(3, 'orange', 'pear', 'grapefruit')
#=> [0, 1, 2, "orange", "pear", "grapefruit", "apple", 3, 4, 5, 6]
Removing Items from an Array
The method #pop removes the last element in an array and returns it:
arr = [1, 2, 3, 4, 5, 6]
arr.pop #=> 6
arr #=> [1, 2, 3, 4, 5]
To retrieve and at the same time remove the first item, use #shift:
arr.shift #=> 1
arr #=> [2, 3, 4, 5]
To delete an element at a particular index:
arr.delete_at(2) #=> 4
arr #=> [2, 3, 5]
To delete a particular element anywhere in an array, use #delete:
arr = [1, 2, 2, 3]
arr.delete(2) #=> 2
arr #=> [1,3]
A useful method if you need to remove nil
values from an array is #compact:
arr = ['foo', 0, nil, 'bar', 7, 'baz', nil]
arr.compact #=> ['foo', 0, 'bar', 7, 'baz']
arr #=> ['foo', 0, nil, 'bar', 7, 'baz', nil]
arr.compact! #=> ['foo', 0, 'bar', 7, 'baz']
arr #=> ['foo', 0, 'bar', 7, 'baz']
Another common need is to remove duplicate elements from an array.
It has the non-destructive #uniq, and destructive method #uniq!
arr = [2, 5, 6, 556, 6, 6, 8, 9, 0, 123, 556]
arr.uniq #=> [2, 5, 6, 556, 8, 9, 0, 123]
Iterating over Arrays
Like all classes that include the Enumerable module, Array has an each method, which defines what elements should be iterated over and how. In case of Array’s #each, all elements in the Array instance are yielded to the supplied block in sequence.
Note that this operation leaves the array unchanged.
arr = [1, 2, 3, 4, 5]
arr.each {|a| print a -= 10, " "}
# prints: -9 -8 -7 -6 -5
#=> [1, 2, 3, 4, 5]
Another sometimes useful iterator is #reverse_each which will iterate over the elements in the array in reverse order.
words = %w[first second third fourth fifth sixth]
str = ""
words.reverse_each {|word| str += "#{word} "}
p str #=> "sixth fifth fourth third second first "
The #map method can be used to create a new array based on the original array, but with the values modified by the supplied block:
arr.map {|a| 2*a} #=> [2, 4, 6, 8, 10]
arr #=> [1, 2, 3, 4, 5]
arr.map! {|a| a**2} #=> [1, 4, 9, 16, 25]
arr #=> [1, 4, 9, 16, 25]
Selecting Items from an Array
Elements can be selected from an array according to criteria defined in a block. The selection can happen in a destructive or a non-destructive manner. While the destructive operations will modify the array they were called on, the non-destructive methods usually return a new array with the selected elements, but leave the original array unchanged.
Non-destructive Selection
arr = [1, 2, 3, 4, 5, 6]
arr.select {|a| a > 3} #=> [4, 5, 6]
arr.reject {|a| a < 3} #=> [3, 4, 5, 6]
arr.drop_while {|a| a < 4} #=> [4, 5, 6]
arr #=> [1, 2, 3, 4, 5, 6]
Destructive Selection
#select! and #reject! are the corresponding destructive methods to #select and #reject
Similar to #select vs. #reject, #delete_if and #keep_if have the exact opposite result when supplied with the same block:
arr.delete_if {|a| a < 4} #=> [4, 5, 6]
arr #=> [4, 5, 6]
arr = [1, 2, 3, 4, 5, 6]
arr.keep_if {|a| a < 4} #=> [1, 2, 3]
arr #=> [1, 2, 3]
Class Method Summary collapse
-
.[](*args) ⇒ Object
Returns a new array populated with the given objects.
-
.try_convert(obj) ⇒ Array?
Tries to convert
obj
into an array, using theto_ary
method.
Instance Method Summary collapse
-
#&(other_ary) ⇒ Array
Set Intersection — Returns a new array containing unique elements common to the two arrays.
-
#*(times) ⇒ Object
Repetition — With a String argument, equivalent to
ary.join(str)
. -
#+(other_ary) ⇒ Array
Concatenation — Returns a new array built by concatenating the two arrays together to produce a third array.
-
#-(other_ary) ⇒ Array
Array Difference.
-
#<<(obj) ⇒ Array
Append—Pushes the given object on to the end of this array.
-
#<=>(other_ary) ⇒ -1, ...
Comparison — Returns an integer (
-1
,0
, or+1
) if this array is less than, equal to, or greater thanother_ary
. -
#==(other_ary) ⇒ Boolean
Equality — Two arrays are equal if they contain the same number of elements and if each element is equal to (according to Object#==) the corresponding element in
other_ary
. -
#[](*args) ⇒ Object
Element Reference — Returns the element at
index
, or returns a subarray starting at thestart
index and continuing forlength
elements, or returns a subarray specified byrange
of indices. -
#[]=(*args) ⇒ Object
Element Assignment — Sets the element at
index
, or replaces a subarray from thestart
index forlength
elements, or replaces a subarray specified by therange
of indices. -
#all?(*args) ⇒ Object
See also Enumerable#all?.
-
#any?(*args) ⇒ Object
See also Enumerable#any?.
-
#assoc(obj) ⇒ nil
Searches through an array whose elements are also arrays comparing
obj
with the first element of each contained array usingobj.==
. -
#at(index) ⇒ Object?
Returns the element at
index
. -
#bsearch {|x| ... } ⇒ Object
By using binary search, finds a value from this array which meets the given condition in O(log n) where n is the size of the array.
-
#bsearch_index {|x| ... } ⇒ Integer?
By using binary search, finds an index of a value from this array which meets the given condition in O(log n) where n is the size of the array.
-
#clear ⇒ Array
Removes all elements from
self
. -
#collect ⇒ Object
Invokes the given block once for each element of
self
. -
#collect! ⇒ Object
Invokes the given block once for each element of
self
, replacing the element with the value returned by the block. -
#combination(num) ⇒ Object
When invoked with a block, yields all combinations of length
n
of elements from the array and then returns the array itself. -
#compact ⇒ Array
Returns a copy of
self
with allnil
elements removed. -
#compact! ⇒ Array?
Removes
nil
elements from the array. -
#concat(other_ary1, other_ary2, ...) ⇒ Array
Appends the elements of
other_ary
s toself
. -
#count(*args) ⇒ Object
Returns the number of elements.
-
#cycle(*args) ⇒ Object
Calls the given block for each element
n
times or forever ifnil
is given. - #deconstruct ⇒ Object
-
#delete(item) ⇒ Object
Deletes all items from
self
that are equal toobj
. -
#delete_at(index) ⇒ Object?
Deletes the element at the specified
index
, returning that element, ornil
if theindex
is out of range. -
#delete_if ⇒ Object
Deletes every element of
self
for which block evaluates totrue
. -
#difference(other_ary1, other_ary2, ...) ⇒ Array
Array Difference.
-
#dig(idx, ...) ⇒ Object
Extracts the nested value specified by the sequence of idx objects by calling
dig
at each step, returningnil
if any intermediate step isnil
. -
#drop(n) ⇒ Array
Drops first
n
elements fromary
and returns the rest of the elements in an array. -
#drop_while ⇒ Object
Drops elements up to, but not including, the first element for which the block returns
nil
orfalse
and returns an array containing the remaining elements. -
#each ⇒ Object
Calls the given block once for each element in
self
, passing that element as a parameter. -
#each_index ⇒ Object
Same as Array#each, but passes the
index
of the element instead of the element itself. -
#empty? ⇒ Boolean
Returns
true
ifself
contains no elements. -
#eql?(other) ⇒ Boolean
Returns
true
ifself
andother
are the same object, or are both arrays with the same content (according to Object#eql?). -
#fetch(*args) ⇒ Object
Tries to return the element at position
index
, but throws an IndexError exception if the referencedindex
lies outside of the array bounds. -
#fill(*args) ⇒ Object
The first three forms set the selected elements of
self
(which may be the entire array) toobj
. -
#filter ⇒ Object
Returns a new array containing all elements of
ary
for which the givenblock
returns a true value. -
#filter! ⇒ Object
Invokes the given block passing in successive elements from
self
, deleting elements for which the block returns afalse
value. -
#find_index(*args) ⇒ Object
Returns the index of the first object in
ary
such that the object is==
toobj
. -
#first(*args) ⇒ Object
Returns the first element, or the first
n
elements, of the array. -
#flatten(*args) ⇒ Object
Returns a new array that is a one-dimensional flattening of
self
(recursively). -
#flatten!(*args) ⇒ Object
Flattens
self
in place. -
#hash ⇒ Integer
Compute a hash-code for this array.
-
#include?(object) ⇒ Boolean
Returns
true
if the givenobject
is present inself
(that is, if any element==
object
), otherwise returnsfalse
. -
#index(*args) ⇒ Object
Returns the index of the first object in
ary
such that the object is==
toobj
. -
#initialize(*args) ⇒ Object
constructor
Returns a new array.
-
#initialize_copy(orig) ⇒ Object
Replaces the contents of
self
with the contents ofother_ary
, truncating or expanding if necessary. -
#insert(index, obj...) ⇒ Array
Inserts the given values before the element with the given
index
. -
#inspect ⇒ Object
(also: #to_s)
Creates a string representation of
self
, by calling #inspect on each element. -
#intersection(other_ary1, other_ary2, ...) ⇒ Array
Set Intersection — Returns a new array containing unique elements common to
self
andother_ary
s. -
#join(separator = $,) ⇒ String
Returns a string created by converting each element of the array to a string, separated by the given
separator
. -
#keep_if ⇒ Object
Deletes every element of
self
for which the given block evaluates tofalse
, and returnsself
. -
#last(*args) ⇒ Object
Returns the last element(s) of
self
. -
#length ⇒ Integer
(also: #size)
Returns the number of elements in
self
. -
#map ⇒ Object
Invokes the given block once for each element of
self
. -
#map! ⇒ Object
Invokes the given block once for each element of
self
, replacing the element with the value returned by the block. -
#max(*args) ⇒ Object
Returns the object in ary with the maximum value.
-
#min(*args) ⇒ Object
Returns the object in ary with the minimum value.
-
#minmax ⇒ Object
Returns a two element array which contains the minimum and the maximum value in the array.
-
#none?(*args) ⇒ Object
See also Enumerable#none?.
-
#one?(*args) ⇒ Object
See also Enumerable#one?.
-
#permutation(*args) ⇒ Object
When invoked with a block, yield all permutations of length
n
of the elements of the array, then return the array itself. -
#pop(*args) ⇒ Object
Removes the last element from
self
and returns it, ornil
if the array is empty. -
#product(*args) ⇒ Object
Returns an array of all combinations of elements from all arrays.
-
#push(*args) ⇒ Object
(also: #append)
Append — Pushes the given object(s) on to the end of this array.
-
#rassoc(obj) ⇒ nil
Searches through the array whose elements are also arrays.
-
#reject ⇒ Object
Returns a new array containing the items in
self
for which the given block is nottrue
. -
#reject! ⇒ Object
Deletes every element of
self
for which the block evaluates totrue
, if no changes were made returnsnil
. -
#repeated_combination(num) ⇒ Object
When invoked with a block, yields all repeated combinations of length
n
of elements from the array and then returns the array itself. -
#repeated_permutation(num) ⇒ Object
When invoked with a block, yield all repeated permutations of length
n
of the elements of the array, then return the array itself. -
#replace(orig) ⇒ Object
Replaces the contents of
self
with the contents ofother_ary
, truncating or expanding if necessary. -
#reverse ⇒ Array
Returns a new array containing
self
‘s elements in reverse order. -
#reverse! ⇒ Array
Reverses
self
in place. -
#reverse_each ⇒ Object
Same as Array#each, but traverses
self
in reverse order. -
#rindex(*args) ⇒ Object
Returns the index of the last object in
self
==
toobj
. -
#rotate(count = 1) ⇒ Array
Returns a new array by rotating
self
so that the element atcount
is the first element of the new array. -
#rotate!(count = 1) ⇒ Array
Rotates
self
in place so that the element atcount
comes first, and returnsself
. -
#sample(*args) ⇒ Object
Choose a random element or
n
random elements from the array. -
#select ⇒ Object
Returns a new array containing all elements of
ary
for which the givenblock
returns a true value. -
#select! ⇒ Object
Invokes the given block passing in successive elements from
self
, deleting elements for which the block returns afalse
value. -
#shift(*args) ⇒ Object
Removes the first element of
self
and returns it (shifting all other elements down by one). -
#shuffle(*args) ⇒ Object
Returns a new array with elements of
self
shuffled. -
#shuffle!(*args) ⇒ Object
Shuffles elements in
self
in place. -
#slice(*args) ⇒ Object
Element Reference — Returns the element at
index
, or returns a subarray starting at thestart
index and continuing forlength
elements, or returns a subarray specified byrange
of indices. -
#slice!(*args) ⇒ Object
Deletes the element(s) given by an
index
(optionally up tolength
elements) or by arange
. -
#sort ⇒ Object
Returns a new array created by sorting
self
. -
#sort! ⇒ Object
Sorts
self
in place. -
#sort_by! ⇒ Object
Sorts
self
in place using a set of keys generated by mapping the values inself
through the given block. -
#sum(*args) ⇒ Object
Returns the sum of elements.
-
#take(n) ⇒ Array
Returns first
n
elements from the array. -
#take_while ⇒ Object
Passes elements to the block until the block returns
nil
orfalse
, then stops iterating and returns an array of all prior elements. -
#to_a ⇒ Array
Returns
self
. -
#to_ary ⇒ Array
Returns
self
. -
#to_h ⇒ Object
Returns the result of interpreting ary as an array of
[key, value]
pairs. -
#transpose ⇒ Array
Assumes that
self
is an array of arrays and transposes the rows and columns. -
#union(other_ary1, other_ary2, ...) ⇒ Array
Set Union — Returns a new array by joining
other_ary
s withself
, excluding any duplicates and preserving the order from the given arrays. -
#uniq ⇒ Object
Returns a new array by removing duplicate values in
self
. -
#uniq! ⇒ Object
Removes duplicate elements from
self
. -
#unshift(*args) ⇒ Object
(also: #prepend)
Prepends objects to the front of
self
, moving other elements upwards. -
#values_at(selector, ...) ⇒ Array
Returns an array containing the elements in
self
corresponding to the givenselector
(s). -
#zip(*args) ⇒ Object
Converts any arguments to arrays, then merges elements of
self
with corresponding elements from each argument. -
#|(other_ary) ⇒ Array
Set Union — Returns a new array by joining
ary
withother_ary
, excluding any duplicates and preserving the order from the given arrays.
Methods included from Enumerable
#chain, #chunk, #chunk_while, #collect_concat, #detect, #each_cons, #each_entry, #each_slice, #each_with_index, #each_with_object, #entries, #filter_map, #find, #find_all, #flat_map, #grep, #grep_v, #group_by, #inject, #lazy, #max_by, #member?, #min_by, #minmax_by, #partition, #reduce, #slice_after, #slice_before, #slice_when, #sort_by, #tally
Constructor Details
#new(size = 0, default = nil) ⇒ Object #new(array) ⇒ Object #new(size) {|index| ... } ⇒ Object
Returns a new array.
In the first form, if no arguments are sent, the new array will be empty. When a size
and an optional default
are sent, an array is created with size
copies of default
. Take notice that all elements will reference the same object default
.
The second form creates a copy of the array passed as a parameter (the array is generated by calling to_ary on the parameter).
first_array = ["Matz", "Guido"]
second_array = Array.new(first_array) #=> ["Matz", "Guido"]
first_array.equal? second_array #=> false
In the last form, an array of the given size is created. Each element in this array is created by passing the element’s index to the given block and storing the return value.
Array.new(3) {|index| index ** 2}
# => [0, 1, 4]
Common gotchas
When sending the second parameter, the same object will be used as the value for all the array elements:
a = Array.new(2, Hash.new)
# => [{}, {}]
a[0]['cat'] = 'feline'
a # => [{"cat"=>"feline"}, {"cat"=>"feline"}]
a[1]['cat'] = 'Felix'
a # => [{"cat"=>"Felix"}, {"cat"=>"Felix"}]
Since all the Array elements store the same hash, changes to one of them will affect them all.
If multiple copies are what you want, you should use the block version which uses the result of that block each time an element of the array needs to be initialized:
a = Array.new(2) {Hash.new}
a[0]['cat'] = 'feline'
a # => [{"cat"=>"feline"}, {}]
1001 1002 1003 1004 1005 1006 1007 1008 1009 1010 1011 1012 1013 1014 1015 1016 1017 1018 1019 1020 1021 1022 1023 1024 1025 1026 1027 1028 1029 1030 1031 1032 1033 1034 1035 1036 1037 1038 1039 1040 1041 1042 1043 1044 1045 1046 1047 1048 1049 1050 1051 1052 1053 1054 1055 1056 |
# File 'array.c', line 1001 static VALUE rb_ary_initialize(int argc, VALUE *argv, VALUE ary) { long len; VALUE size, val; rb_ary_modify(ary); if (argc == 0) { if (ARY_OWNS_HEAP_P(ary) && ARY_HEAP_PTR(ary) != NULL) { ary_heap_free(ary); } rb_ary_unshare_safe(ary); FL_SET_EMBED(ary); ARY_SET_EMBED_LEN(ary, 0); if (rb_block_given_p()) { rb_warning("given block not used"); } return ary; } rb_scan_args(argc, argv, "02", &size, &val); if (argc == 1 && !FIXNUM_P(size)) { val = rb_check_array_type(size); if (!NIL_P(val)) { rb_ary_replace(ary, val); return ary; } } len = NUM2LONG(size); /* NUM2LONG() may call size.to_int, ary can be frozen, modified, etc */ if (len < 0) { rb_raise(rb_eArgError, "negative array size"); } if (len > ARY_MAX_SIZE) { rb_raise(rb_eArgError, "array size too big"); } /* recheck after argument conversion */ rb_ary_modify(ary); ary_resize_capa(ary, len); if (rb_block_given_p()) { long i; if (argc == 2) { rb_warn("block supersedes default value argument"); } for (i=0; i<len; i++) { rb_ary_store(ary, i, rb_yield(LONG2NUM(i))); ARY_SET_LEN(ary, i + 1); } } else { ary_memfill(ary, 0, len, val); ARY_SET_LEN(ary, len); } return ary; } |
Class Method Details
.[](*args) ⇒ Object
Returns a new array populated with the given objects.
Array.[]( 1, 'a', /^A/) # => [1, "a", /^A/]
Array[ 1, 'a', /^A/ ] # => [1, "a", /^A/]
[ 1, 'a', /^A/ ] # => [1, "a", /^A/]
1066 1067 1068 1069 1070 1071 1072 1073 1074 1075 1076 |
# File 'array.c', line 1066 static VALUE rb_ary_s_create(int argc, VALUE *argv, VALUE klass) { VALUE ary = ary_new(klass, argc); if (argc > 0 && argv) { ary_memcpy(ary, 0, argc, argv); ARY_SET_LEN(ary, argc); } return ary; } |
.try_convert(obj) ⇒ Array?
Tries to convert obj
into an array, using the to_ary
method. Returns the converted array or nil
if obj
cannot be converted. This method can be used to check if an argument is an array.
Array.try_convert([1]) #=> [1]
Array.try_convert("1") #=> nil
if tmp = Array.try_convert(arg)
# the argument is an array
elsif tmp = String.try_convert(arg)
# the argument is a string
end
939 940 941 942 943 |
# File 'array.c', line 939 static VALUE rb_ary_s_try_convert(VALUE dummy, VALUE ary) { return rb_check_array_type(ary); } |
Instance Method Details
#&(other_ary) ⇒ Array
Set Intersection — Returns a new array containing unique elements common to the two arrays. The order is preserved from the original array.
It compares elements using their #hash and #eql? methods for efficiency.
[ 1, 1, 3, 5 ] & [ 3, 2, 1 ] #=> [ 1, 3 ]
[ 'a', 'b', 'b', 'z' ] & [ 'a', 'b', 'c' ] #=> [ 'a', 'b' ]
See also Array#uniq.
4628 4629 4630 4631 4632 4633 4634 4635 4636 4637 4638 4639 4640 4641 4642 4643 4644 4645 4646 4647 4648 4649 4650 4651 4652 4653 4654 4655 4656 4657 4658 4659 4660 4661 |
# File 'array.c', line 4628 static VALUE rb_ary_and(VALUE ary1, VALUE ary2) { VALUE hash, ary3, v; st_data_t vv; long i; ary2 = to_ary(ary2); ary3 = rb_ary_new(); if (RARRAY_LEN(ary1) == 0 || RARRAY_LEN(ary2) == 0) return ary3; if (RARRAY_LEN(ary1) <= SMALL_ARRAY_LEN && RARRAY_LEN(ary2) <= SMALL_ARRAY_LEN) { for (i=0; i<RARRAY_LEN(ary1); i++) { v = RARRAY_AREF(ary1, i); if (!rb_ary_includes_by_eql(ary2, v)) continue; if (rb_ary_includes_by_eql(ary3, v)) continue; rb_ary_push(ary3, v); } return ary3; } hash = ary_make_hash(ary2); for (i=0; i<RARRAY_LEN(ary1); i++) { v = RARRAY_AREF(ary1, i); vv = (st_data_t)v; if (rb_hash_stlike_delete(hash, &vv, 0)) { rb_ary_push(ary3, v); } } ary_recycle_hash(hash); return ary3; } |
#*(int) ⇒ Array #*(str) ⇒ Object
Repetition — With a String argument, equivalent to ary.join(str)
.
Otherwise, returns a new array built by concatenating the int
copies of self
.
[ 1, 2, 3 ] * 3 #=> [ 1, 2, 3, 1, 2, 3, 1, 2, 3 ]
[ 1, 2, 3 ] * "," #=> "1,2,3"
4091 4092 4093 4094 4095 4096 4097 4098 4099 4100 4101 4102 4103 4104 4105 4106 4107 4108 4109 4110 4111 4112 4113 4114 4115 4116 4117 4118 4119 4120 4121 4122 4123 4124 4125 4126 4127 4128 4129 4130 4131 4132 4133 |
# File 'array.c', line 4091 static VALUE rb_ary_times(VALUE ary, VALUE times) { VALUE ary2, tmp; const VALUE *ptr; long t, len; tmp = rb_check_string_type(times); if (!NIL_P(tmp)) { return rb_ary_join(ary, tmp); } len = NUM2LONG(times); if (len == 0) { ary2 = ary_new(rb_obj_class(ary), 0); goto out; } if (len < 0) { rb_raise(rb_eArgError, "negative argument"); } if (ARY_MAX_SIZE/len < RARRAY_LEN(ary)) { rb_raise(rb_eArgError, "argument too big"); } len *= RARRAY_LEN(ary); ary2 = ary_new(rb_obj_class(ary), len); ARY_SET_LEN(ary2, len); ptr = RARRAY_CONST_PTR_TRANSIENT(ary); t = RARRAY_LEN(ary); if (0 < t) { ary_memcpy(ary2, 0, t, ptr); while (t <= len/2) { ary_memcpy(ary2, t, t, RARRAY_CONST_PTR_TRANSIENT(ary2)); t *= 2; } if (t < len) { ary_memcpy(ary2, t, len-t, RARRAY_CONST_PTR_TRANSIENT(ary2)); } } out: return ary2; } |
#+(other_ary) ⇒ Array
Concatenation — Returns a new array built by concatenating the two arrays together to produce a third array.
[ 1, 2, 3 ] + [ 4, 5 ] #=> [ 1, 2, 3, 4, 5 ]
a = [ "a", "b", "c" ]
c = a + [ "d", "e", "f" ]
c #=> [ "a", "b", "c", "d", "e", "f" ]
a #=> [ "a", "b", "c" ]
Note that
x += y
is the same as
x = x + y
This means that it produces a new array. As a consequence, repeated use of +=
on arrays can be quite inefficient.
See also Array#concat.
3999 4000 4001 4002 4003 4004 4005 4006 4007 4008 4009 4010 4011 4012 4013 4014 4015 |
# File 'array.c', line 3999 VALUE rb_ary_plus(VALUE x, VALUE y) { VALUE z; long len, xlen, ylen; y = to_ary(y); xlen = RARRAY_LEN(x); ylen = RARRAY_LEN(y); len = xlen + ylen; z = rb_ary_new2(len); ary_memcpy(z, 0, xlen, RARRAY_CONST_PTR_TRANSIENT(x)); ary_memcpy(z, xlen, ylen, RARRAY_CONST_PTR_TRANSIENT(y)); ARY_SET_LEN(z, len); return z; } |
#-(other_ary) ⇒ Array
Array Difference
Returns a new array that is a copy of the original array, removing all occurrences of any item that also appear in other_ary
. The order is preserved from the original array.
It compares elements using their #hash and #eql? methods for efficiency.
[ 1, 1, 2, 2, 3, 3, 4, 5 ] - [ 1, 2, 4 ] #=> [ 3, 3, 5 ]
Note that while 1 and 2 were only present once in the array argument, and were present twice in the receiver array, all occurrences of each Integer are removed in the returned array.
If you need set-like behavior, see the library class Set.
See also Array#difference.
4518 4519 4520 4521 4522 4523 4524 4525 4526 4527 4528 4529 4530 4531 4532 4533 4534 4535 4536 4537 4538 4539 4540 4541 4542 4543 4544 |
# File 'array.c', line 4518 static VALUE rb_ary_diff(VALUE ary1, VALUE ary2) { VALUE ary3; VALUE hash; long i; ary2 = to_ary(ary2); ary3 = rb_ary_new(); if (RARRAY_LEN(ary1) <= SMALL_ARRAY_LEN || RARRAY_LEN(ary2) <= SMALL_ARRAY_LEN) { for (i=0; i<RARRAY_LEN(ary1); i++) { VALUE elt = rb_ary_elt(ary1, i); if (rb_ary_includes_by_eql(ary2, elt)) continue; rb_ary_push(ary3, elt); } return ary3; } hash = ary_make_hash(ary2); for (i=0; i<RARRAY_LEN(ary1); i++) { if (rb_hash_stlike_lookup(hash, RARRAY_AREF(ary1, i), NULL)) continue; rb_ary_push(ary3, rb_ary_elt(ary1, i)); } ary_recycle_hash(hash); return ary3; } |
#<<(obj) ⇒ Array
Append—Pushes the given object on to the end of this array. This expression returns the array itself, so several appends may be chained together.
a = [ 1, 2 ]
a << "c" << "d" << [ 3, 4 ]
#=> [ 1, 2, "c", "d", [ 3, 4 ] ]
a
#=> [ 1, 2, "c", "d", [ 3, 4 ] ]
1194 1195 1196 1197 1198 1199 1200 1201 1202 1203 1204 1205 |
# File 'array.c', line 1194 VALUE rb_ary_push(VALUE ary, VALUE item) { long idx = RARRAY_LEN((ary_verify(ary), ary)); VALUE target_ary = ary_ensure_room_for_push(ary, 1); RARRAY_PTR_USE_TRANSIENT(ary, ptr, { RB_OBJ_WRITE(target_ary, &ptr[idx], item); }); ARY_SET_LEN(ary, idx + 1); ary_verify(ary); return ary; } |
#<=>(other_ary) ⇒ -1, ...
Comparison — Returns an integer (-1
, 0
, or +1
) if this array is less than, equal to, or greater than other_ary
.
Each object in each array is compared (using the <=> operator).
Arrays are compared in an “element-wise” manner; the first element of ary
is compared with the first one of other_ary
using the <=> operator, then each of the second elements, etc… As soon as the result of any such comparison is non zero (i.e. the two corresponding elements are not equal), that result is returned for the whole array comparison.
If all the elements are equal, then the result is based on a comparison of the array lengths. Thus, two arrays are “equal” according to Array#<=> if, and only if, they have the same length and the value of each element is equal to the value of the corresponding element in the other array.
nil
is returned if the other_ary
is not an array or if the comparison of two elements returned nil
.
[ "a", "a", "c" ] <=> [ "a", "b", "c" ] #=> -1
[ 1, 2, 3, 4, 5, 6 ] <=> [ 1, 2 ] #=> +1
[ 1, 2 ] <=> [ 1, :two ] #=> nil
4419 4420 4421 4422 4423 4424 4425 4426 4427 4428 4429 4430 4431 4432 4433 4434 |
# File 'array.c', line 4419 VALUE rb_ary_cmp(VALUE ary1, VALUE ary2) { long len; VALUE v; ary2 = rb_check_array_type(ary2); if (NIL_P(ary2)) return Qnil; if (ary1 == ary2) return INT2FIX(0); v = rb_exec_recursive_paired(recursive_cmp, ary1, ary2, ary2); if (v != Qundef) return v; len = RARRAY_LEN(ary1) - RARRAY_LEN(ary2); if (len == 0) return INT2FIX(0); if (len > 0) return INT2FIX(1); return INT2FIX(-1); } |
#==(other_ary) ⇒ Boolean
Equality — Two arrays are equal if they contain the same number of elements and if each element is equal to (according to Object#==) the corresponding element in other_ary
.
[ "a", "c" ] == [ "a", "c", 7 ] #=> false
[ "a", "c", 7 ] == [ "a", "c", 7 ] #=> true
[ "a", "c", 7 ] == [ "a", "d", "f" ] #=> false
4252 4253 4254 4255 4256 4257 4258 4259 4260 4261 4262 4263 4264 4265 |
# File 'array.c', line 4252 static VALUE rb_ary_equal(VALUE ary1, VALUE ary2) { if (ary1 == ary2) return Qtrue; if (!RB_TYPE_P(ary2, T_ARRAY)) { if (!rb_respond_to(ary2, idTo_ary)) { return Qfalse; } return rb_equal(ary2, ary1); } if (RARRAY_LEN(ary1) != RARRAY_LEN(ary2)) return Qfalse; if (RARRAY_CONST_PTR_TRANSIENT(ary1) == RARRAY_CONST_PTR_TRANSIENT(ary2)) return Qtrue; return rb_exec_recursive_paired(recursive_equal, ary1, ary2, ary2); } |
#[](index) ⇒ Object? #[](start, length) ⇒ Array? #[](range) ⇒ Array? #slice(index) ⇒ Object? #slice(start, length) ⇒ Array? #slice(range) ⇒ Array?
Element Reference — Returns the element at index
, or returns a subarray starting at the start
index and continuing for length
elements, or returns a subarray specified by range
of indices.
Negative indices count backward from the end of the array (-1 is the last element). For start
and range
cases the starting index is just before an element. Additionally, an empty array is returned when the starting index for an element range is at the end of the array.
Returns nil
if the index (or starting index) are out of range.
a = [ "a", "b", "c", "d", "e" ]
a[2] + a[0] + a[1] #=> "cab"
a[6] #=> nil
a[1, 2] #=> [ "b", "c" ]
a[1..3] #=> [ "b", "c", "d" ]
a[4..7] #=> [ "e" ]
a[6..10] #=> nil
a[-3, 3] #=> [ "c", "d", "e" ]
# special cases
a[5] #=> nil
a[6, 1] #=> nil
a[5, 1] #=> []
a[5..10] #=> []
1573 1574 1575 1576 1577 1578 1579 1580 1581 |
# File 'array.c', line 1573 VALUE rb_ary_aref(int argc, const VALUE *argv, VALUE ary) { rb_check_arity(argc, 1, 2); if (argc == 2) { return rb_ary_aref2(ary, argv[0], argv[1]); } return rb_ary_aref1(ary, argv[0]); } |
#[]=(index) ⇒ Object #[]=(start, length) ⇒ Object? #[]=(range) ⇒ Object?
Element Assignment — Sets the element at index
, or replaces a subarray from the start
index for length
elements, or replaces a subarray specified by the range
of indices.
If indices are greater than the current capacity of the array, the array grows automatically. Elements are inserted into the array at start
if length
is zero.
Negative indices will count backward from the end of the array. For start
and range
cases the starting index is just before an element.
An IndexError is raised if a negative index points past the beginning of the array.
See also Array#push, and Array#unshift.
a = Array.new
a[4] = "4"; #=> [nil, nil, nil, nil, "4"]
a[0, 3] = [ 'a', 'b', 'c' ] #=> ["a", "b", "c", nil, "4"]
a[1..2] = [ 1, 2 ] #=> ["a", 1, 2, nil, "4"]
a[0, 2] = "?" #=> ["?", 2, nil, "4"]
a[0..2] = "A" #=> ["A", "4"]
a[-1] = "Z" #=> ["A", "Z"]
a[1..-1] = nil #=> ["A", nil]
a[1..-1] = [] #=> ["A"]
a[0, 0] = [ 1, 2 ] #=> [1, 2, "A"]
a[3, 0] = "B" #=> [1, 2, "A", "B"]
2028 2029 2030 2031 2032 2033 2034 2035 2036 2037 2038 2039 2040 2041 2042 2043 2044 2045 2046 2047 2048 2049 2050 2051 2052 2053 2054 2055 2056 2057 2058 2059 |
# File 'array.c', line 2028 static VALUE rb_ary_aset(int argc, VALUE *argv, VALUE ary) { long offset, beg, len; VALUE rpl; if (argc == 3) { rb_ary_modify_check(ary); beg = NUM2LONG(argv[0]); len = NUM2LONG(argv[1]); goto range; } rb_check_arity(argc, 2, 2); rb_ary_modify_check(ary); if (FIXNUM_P(argv[0])) { offset = FIX2LONG(argv[0]); goto fixnum; } if (rb_range_beg_len(argv[0], &beg, &len, RARRAY_LEN(ary), 1)) { /* check if idx is Range */ range: rpl = rb_ary_to_ary(argv[argc-1]); rb_ary_splice(ary, beg, len, RARRAY_CONST_PTR_TRANSIENT(rpl), RARRAY_LEN(rpl)); RB_GC_GUARD(rpl); return argv[argc-1]; } offset = NUM2LONG(argv[0]); fixnum: rb_ary_store(ary, offset, argv[1]); return argv[1]; } |
#all? {|obj| ... } ⇒ Boolean #all?(pattern) ⇒ Boolean
See also Enumerable#all?
6366 6367 6368 6369 6370 6371 6372 6373 6374 6375 6376 6377 6378 6379 6380 6381 6382 6383 6384 6385 6386 6387 6388 6389 6390 6391 6392 |
# File 'array.c', line 6366 static VALUE rb_ary_all_p(int argc, VALUE *argv, VALUE ary) { long i, len = RARRAY_LEN(ary); rb_check_arity(argc, 0, 1); if (!len) return Qtrue; if (argc) { if (rb_block_given_p()) { rb_warn("given block not used"); } for (i = 0; i < RARRAY_LEN(ary); ++i) { if (!RTEST(rb_funcall(argv[0], idEqq, 1, RARRAY_AREF(ary, i)))) return Qfalse; } } else if (!rb_block_given_p()) { for (i = 0; i < len; ++i) { if (!RTEST(RARRAY_AREF(ary, i))) return Qfalse; } } else { for (i = 0; i < RARRAY_LEN(ary); ++i) { if (!RTEST(rb_yield(RARRAY_AREF(ary, i)))) return Qfalse; } } return Qtrue; } |
#any? {|obj| ... } ⇒ Boolean #any?(pattern) ⇒ Boolean
See also Enumerable#any?
6330 6331 6332 6333 6334 6335 6336 6337 6338 6339 6340 6341 6342 6343 6344 6345 6346 6347 6348 6349 6350 6351 6352 6353 6354 6355 6356 |
# File 'array.c', line 6330 static VALUE rb_ary_any_p(int argc, VALUE *argv, VALUE ary) { long i, len = RARRAY_LEN(ary); rb_check_arity(argc, 0, 1); if (!len) return Qfalse; if (argc) { if (rb_block_given_p()) { rb_warn("given block not used"); } for (i = 0; i < RARRAY_LEN(ary); ++i) { if (RTEST(rb_funcall(argv[0], idEqq, 1, RARRAY_AREF(ary, i)))) return Qtrue; } } else if (!rb_block_given_p()) { for (i = 0; i < len; ++i) { if (RTEST(RARRAY_AREF(ary, i))) return Qtrue; } } else { for (i = 0; i < RARRAY_LEN(ary); ++i) { if (RTEST(rb_yield(RARRAY_AREF(ary, i)))) return Qtrue; } } return Qfalse; } |
#assoc(obj) ⇒ nil
Searches through an array whose elements are also arrays comparing obj
with the first element of each contained array using obj.==
.
Returns the first contained array that matches (that is, the first associated array), or nil
if no match is found.
See also Array#rassoc
s1 = [ "colors", "red", "blue", "green" ]
s2 = [ "letters", "a", "b", "c" ]
s3 = "foo"
a = [ s1, s2, s3 ]
a.assoc("letters") #=> [ "letters", "a", "b", "c" ]
a.assoc("foo") #=> nil
4155 4156 4157 4158 4159 4160 4161 4162 4163 4164 4165 4166 4167 4168 |
# File 'array.c', line 4155 VALUE rb_ary_assoc(VALUE ary, VALUE key) { long i; VALUE v; for (i = 0; i < RARRAY_LEN(ary); ++i) { v = rb_check_array_type(RARRAY_AREF(ary, i)); if (!NIL_P(v) && RARRAY_LEN(v) > 0 && rb_equal(RARRAY_AREF(v, 0), key)) return v; } return Qnil; } |
#at(index) ⇒ Object?
Returns the element at index
. A negative index counts from the end of self
. Returns nil
if the index is out of range. See also Array#[].
a = [ "a", "b", "c", "d", "e" ]
a.at(0) #=> "a"
a.at(-1) #=> "e"
1628 1629 1630 1631 1632 |
# File 'array.c', line 1628 VALUE rb_ary_at(VALUE ary, VALUE pos) { return rb_ary_entry(ary, NUM2LONG(pos)); } |
#bsearch {|x| ... } ⇒ Object
By using binary search, finds a value from this array which meets the given condition in O(log n) where n is the size of the array.
You can use this method in two modes: a find-minimum mode and a find-any mode. In either case, the elements of the array must be monotone (or sorted) with respect to the block.
In find-minimum mode (this is a good choice for typical use cases), the block must always return true or false, and there must be an index i (0 <= i <= ary.size) so that:
-
the block returns false for any element whose index is less than i, and
-
the block returns true for any element whose index is greater than or equal to i.
This method returns the i-th element. If i is equal to ary.size, it returns nil.
ary = [0, 4, 7, 10, 12]
ary.bsearch {|x| x >= 4 } #=> 4
ary.bsearch {|x| x >= 6 } #=> 7
ary.bsearch {|x| x >= -1 } #=> 0
ary.bsearch {|x| x >= 100 } #=> nil
In find-any mode (this behaves like libc’s bsearch(3)), the block must always return a number, and there must be two indices i and j (0 <= i <= j <= ary.size) so that:
-
the block returns a positive number for ary if 0 <= k < i,
-
the block returns zero for ary if i <= k < j, and
-
the block returns a negative number for ary if j <= k < ary.size.
Under this condition, this method returns any element whose index is within i…j. If i is equal to j (i.e., there is no element that satisfies the block), this method returns nil.
ary = [0, 4, 7, 10, 12]
# try to find v such that 4 <= v < 8
ary.bsearch {|x| 1 - x / 4 } #=> 4 or 7
# try to find v such that 8 <= v < 10
ary.bsearch {|x| 4 - x / 2 } #=> nil
You must not mix the two modes at a time; the block must always return either true/false, or always return a number. It is undefined which value is actually picked up at each iteration.
2928 2929 2930 2931 2932 2933 2934 2935 2936 2937 |
# File 'array.c', line 2928 static VALUE rb_ary_bsearch(VALUE ary) { VALUE index_result = rb_ary_bsearch_index(ary); if (FIXNUM_P(index_result)) { return rb_ary_entry(ary, FIX2LONG(index_result)); } return index_result; } |
#bsearch_index {|x| ... } ⇒ Integer?
By using binary search, finds an index of a value from this array which meets the given condition in O(log n) where n is the size of the array.
It supports two modes, depending on the nature of the block. They are exactly the same as in the case of the #bsearch method, with the only difference being that this method returns the index of the element instead of the element itself. For more details consult the documentation for #bsearch.
2952 2953 2954 2955 2956 2957 2958 2959 2960 2961 2962 2963 2964 2965 2966 2967 2968 2969 2970 2971 2972 2973 2974 2975 2976 2977 2978 2979 2980 2981 2982 2983 2984 2985 2986 2987 2988 2989 2990 2991 2992 2993 2994 2995 2996 2997 |
# File 'array.c', line 2952 static VALUE rb_ary_bsearch_index(VALUE ary) { long low = 0, high = RARRAY_LEN(ary), mid; int smaller = 0, satisfied = 0; VALUE v, val; RETURN_ENUMERATOR(ary, 0, 0); while (low < high) { mid = low + ((high - low) / 2); val = rb_ary_entry(ary, mid); v = rb_yield(val); if (FIXNUM_P(v)) { if (v == INT2FIX(0)) return INT2FIX(mid); smaller = (SIGNED_VALUE)v < 0; /* Fixnum preserves its sign-bit */ } else if (v == Qtrue) { satisfied = 1; smaller = 1; } else if (v == Qfalse || v == Qnil) { smaller = 0; } else if (rb_obj_is_kind_of(v, rb_cNumeric)) { const VALUE zero = INT2FIX(0); switch (rb_cmpint(rb_funcallv(v, id_cmp, 1, &zero), v, zero)) { case 0: return INT2FIX(mid); case 1: smaller = 1; break; case -1: smaller = 0; } } else { rb_raise(rb_eTypeError, "wrong argument type %"PRIsVALUE " (must be numeric, true, false or nil)", rb_obj_class(v)); } if (smaller) { high = mid; } else { low = mid + 1; } } if (!satisfied) return Qnil; return INT2FIX(low); } |
#clear ⇒ Array
Removes all elements from self
.
a = [ "a", "b", "c", "d", "e" ]
a.clear #=> [ ]
3861 3862 3863 3864 3865 3866 3867 3868 3869 3870 3871 3872 3873 3874 3875 3876 3877 3878 3879 3880 |
# File 'array.c', line 3861 VALUE rb_ary_clear(VALUE ary) { rb_ary_modify_check(ary); if (ARY_SHARED_P(ary)) { if (!ARY_EMBED_P(ary)) { rb_ary_unshare(ary); FL_SET_EMBED(ary); ARY_SET_EMBED_LEN(ary, 0); } } else { ARY_SET_LEN(ary, 0); if (ARY_DEFAULT_SIZE * 2 < ARY_CAPA(ary)) { ary_resize_capa(ary, ARY_DEFAULT_SIZE * 2); } } ary_verify(ary); return ary; } |
#collect {|item| ... } ⇒ Array #map {|item| ... } ⇒ Array #collect ⇒ Enumerator #map ⇒ Enumerator
Invokes the given block once for each element of self
.
Creates a new array containing the values returned by the block.
See also Enumerable#collect.
If no block is given, an Enumerator is returned instead.
a = [ "a", "b", "c", "d" ]
a.collect {|x| x + "!"} #=> ["a!", "b!", "c!", "d!"]
a.map.with_index {|x, i| x * i} #=> ["", "b", "cc", "ddd"]
a #=> ["a", "b", "c", "d"]
3056 3057 3058 3059 3060 3061 3062 3063 3064 3065 3066 3067 3068 |
# File 'array.c', line 3056 static VALUE rb_ary_collect(VALUE ary) { long i; VALUE collect; RETURN_SIZED_ENUMERATOR(ary, 0, 0, ary_enum_length); collect = rb_ary_new2(RARRAY_LEN(ary)); for (i = 0; i < RARRAY_LEN(ary); i++) { rb_ary_push(collect, rb_yield(RARRAY_AREF(ary, i))); } return collect; } |
#collect! {|item| ... } ⇒ Array #map! {|item| ... } ⇒ Array #collect! ⇒ Enumerator #map! ⇒ Enumerator
Invokes the given block once for each element of self
, replacing the element with the value returned by the block.
See also Enumerable#collect.
If no block is given, an Enumerator is returned instead.
a = [ "a", "b", "c", "d" ]
a.map! {|x| x + "!" }
a #=> [ "a!", "b!", "c!", "d!" ]
a.collect!.with_index {|x, i| x[0...i] }
a #=> ["", "b", "c!", "d!"]
3092 3093 3094 3095 3096 3097 3098 3099 3100 3101 3102 3103 |
# File 'array.c', line 3092 static VALUE rb_ary_collect_bang(VALUE ary) { long i; RETURN_SIZED_ENUMERATOR(ary, 0, 0, ary_enum_length); rb_ary_modify(ary); for (i = 0; i < RARRAY_LEN(ary); i++) { rb_ary_store(ary, i, rb_yield(RARRAY_AREF(ary, i))); } return ary; } |
#combination(n) {|c| ... } ⇒ Array #combination(n) ⇒ Enumerator
When invoked with a block, yields all combinations of length n
of elements from the array and then returns the array itself.
The implementation makes no guarantees about the order in which the combinations are yielded.
If no block is given, an Enumerator is returned instead.
Examples:
a = [1, 2, 3, 4]
a.combination(1).to_a #=> [[1],[2],[3],[4]]
a.combination(2).to_a #=> [[1,2],[1,3],[1,4],[2,3],[2,4],[3,4]]
a.combination(3).to_a #=> [[1,2,3],[1,2,4],[1,3,4],[2,3,4]]
a.combination(4).to_a #=> [[1,2,3,4]]
a.combination(0).to_a #=> [[]] # one combination of length 0
a.combination(5).to_a #=> [] # no combinations of length 5
5865 5866 5867 5868 5869 5870 5871 5872 5873 5874 5875 5876 5877 5878 5879 5880 5881 5882 5883 5884 5885 5886 5887 5888 5889 5890 5891 5892 5893 5894 5895 |
# File 'array.c', line 5865 static VALUE rb_ary_combination(VALUE ary, VALUE num) { long i, n, len; n = NUM2LONG(num); RETURN_SIZED_ENUMERATOR(ary, 1, &num, rb_ary_combination_size); len = RARRAY_LEN(ary); if (n < 0 || len < n) { /* yield nothing */ } else if (n == 0) { rb_yield(rb_ary_new2(0)); } else if (n == 1) { for (i = 0; i < RARRAY_LEN(ary); i++) { rb_yield(rb_ary_new3(1, RARRAY_AREF(ary, i))); } } else { VALUE ary0 = ary_make_shared_copy(ary); /* private defensive copy of ary */ volatile VALUE t0; long *stack = ALLOCV_N(long, t0, n+1); RBASIC_CLEAR_CLASS(ary0); combinate0(len, n, stack, ary0); ALLOCV_END(t0); RBASIC_SET_CLASS_RAW(ary0, rb_cArray); } return ary; } |
#compact ⇒ Array
Returns a copy of self
with all nil
elements removed.
[ "a", nil, "b", nil, "c", nil ].compact
#=> [ "a", "b", "c" ]
5088 5089 5090 5091 5092 5093 5094 |
# File 'array.c', line 5088 static VALUE rb_ary_compact(VALUE ary) { ary = rb_ary_dup(ary); rb_ary_compact_bang(ary); return ary; } |
#compact! ⇒ Array?
Removes nil
elements from the array.
Returns nil
if no changes were made, otherwise returns the array.
[ "a", nil, "b", nil, "c" ].compact! #=> [ "a", "b", "c" ]
[ "a", "b", "c" ].compact! #=> nil
5055 5056 5057 5058 5059 5060 5061 5062 5063 5064 5065 5066 5067 5068 5069 5070 5071 5072 5073 5074 5075 5076 |
# File 'array.c', line 5055 static VALUE rb_ary_compact_bang(VALUE ary) { VALUE *p, *t, *end; long n; rb_ary_modify(ary); p = t = (VALUE *)RARRAY_CONST_PTR_TRANSIENT(ary); /* WB: no new reference */ end = p + RARRAY_LEN(ary); while (t < end) { if (NIL_P(*t)) t++; else *p++ = *t++; } n = p - RARRAY_CONST_PTR_TRANSIENT(ary); if (RARRAY_LEN(ary) == n) { return Qnil; } ary_resize_smaller(ary, n); return ary; } |
#concat(other_ary1, other_ary2, ...) ⇒ Array
Appends the elements of other_ary
s to self
.
[ "a", "b" ].concat( ["c", "d"]) #=> [ "a", "b", "c", "d" ]
[ "a" ].concat( ["b"], ["c", "d"]) #=> [ "a", "b", "c", "d" ]
[ "a" ].concat #=> [ "a" ]
a = [ 1, 2, 3 ]
a.concat( [ 4, 5 ])
a #=> [ 1, 2, 3, 4, 5 ]
a = [ 1, 2 ]
a.concat(a, a) #=> [1, 2, 1, 2, 1, 2]
See also Array#+.
4047 4048 4049 4050 4051 4052 4053 4054 4055 4056 4057 4058 4059 4060 4061 4062 4063 4064 4065 4066 |
# File 'array.c', line 4047 static VALUE rb_ary_concat_multi(int argc, VALUE *argv, VALUE ary) { rb_ary_modify_check(ary); if (argc == 1) { rb_ary_concat(ary, argv[0]); } else if (argc > 1) { int i; VALUE args = rb_ary_tmp_new(argc); for (i = 0; i < argc; i++) { rb_ary_concat(args, argv[i]); } ary_append(ary, args); } ary_verify(ary); return ary; } |
#count ⇒ Integer #count(obj) ⇒ Integer #count {|item| ... } ⇒ Integer
Returns the number of elements.
If an argument is given, counts the number of elements which equal obj
using ==
.
If a block is given, counts the number of elements for which the block returns a true value.
ary = [1, 2, 4, 2]
ary.count #=> 4
ary.count(2) #=> 2
ary.count {|x| x%2 == 0} #=> 3
5117 5118 5119 5120 5121 5122 5123 5124 5125 5126 5127 5128 5129 5130 5131 5132 5133 5134 5135 5136 5137 5138 5139 5140 5141 5142 5143 5144 5145 |
# File 'array.c', line 5117 static VALUE rb_ary_count(int argc, VALUE *argv, VALUE ary) { long i, n = 0; if (rb_check_arity(argc, 0, 1) == 0) { VALUE v; if (!rb_block_given_p()) return LONG2NUM(RARRAY_LEN(ary)); for (i = 0; i < RARRAY_LEN(ary); i++) { v = RARRAY_AREF(ary, i); if (RTEST(rb_yield(v))) n++; } } else { VALUE obj = argv[0]; if (rb_block_given_p()) { rb_warn("given block not used"); } for (i = 0; i < RARRAY_LEN(ary); i++) { if (rb_equal(RARRAY_AREF(ary, i), obj)) n++; } } return LONG2NUM(n); } |
#cycle(n = nil) {|obj| ... } ⇒ nil #cycle(n = nil) ⇒ Enumerator
Calls the given block for each element n
times or forever if nil
is given.
Does nothing if a non-positive number is given or the array is empty.
Returns nil
if the loop has finished without getting interrupted.
If no block is given, an Enumerator is returned instead.
a = ["a", "b", "c"]
a.cycle {|x| puts x} # print, a, b, c, a, b, c,.. forever.
a.cycle(2) {|x| puts x} # print, a, b, c, a, b, c.
5601 5602 5603 5604 5605 5606 5607 5608 5609 5610 5611 5612 5613 5614 5615 5616 5617 5618 5619 5620 5621 5622 5623 |
# File 'array.c', line 5601 static VALUE rb_ary_cycle(int argc, VALUE *argv, VALUE ary) { long n, i; rb_check_arity(argc, 0, 1); RETURN_SIZED_ENUMERATOR(ary, argc, argv, rb_ary_cycle_size); if (argc == 0 || NIL_P(argv[0])) { n = -1; } else { n = NUM2LONG(argv[0]); if (n <= 0) return Qnil; } while (RARRAY_LEN(ary) > 0 && (n < 0 || 0 < n--)) { for (i=0; i<RARRAY_LEN(ary); i++) { rb_yield(RARRAY_AREF(ary, i)); } } return Qnil; } |
#deconstruct ⇒ Object
6674 6675 6676 6677 6678 |
# File 'array.c', line 6674 static VALUE rb_ary_deconstruct(VALUE ary) { return ary; } |
#delete(obj) ⇒ nil #delete(obj) { ... } ⇒ Object
Deletes all items from self
that are equal to obj
.
Returns the last deleted item, or nil
if no matching item is found.
If the optional code block is given, the result of the block is returned if the item is not found. (To remove nil
elements and get an informative return value, use Array#compact!)
a = [ "a", "b", "b", "b", "c" ]
a.delete("b") #=> "b"
a #=> ["a", "c"]
a.delete("z") #=> nil
a.delete("z") {"not found"} #=> "not found"
3364 3365 3366 3367 3368 3369 3370 3371 3372 3373 3374 3375 3376 3377 3378 3379 3380 3381 3382 3383 3384 3385 3386 3387 3388 3389 3390 3391 3392 3393 |
# File 'array.c', line 3364 VALUE rb_ary_delete(VALUE ary, VALUE item) { VALUE v = item; long i1, i2; for (i1 = i2 = 0; i1 < RARRAY_LEN(ary); i1++) { VALUE e = RARRAY_AREF(ary, i1); if (rb_equal(e, item)) { v = e; continue; } if (i1 != i2) { rb_ary_store(ary, i2, e); } i2++; } if (RARRAY_LEN(ary) == i2) { if (rb_block_given_p()) { return rb_yield(item); } return Qnil; } ary_resize_smaller(ary, i2); ary_verify(ary); return v; } |
#delete_at(index) ⇒ Object?
Deletes the element at the specified index
, returning that element, or nil
if the index
is out of range.
See also Array#slice!
a = ["ant", "bat", "cat", "dog"]
a.delete_at(2) #=> "cat"
a #=> ["ant", "bat", "dog"]
a.delete_at(99) #=> nil
3455 3456 3457 3458 3459 |
# File 'array.c', line 3455 static VALUE rb_ary_delete_at_m(VALUE ary, VALUE pos) { return rb_ary_delete_at(ary, NUM2LONG(pos)); } |
#delete_if {|item| ... } ⇒ Array #delete_if ⇒ Enumerator
Deletes every element of self
for which block evaluates to true
.
The array is changed instantly every time the block is called, not after the iteration is over.
See also Array#reject!
If no block is given, an Enumerator is returned instead.
scores = [ 97, 42, 75 ]
scores.delete_if {|score| score < 80 } #=> [97]
3638 3639 3640 3641 3642 3643 3644 3645 |
# File 'array.c', line 3638 static VALUE rb_ary_delete_if(VALUE ary) { ary_verify(ary); RETURN_SIZED_ENUMERATOR(ary, 0, 0, ary_enum_length); ary_reject_bang(ary); return ary; } |
#difference(other_ary1, other_ary2, ...) ⇒ Array
Array Difference
Returns a new array that is a copy of the original array, removing all occurrences of any item that also appear in other_ary
. The order is preserved from the original array.
It compares elements using their #hash and #eql? methods for efficiency.
[ 1, 1, 2, 2, 3, 3, 4, 5 ].difference([ 1, 2, 4 ]) #=> [ 3, 3, 5 ]
Note that while 1 and 2 were only present once in the array argument, and were present twice in the receiver array, all occurrences of each Integer are removed in the returned array.
Multiple array arguments can be supplied and all occurrences of any element in those supplied arrays that match the receiver will be removed from the returned array.
[ 1, 'c', :s, 'yep' ].difference([ 1 ], [ 'a', 'c' ]) #=> [ :s, "yep" ]
If you need set-like behavior, see the library class Set.
See also Array#-.
4575 4576 4577 4578 4579 4580 4581 4582 4583 4584 4585 4586 4587 4588 4589 4590 4591 4592 4593 4594 4595 4596 4597 4598 4599 4600 4601 4602 4603 4604 4605 4606 4607 4608 4609 |
# File 'array.c', line 4575 static VALUE rb_ary_difference_multi(int argc, VALUE *argv, VALUE ary) { VALUE ary_diff; long i, length; volatile VALUE t0; bool *is_hash = ALLOCV_N(bool, t0, argc); ary_diff = rb_ary_new(); length = RARRAY_LEN(ary); for (i = 0; i < argc; i++) { argv[i] = to_ary(argv[i]); is_hash[i] = (length > SMALL_ARRAY_LEN && RARRAY_LEN(argv[i]) > SMALL_ARRAY_LEN); if (is_hash[i]) argv[i] = ary_make_hash(argv[i]); } for (i = 0; i < RARRAY_LEN(ary); i++) { int j; VALUE elt = rb_ary_elt(ary, i); for (j = 0; j < argc; j++) { if (is_hash[j]) { if (rb_hash_stlike_lookup(argv[j], RARRAY_AREF(ary, i), NULL)) break; } else { if (rb_ary_includes_by_eql(argv[j], elt)) break; } } if (j == argc) rb_ary_push(ary_diff, elt); } ALLOCV_END(t0); return ary_diff; } |
#dig(idx, ...) ⇒ Object
Extracts the nested value specified by the sequence of idx objects by calling dig
at each step, returning nil
if any intermediate step is nil
.
a = [[1, [2, 3]]]
a.dig(0, 1, 1) #=> 3
a.dig(1, 2, 3) #=> nil
a.dig(0, 0, 0) #=> TypeError: Integer does not have #dig method
[42, {foo: :bar}].dig(1, :foo) #=> :bar
6492 6493 6494 6495 6496 6497 6498 6499 6500 |
# File 'array.c', line 6492 static VALUE rb_ary_dig(int argc, VALUE *argv, VALUE self) { rb_check_arity(argc, 1, UNLIMITED_ARGUMENTS); self = rb_ary_at(self, *argv); if (!--argc) return self; ++argv; return rb_obj_dig(argc, argv, self, Qnil); } |
#drop(n) ⇒ Array
Drops first n
elements from ary
and returns the rest of the elements in an array.
If a negative number is given, raises an ArgumentError.
See also Array#take
a = [1, 2, 3, 4, 5, 0]
a.drop(3) #=> [4, 5, 0]
6278 6279 6280 6281 6282 6283 6284 6285 6286 6287 6288 6289 6290 |
# File 'array.c', line 6278 static VALUE rb_ary_drop(VALUE ary, VALUE n) { VALUE result; long pos = NUM2LONG(n); if (pos < 0) { rb_raise(rb_eArgError, "attempt to drop negative size"); } result = rb_ary_subseq(ary, pos, RARRAY_LEN(ary)); if (result == Qnil) result = rb_ary_new(); return result; } |
#drop_while {|obj| ... } ⇒ Array #drop_while ⇒ Enumerator
Drops elements up to, but not including, the first element for which the block returns nil
or false
and returns an array containing the remaining elements.
If no block is given, an Enumerator is returned instead.
See also Array#take_while
a = [1, 2, 3, 4, 5, 0]
a.drop_while {|i| i < 3 } #=> [3, 4, 5, 0]
6310 6311 6312 6313 6314 6315 6316 6317 6318 6319 6320 |
# File 'array.c', line 6310 static VALUE rb_ary_drop_while(VALUE ary) { long i; RETURN_ENUMERATOR(ary, 0, 0); for (i = 0; i < RARRAY_LEN(ary); i++) { if (!RTEST(rb_yield(RARRAY_AREF(ary, i)))) break; } return rb_ary_drop(ary, LONG2FIX(i)); } |
#each {|item| ... } ⇒ Array #each ⇒ Enumerator
Calls the given block once for each element in self
, passing that element as a parameter. Returns the array itself.
If no block is given, an Enumerator is returned.
a = [ "a", "b", "c" ]
a.each {|x| print x, " -- " }
produces:
a -- b -- c --
2128 2129 2130 2131 2132 2133 2134 2135 2136 2137 2138 |
# File 'array.c', line 2128 VALUE rb_ary_each(VALUE ary) { long i; ary_verify(ary); RETURN_SIZED_ENUMERATOR(ary, 0, 0, ary_enum_length); for (i=0; i<RARRAY_LEN(ary); i++) { rb_yield(RARRAY_AREF(ary, i)); } return ary; } |
#each_index {|index| ... } ⇒ Array #each_index ⇒ Enumerator
Same as Array#each, but passes the index
of the element instead of the element itself.
An Enumerator is returned if no block is given.
a = [ "a", "b", "c" ]
a.each_index {|x| print x, " -- " }
produces:
0 -- 1 -- 2 --
2158 2159 2160 2161 2162 2163 2164 2165 2166 2167 2168 |
# File 'array.c', line 2158 static VALUE rb_ary_each_index(VALUE ary) { long i; RETURN_SIZED_ENUMERATOR(ary, 0, 0, ary_enum_length); for (i=0; i<RARRAY_LEN(ary); i++) { rb_yield(LONG2NUM(i)); } return ary; } |
#empty? ⇒ Boolean
Returns true
if self
contains no elements.
[].empty? #=> true
2229 2230 2231 2232 2233 2234 2235 |
# File 'array.c', line 2229 static VALUE rb_ary_empty_p(VALUE ary) { if (RARRAY_LEN(ary) == 0) return Qtrue; return Qfalse; } |
#eql?(other) ⇒ Boolean
Returns true
if self
and other
are the same object, or are both arrays with the same content (according to Object#eql?).
4288 4289 4290 4291 4292 4293 4294 4295 4296 |
# File 'array.c', line 4288 static VALUE rb_ary_eql(VALUE ary1, VALUE ary2) { if (ary1 == ary2) return Qtrue; if (!RB_TYPE_P(ary2, T_ARRAY)) return Qfalse; if (RARRAY_LEN(ary1) != RARRAY_LEN(ary2)) return Qfalse; if (RARRAY_CONST_PTR_TRANSIENT(ary1) == RARRAY_CONST_PTR_TRANSIENT(ary2)) return Qtrue; return rb_exec_recursive_paired(recursive_eql, ary1, ary2, ary2); } |
#fetch(index) ⇒ Object #fetch(index, default) ⇒ Object #fetch(index) {|index| ... } ⇒ Object
Tries to return the element at position index
, but throws an IndexError exception if the referenced index
lies outside of the array bounds. This error can be prevented by supplying a second argument, which will act as a default
value.
Alternatively, if a block is given it will only be executed when an invalid index
is referenced.
Negative values of index
count from the end of the array.
a = [ 11, 22, 33, 44 ]
a.fetch(1) #=> 22
a.fetch(-1) #=> 44
a.fetch(4, 'cat') #=> "cat"
a.fetch(100) {|i| puts "#{i} is out of bounds"}
#=> "100 is out of bounds"
1713 1714 1715 1716 1717 1718 1719 1720 1721 1722 1723 1724 1725 1726 1727 1728 1729 1730 1731 1732 1733 1734 1735 1736 1737 1738 1739 |
# File 'array.c', line 1713 static VALUE rb_ary_fetch(int argc, VALUE *argv, VALUE ary) { VALUE pos, ifnone; long block_given; long idx; rb_scan_args(argc, argv, "11", &pos, &ifnone); block_given = rb_block_given_p(); if (block_given && argc == 2) { rb_warn("block supersedes default value argument"); } idx = NUM2LONG(pos); if (idx < 0) { idx += RARRAY_LEN(ary); } if (idx < 0 || RARRAY_LEN(ary) <= idx) { if (block_given) return rb_yield(pos); if (argc == 1) { rb_raise(rb_eIndexError, "index %ld outside of array bounds: %ld...%ld", idx - (idx < 0 ? RARRAY_LEN(ary) : 0), -RARRAY_LEN(ary), RARRAY_LEN(ary)); } return ifnone; } return RARRAY_AREF(ary, idx); } |
#fill(obj) ⇒ Array #fill(obj, start[, length]) ⇒ Array #fill(obj, range) ⇒ Array #fill {|index| ... } ⇒ Array #fill(start[, length]) {|index| ... } ⇒ Array #fill(range) {|index| ... } ⇒ Array
The first three forms set the selected elements of self
(which may be the entire array) to obj
.
A start
of nil
is equivalent to zero.
A length
of nil
is equivalent to the length of the array.
The last three forms fill the array with the value of the given block, which is passed the absolute index of each element to be filled.
Negative values of start
count from the end of the array, where -1
is the last element.
a = [ "a", "b", "c", "d" ]
a.fill("x") #=> ["x", "x", "x", "x"]
a.fill("z", 2, 2) #=> ["x", "x", "z", "z"]
a.fill("y", 0..1) #=> ["y", "y", "z", "z"]
a.fill {|i| i*i} #=> [0, 1, 4, 9]
a.fill(-2) {|i| i*i*i} #=> [0, 1, 8, 27]
3912 3913 3914 3915 3916 3917 3918 3919 3920 3921 3922 3923 3924 3925 3926 3927 3928 3929 3930 3931 3932 3933 3934 3935 3936 3937 3938 3939 3940 3941 3942 3943 3944 3945 3946 3947 3948 3949 3950 3951 3952 3953 3954 3955 3956 3957 3958 3959 3960 3961 3962 3963 3964 3965 3966 3967 3968 3969 3970 3971 3972 3973 3974 |
# File 'array.c', line 3912 static VALUE rb_ary_fill(int argc, VALUE *argv, VALUE ary) { VALUE item = Qundef, arg1, arg2; long beg = 0, end = 0, len = 0; if (rb_block_given_p()) { rb_scan_args(argc, argv, "02", &arg1, &arg2); argc += 1; /* hackish */ } else { rb_scan_args(argc, argv, "12", &item, &arg1, &arg2); } switch (argc) { case 1: beg = 0; len = RARRAY_LEN(ary); break; case 2: if (rb_range_beg_len(arg1, &beg, &len, RARRAY_LEN(ary), 1)) { break; } /* fall through */ case 3: beg = NIL_P(arg1) ? 0 : NUM2LONG(arg1); if (beg < 0) { beg = RARRAY_LEN(ary) + beg; if (beg < 0) beg = 0; } len = NIL_P(arg2) ? RARRAY_LEN(ary) - beg : NUM2LONG(arg2); break; } rb_ary_modify(ary); if (len < 0) { return ary; } if (beg >= ARY_MAX_SIZE || len > ARY_MAX_SIZE - beg) { rb_raise(rb_eArgError, "argument too big"); } end = beg + len; if (RARRAY_LEN(ary) < end) { if (end >= ARY_CAPA(ary)) { ary_resize_capa(ary, end); } ary_mem_clear(ary, RARRAY_LEN(ary), end - RARRAY_LEN(ary)); ARY_SET_LEN(ary, end); } if (item == Qundef) { VALUE v; long i; for (i=beg; i<end; i++) { v = rb_yield(LONG2NUM(i)); if (i>=RARRAY_LEN(ary)) break; ARY_SET(ary, i, v); } } else { ary_memfill(ary, beg, len, item); } return ary; } |
#select {|item| ... } ⇒ Array #select ⇒ Enumerator #filter {|item| ... } ⇒ Array #filter ⇒ Enumerator
Returns a new array containing all elements of ary
for which the given block
returns a true value.
If no block is given, an Enumerator is returned instead.
[1,2,3,4,5].select {|num| num.even? } #=> [2, 4]
a = %w[ a b c d e f ]
a.select {|v| v =~ /[aeiou]/ } #=> ["a", "e"]
See also Enumerable#select.
Array#filter is an alias for Array#select.
3212 3213 3214 3215 3216 3217 3218 3219 3220 3221 3222 3223 3224 3225 3226 |
# File 'array.c', line 3212 static VALUE rb_ary_select(VALUE ary) { VALUE result; long i; RETURN_SIZED_ENUMERATOR(ary, 0, 0, ary_enum_length); result = rb_ary_new2(RARRAY_LEN(ary)); for (i = 0; i < RARRAY_LEN(ary); i++) { if (RTEST(rb_yield(RARRAY_AREF(ary, i)))) { rb_ary_push(result, rb_ary_elt(ary, i)); } } return result; } |
#select! {|item| ... } ⇒ Array? #select! ⇒ Enumerator #filter! {|item| ... } ⇒ Array? #filter! ⇒ Enumerator
Invokes the given block passing in successive elements from self
, deleting elements for which the block returns a false
value.
The array may not be changed instantly every time the block is called.
If changes were made, it will return self
, otherwise it returns nil
.
If no block is given, an Enumerator is returned instead.
See also Array#keep_if.
Array#filter! is an alias for Array#select!.
3293 3294 3295 3296 3297 3298 3299 3300 3301 3302 3303 3304 |
# File 'array.c', line 3293 static VALUE rb_ary_select_bang(VALUE ary) { struct select_bang_arg args; RETURN_SIZED_ENUMERATOR(ary, 0, 0, ary_enum_length); rb_ary_modify(ary); args.ary = ary; args.len[0] = args.len[1] = 0; return rb_ensure(select_bang_i, (VALUE)&args, select_bang_ensure, (VALUE)&args); } |
#find_index(obj) ⇒ Integer? #find_index {|item| ... } ⇒ Integer? #find_index ⇒ Enumerator #index(obj) ⇒ Integer? #index {|item| ... } ⇒ Integer? #index ⇒ Enumerator
Returns the index of the first object in ary
such that the object is ==
to obj
.
If a block is given instead of an argument, returns the index of the first object for which the block returns true
. Returns nil
if no match is found.
See also Array#rindex.
An Enumerator is returned if neither a block nor argument is given.
a = [ "a", "b", "c" ]
a.index("b") #=> 1
a.index("z") #=> nil
a.index {|x| x == "b"} #=> 1
1767 1768 1769 1770 1771 1772 1773 1774 1775 1776 1777 1778 1779 1780 1781 1782 1783 1784 1785 1786 1787 1788 1789 1790 1791 1792 1793 |
# File 'array.c', line 1767 static VALUE rb_ary_index(int argc, VALUE *argv, VALUE ary) { VALUE val; long i; if (argc == 0) { RETURN_ENUMERATOR(ary, 0, 0); for (i=0; i<RARRAY_LEN(ary); i++) { if (RTEST(rb_yield(RARRAY_AREF(ary, i)))) { return LONG2NUM(i); } } return Qnil; } rb_check_arity(argc, 0, 1); val = argv[0]; if (rb_block_given_p()) rb_warn("given block not used"); for (i=0; i<RARRAY_LEN(ary); i++) { VALUE e = RARRAY_AREF(ary, i); if (rb_equal(e, val)) { return LONG2NUM(i); } } return Qnil; } |
#first ⇒ Object? #first(n) ⇒ Array
Returns the first element, or the first n
elements, of the array. If the array is empty, the first form returns nil
, and the second form returns an empty array. See also Array#last for the opposite effect.
a = [ "q", "r", "s", "t" ]
a.first #=> "q"
a.first(2) #=> ["q", "r"]
1649 1650 1651 1652 1653 1654 1655 1656 1657 1658 1659 |
# File 'array.c', line 1649 static VALUE rb_ary_first(int argc, VALUE *argv, VALUE ary) { if (argc == 0) { if (RARRAY_LEN(ary) == 0) return Qnil; return RARRAY_AREF(ary, 0); } else { return ary_take_first_or_last(argc, argv, ary, ARY_TAKE_FIRST); } } |
#flatten ⇒ Array #flatten(level) ⇒ Array
Returns a new array that is a one-dimensional flattening of self
(recursively).
That is, for every element that is an array, extract its elements into the new array.
The optional level
argument determines the level of recursion to flatten.
s = [ 1, 2, 3 ] #=> [1, 2, 3]
t = [ 4, 5, 6, [7, 8] ] #=> [4, 5, 6, [7, 8]]
a = [ s, t, 9, 10 ] #=> [[1, 2, 3], [4, 5, 6, [7, 8]], 9, 10]
a.flatten #=> [1, 2, 3, 4, 5, 6, 7, 8, 9, 10]
a = [ 1, 2, [3, [4, 5] ] ]
a.flatten(1) #=> [1, 2, 3, [4, 5]]
5295 5296 5297 5298 5299 5300 5301 5302 5303 5304 5305 5306 5307 5308 5309 5310 5311 5312 |
# File 'array.c', line 5295 static VALUE rb_ary_flatten(int argc, VALUE *argv, VALUE ary) { int level = -1; VALUE result; if (rb_check_arity(argc, 0, 1) && !NIL_P(argv[0])) { level = NUM2INT(argv[0]); if (level == 0) return ary_make_shared_copy(ary); } result = flatten(ary, level); if (result == ary) { result = ary_make_shared_copy(ary); } return result; } |
#flatten! ⇒ Array? #flatten!(level) ⇒ Array?
Flattens self
in place.
Returns nil
if no modifications were made (i.e., the array contains no subarrays.)
The optional level
argument determines the level of recursion to flatten.
a = [ 1, 2, [3, [4, 5] ] ]
a.flatten! #=> [1, 2, 3, 4, 5]
a.flatten! #=> nil
a #=> [1, 2, 3, 4, 5]
a = [ 1, 2, [3, [4, 5] ] ]
a.flatten!(1) #=> [1, 2, 3, [4, 5]]
5251 5252 5253 5254 5255 5256 5257 5258 5259 5260 5261 5262 5263 5264 5265 5266 5267 5268 5269 5270 5271 |
# File 'array.c', line 5251 static VALUE rb_ary_flatten_bang(int argc, VALUE *argv, VALUE ary) { int mod = 0, level = -1; VALUE result, lv; lv = (rb_check_arity(argc, 0, 1) ? argv[0] : Qnil); rb_ary_modify_check(ary); if (!NIL_P(lv)) level = NUM2INT(lv); if (level == 0) return Qnil; result = flatten(ary, level); if (result == ary) { return Qnil; } if (!(mod = ARY_EMBED_P(result))) rb_obj_freeze(result); rb_ary_replace(ary, result); if (mod) ARY_SET_EMBED_LEN(result, 0); return ary; } |
#hash ⇒ Integer
Compute a hash-code for this array.
Two arrays with the same content will have the same hash code (and will compare using #eql?).
See also Object#hash.
4310 4311 4312 4313 4314 4315 4316 4317 4318 4319 4320 4321 4322 4323 4324 4325 |
# File 'array.c', line 4310 static VALUE rb_ary_hash(VALUE ary) { long i; st_index_t h; VALUE n; h = rb_hash_start(RARRAY_LEN(ary)); h = rb_hash_uint(h, (st_index_t)rb_ary_hash); for (i=0; i<RARRAY_LEN(ary); i++) { n = rb_hash(RARRAY_AREF(ary, i)); h = rb_hash_uint(h, NUM2LONG(n)); } h = rb_hash_end(h); return ST2FIX(h); } |
#include?(object) ⇒ Boolean
Returns true
if the given object
is present in self
(that is, if any element ==
object
), otherwise returns false
.
a = [ "a", "b", "c" ]
a.include?("b") #=> true
a.include?("z") #=> false
4339 4340 4341 4342 4343 4344 4345 4346 4347 4348 4349 4350 4351 4352 |
# File 'array.c', line 4339 VALUE rb_ary_includes(VALUE ary, VALUE item) { long i; VALUE e; for (i=0; i<RARRAY_LEN(ary); i++) { e = RARRAY_AREF(ary, i); if (rb_equal(e, item)) { return Qtrue; } } return Qfalse; } |
#find_index(obj) ⇒ Integer? #find_index {|item| ... } ⇒ Integer? #find_index ⇒ Enumerator #index(obj) ⇒ Integer? #index {|item| ... } ⇒ Integer? #index ⇒ Enumerator
Returns the index of the first object in ary
such that the object is ==
to obj
.
If a block is given instead of an argument, returns the index of the first object for which the block returns true
. Returns nil
if no match is found.
See also Array#rindex.
An Enumerator is returned if neither a block nor argument is given.
a = [ "a", "b", "c" ]
a.index("b") #=> 1
a.index("z") #=> nil
a.index {|x| x == "b"} #=> 1
1767 1768 1769 1770 1771 1772 1773 1774 1775 1776 1777 1778 1779 1780 1781 1782 1783 1784 1785 1786 1787 1788 1789 1790 1791 1792 1793 |
# File 'array.c', line 1767 static VALUE rb_ary_index(int argc, VALUE *argv, VALUE ary) { VALUE val; long i; if (argc == 0) { RETURN_ENUMERATOR(ary, 0, 0); for (i=0; i<RARRAY_LEN(ary); i++) { if (RTEST(rb_yield(RARRAY_AREF(ary, i)))) { return LONG2NUM(i); } } return Qnil; } rb_check_arity(argc, 0, 1); val = argv[0]; if (rb_block_given_p()) rb_warn("given block not used"); for (i=0; i<RARRAY_LEN(ary); i++) { VALUE e = RARRAY_AREF(ary, i); if (rb_equal(e, val)) { return LONG2NUM(i); } } return Qnil; } |
#replace(other_ary) ⇒ Array #initialize_copy(other_ary) ⇒ Object
Replaces the contents of self
with the contents of other_ary
, truncating or expanding if necessary.
a = [ "a", "b", "c", "d", "e" ]
a.replace([ "x", "y", "z" ]) #=> ["x", "y", "z"]
a #=> ["x", "y", "z"]
3810 3811 3812 3813 3814 3815 3816 3817 3818 3819 3820 3821 3822 3823 3824 3825 3826 3827 3828 3829 3830 3831 3832 3833 3834 3835 3836 3837 3838 3839 3840 3841 3842 3843 3844 3845 3846 3847 3848 3849 |
# File 'array.c', line 3810 VALUE rb_ary_replace(VALUE copy, VALUE orig) { rb_ary_modify_check(copy); orig = to_ary(orig); if (copy == orig) return copy; if (RARRAY_LEN(orig) <= RARRAY_EMBED_LEN_MAX) { VALUE shared_root = 0; if (ARY_OWNS_HEAP_P(copy)) { ary_heap_free(copy); } else if (ARY_SHARED_P(copy)) { shared_root = ARY_SHARED_ROOT(copy); FL_UNSET_SHARED(copy); } FL_SET_EMBED(copy); ary_memcpy(copy, 0, RARRAY_LEN(orig), RARRAY_CONST_PTR_TRANSIENT(orig)); if (shared_root) { rb_ary_decrement_share(shared_root); } ARY_SET_LEN(copy, RARRAY_LEN(orig)); } else { VALUE shared_root = ary_make_shared(orig); if (ARY_OWNS_HEAP_P(copy)) { ary_heap_free(copy); } else { rb_ary_unshare_safe(copy); } FL_UNSET_EMBED(copy); ARY_SET_PTR(copy, ARY_HEAP_PTR(orig)); ARY_SET_LEN(copy, ARY_HEAP_LEN(orig)); rb_ary_set_shared(copy, shared_root); } ary_verify(copy); return copy; } |
#insert(index, obj...) ⇒ Array
Inserts the given values before the element with the given index
.
Negative indices count backwards from the end of the array, where -1
is the last element. If a negative index is used, the given values will be inserted after that element, so using an index of -1
will insert the values at the end of the array.
a = %w{ a b c d }
a.insert(2, 99) #=> ["a", "b", 99, "c", "d"]
a.insert(-2, 1, 2, 3) #=> ["a", "b", 99, "c", 1, 2, 3, "d"]
2077 2078 2079 2080 2081 2082 2083 2084 2085 2086 2087 2088 2089 2090 2091 2092 2093 2094 2095 2096 2097 2098 2099 |
# File 'array.c', line 2077 static VALUE rb_ary_insert(int argc, VALUE *argv, VALUE ary) { long pos; rb_check_arity(argc, 1, UNLIMITED_ARGUMENTS); rb_ary_modify_check(ary); pos = NUM2LONG(argv[0]); if (argc == 1) return ary; if (pos == -1) { pos = RARRAY_LEN(ary); } else if (pos < 0) { long minpos = -RARRAY_LEN(ary) - 1; if (pos < minpos) { rb_raise(rb_eIndexError, "index %ld too small for array; minimum: %ld", pos, minpos); } pos++; } rb_ary_splice(ary, pos, 0, argv + 1, argc - 1); return ary; } |
#inspect ⇒ String #to_s ⇒ String Also known as: to_s
Creates a string representation of self
, by calling #inspect on each element.
[ "a", "b", "c" ].to_s #=> "[\"a\", \"b\", \"c\"]"
2445 2446 2447 2448 2449 2450 |
# File 'array.c', line 2445 static VALUE rb_ary_inspect(VALUE ary) { if (RARRAY_LEN(ary) == 0) return rb_usascii_str_new2("[]"); return rb_exec_recursive(inspect_ary, ary, 0); } |
#intersection(other_ary1, other_ary2, ...) ⇒ Array
Set Intersection — Returns a new array containing unique elements common to self
and other_ary
s. Order is preserved from the original array.
It compares elements using their #hash and #eql? methods for efficiency.
[ 1, 1, 3, 5 ].intersection([ 3, 2, 1 ]) # => [ 1, 3 ]
[ "a", "b", "z" ].intersection([ "a", "b", "c" ], [ "b" ]) # => [ "b" ]
[ "a" ].intersection #=> [ "a" ]
See also Array#&.
4680 4681 4682 4683 4684 4685 4686 4687 4688 4689 4690 4691 |
# File 'array.c', line 4680 static VALUE rb_ary_intersection_multi(int argc, VALUE *argv, VALUE ary) { VALUE result = rb_ary_dup(ary); int i; for (i = 0; i < argc; i++) { result = rb_ary_and(result, argv[i]); } return result; } |
#join(separator = $,) ⇒ String
Returns a string created by converting each element of the array to a string, separated by the given separator
. If the separator
is nil
, it uses current $,
. If both the separator
and $,
are nil
, it uses an empty string.
[ "a", "b", "c" ].join #=> "abc"
[ "a", "b", "c" ].join("-") #=> "a-b-c"
For nested arrays, join is applied recursively:
[ "a", [1, 2, [:x, :y]], "b" ].join("-") #=> "a-1-2-x-y-b"
2401 2402 2403 2404 2405 2406 2407 2408 2409 2410 2411 2412 2413 2414 |
# File 'array.c', line 2401 static VALUE rb_ary_join_m(int argc, VALUE *argv, VALUE ary) { VALUE sep; if (rb_check_arity(argc, 0, 1) == 0 || NIL_P(sep = argv[0])) { sep = rb_output_fs; if (!NIL_P(sep)) { rb_warn("$, is set to non-nil value"); } } return rb_ary_join(ary, sep); } |
#keep_if {|item| ... } ⇒ Array #keep_if ⇒ Enumerator
Deletes every element of self
for which the given block evaluates to false
, and returns self
.
If no block is given, an Enumerator is returned instead.
a = %w[ a b c d e f ]
a.keep_if {|v| v =~ /[aeiou]/ } #=> ["a", "e"]
a #=> ["a", "e"]
See also Array#select!.
3323 3324 3325 3326 3327 3328 3329 |
# File 'array.c', line 3323 static VALUE rb_ary_keep_if(VALUE ary) { RETURN_SIZED_ENUMERATOR(ary, 0, 0, ary_enum_length); rb_ary_select_bang(ary); return ary; } |
#last ⇒ Object? #last(n) ⇒ Array
Returns the last element(s) of self
. If the array is empty, the first form returns nil
.
See also Array#first for the opposite effect.
a = [ "w", "x", "y", "z" ]
a.last #=> "z"
a.last(2) #=> ["y", "z"]
1676 1677 1678 1679 1680 1681 1682 1683 1684 1685 1686 1687 |
# File 'array.c', line 1676 VALUE rb_ary_last(int argc, const VALUE *argv, VALUE ary) { if (argc == 0) { long len = RARRAY_LEN(ary); if (len == 0) return Qnil; return RARRAY_AREF(ary, len-1); } else { return ary_take_first_or_last(argc, argv, ary, ARY_TAKE_LAST); } } |
#length ⇒ Integer Also known as: size
Returns the number of elements in self
. May be zero.
[ 1, 2, 3, 4, 5 ].length #=> 5
[].length #=> 0
2213 2214 2215 2216 2217 2218 |
# File 'array.c', line 2213 static VALUE rb_ary_length(VALUE ary) { long len = RARRAY_LEN(ary); return LONG2NUM(len); } |
#collect {|item| ... } ⇒ Array #map {|item| ... } ⇒ Array #collect ⇒ Enumerator #map ⇒ Enumerator
Invokes the given block once for each element of self
.
Creates a new array containing the values returned by the block.
See also Enumerable#collect.
If no block is given, an Enumerator is returned instead.
a = [ "a", "b", "c", "d" ]
a.collect {|x| x + "!"} #=> ["a!", "b!", "c!", "d!"]
a.map.with_index {|x, i| x * i} #=> ["", "b", "cc", "ddd"]
a #=> ["a", "b", "c", "d"]
3056 3057 3058 3059 3060 3061 3062 3063 3064 3065 3066 3067 3068 |
# File 'array.c', line 3056 static VALUE rb_ary_collect(VALUE ary) { long i; VALUE collect; RETURN_SIZED_ENUMERATOR(ary, 0, 0, ary_enum_length); collect = rb_ary_new2(RARRAY_LEN(ary)); for (i = 0; i < RARRAY_LEN(ary); i++) { rb_ary_push(collect, rb_yield(RARRAY_AREF(ary, i))); } return collect; } |
#collect! {|item| ... } ⇒ Array #map! {|item| ... } ⇒ Array #collect! ⇒ Enumerator #map! ⇒ Enumerator
Invokes the given block once for each element of self
, replacing the element with the value returned by the block.
See also Enumerable#collect.
If no block is given, an Enumerator is returned instead.
a = [ "a", "b", "c", "d" ]
a.map! {|x| x + "!" }
a #=> [ "a!", "b!", "c!", "d!" ]
a.collect!.with_index {|x, i| x[0...i] }
a #=> ["", "b", "c!", "d!"]
3092 3093 3094 3095 3096 3097 3098 3099 3100 3101 3102 3103 |
# File 'array.c', line 3092 static VALUE rb_ary_collect_bang(VALUE ary) { long i; RETURN_SIZED_ENUMERATOR(ary, 0, 0, ary_enum_length); rb_ary_modify(ary); for (i = 0; i < RARRAY_LEN(ary); i++) { rb_ary_store(ary, i, rb_yield(RARRAY_AREF(ary, i))); } return ary; } |
#max ⇒ Object #max {|a, b| ... } ⇒ Object #max(n) ⇒ Array #max(n) {|a, b| ... } ⇒ Array
Returns the object in ary with the maximum value. The first form assumes all objects implement Comparable; the second uses the block to return a <=> b.
ary = %w(albatross dog horse)
ary.max #=> "horse"
ary.max {|a, b| a.length <=> b.length} #=> "albatross"
If the n
argument is given, maximum n
elements are returned as an array.
ary = %w[albatross dog horse]
ary.max(2) #=> ["horse", "dog"]
ary.max(2) {|a, b| a.length <=> b.length } #=> ["albatross", "horse"]
4828 4829 4830 4831 4832 4833 4834 4835 4836 4837 4838 4839 4840 4841 4842 4843 4844 4845 4846 4847 4848 4849 4850 4851 4852 4853 4854 4855 4856 4857 |
# File 'array.c', line 4828 static VALUE rb_ary_max(int argc, VALUE *argv, VALUE ary) { struct cmp_opt_data cmp_opt = { 0, 0 }; VALUE result = Qundef, v; VALUE num; long i; if (rb_check_arity(argc, 0, 1) && !NIL_P(num = argv[0])) return rb_nmin_run(ary, num, 0, 1, 1); if (rb_block_given_p()) { for (i = 0; i < RARRAY_LEN(ary); i++) { v = RARRAY_AREF(ary, i); if (result == Qundef || rb_cmpint(rb_yield_values(2, v, result), v, result) > 0) { result = v; } } } else { for (i = 0; i < RARRAY_LEN(ary); i++) { v = RARRAY_AREF(ary, i); if (result == Qundef || OPTIMIZED_CMP(v, result, cmp_opt) > 0) { result = v; } } } if (result == Qundef) return Qnil; return result; } |
#min ⇒ Object #min {|a, b| ... } ⇒ Object #min(n) ⇒ Array #min(n) {|a, b| ... } ⇒ Array
Returns the object in ary with the minimum value. The first form assumes all objects implement Comparable; the second uses the block to return a <=> b.
ary = %w(albatross dog horse)
ary.min #=> "albatross"
ary.min {|a, b| a.length <=> b.length} #=> "dog"
If the n
argument is given, minimum n
elements are returned as an array.
ary = %w[albatross dog horse]
ary.min(2) #=> ["albatross", "dog"]
ary.min(2) {|a, b| a.length <=> b.length } #=> ["dog", "horse"]
4881 4882 4883 4884 4885 4886 4887 4888 4889 4890 4891 4892 4893 4894 4895 4896 4897 4898 4899 4900 4901 4902 4903 4904 4905 4906 4907 4908 4909 4910 |
# File 'array.c', line 4881 static VALUE rb_ary_min(int argc, VALUE *argv, VALUE ary) { struct cmp_opt_data cmp_opt = { 0, 0 }; VALUE result = Qundef, v; VALUE num; long i; if (rb_check_arity(argc, 0, 1) && !NIL_P(num = argv[0])) return rb_nmin_run(ary, num, 0, 0, 1); if (rb_block_given_p()) { for (i = 0; i < RARRAY_LEN(ary); i++) { v = RARRAY_AREF(ary, i); if (result == Qundef || rb_cmpint(rb_yield_values(2, v, result), v, result) < 0) { result = v; } } } else { for (i = 0; i < RARRAY_LEN(ary); i++) { v = RARRAY_AREF(ary, i); if (result == Qundef || OPTIMIZED_CMP(v, result, cmp_opt) < 0) { result = v; } } } if (result == Qundef) return Qnil; return result; } |
#minmax ⇒ Array #minmax {|a, b| ... } ⇒ Array
Returns a two element array which contains the minimum and the maximum value in the array.
Can be given an optional block to override the default comparison method a <=> b
.
4923 4924 4925 4926 4927 4928 4929 4930 |
# File 'array.c', line 4923 static VALUE rb_ary_minmax(VALUE ary) { if (rb_block_given_p()) { return rb_call_super(0, NULL); } return rb_assoc_new(rb_ary_min(0, 0, ary), rb_ary_max(0, 0, ary)); } |
#none? {|obj| ... } ⇒ Boolean #none?(pattern) ⇒ Boolean
See also Enumerable#none?
6402 6403 6404 6405 6406 6407 6408 6409 6410 6411 6412 6413 6414 6415 6416 6417 6418 6419 6420 6421 6422 6423 6424 6425 6426 6427 6428 |
# File 'array.c', line 6402 static VALUE rb_ary_none_p(int argc, VALUE *argv, VALUE ary) { long i, len = RARRAY_LEN(ary); rb_check_arity(argc, 0, 1); if (!len) return Qtrue; if (argc) { if (rb_block_given_p()) { rb_warn("given block not used"); } for (i = 0; i < RARRAY_LEN(ary); ++i) { if (RTEST(rb_funcall(argv[0], idEqq, 1, RARRAY_AREF(ary, i)))) return Qfalse; } } else if (!rb_block_given_p()) { for (i = 0; i < len; ++i) { if (RTEST(RARRAY_AREF(ary, i))) return Qfalse; } } else { for (i = 0; i < RARRAY_LEN(ary); ++i) { if (RTEST(rb_yield(RARRAY_AREF(ary, i)))) return Qfalse; } } return Qtrue; } |
#one? {|obj| ... } ⇒ Boolean #one?(pattern) ⇒ Boolean
See also Enumerable#one?
6438 6439 6440 6441 6442 6443 6444 6445 6446 6447 6448 6449 6450 6451 6452 6453 6454 6455 6456 6457 6458 6459 6460 6461 6462 6463 6464 6465 6466 6467 6468 6469 6470 6471 6472 6473 6474 |
# File 'array.c', line 6438 static VALUE rb_ary_one_p(int argc, VALUE *argv, VALUE ary) { long i, len = RARRAY_LEN(ary); VALUE result = Qfalse; rb_check_arity(argc, 0, 1); if (!len) return Qfalse; if (argc) { if (rb_block_given_p()) { rb_warn("given block not used"); } for (i = 0; i < RARRAY_LEN(ary); ++i) { if (RTEST(rb_funcall(argv[0], idEqq, 1, RARRAY_AREF(ary, i)))) { if (result) return Qfalse; result = Qtrue; } } } else if (!rb_block_given_p()) { for (i = 0; i < len; ++i) { if (RTEST(RARRAY_AREF(ary, i))) { if (result) return Qfalse; result = Qtrue; } } } else { for (i = 0; i < RARRAY_LEN(ary); ++i) { if (RTEST(rb_yield(RARRAY_AREF(ary, i)))) { if (result) return Qfalse; result = Qtrue; } } } return result; } |
#permutation {|p| ... } ⇒ Array #permutation ⇒ Enumerator #permutation(n) {|p| ... } ⇒ Array #permutation(n) ⇒ Enumerator
When invoked with a block, yield all permutations of length n
of the elements of the array, then return the array itself.
If n
is not specified, yield all permutations of all elements.
The implementation makes no guarantees about the order in which the permutations are yielded.
If no block is given, an Enumerator is returned instead.
Examples:
a = [1, 2, 3]
a.permutation.to_a #=> [[1,2,3],[1,3,2],[2,1,3],[2,3,1],[3,1,2],[3,2,1]]
a.permutation(1).to_a #=> [[1],[2],[3]]
a.permutation(2).to_a #=> [[1,2],[1,3],[2,1],[2,3],[3,1],[3,2]]
a.permutation(3).to_a #=> [[1,2,3],[1,3,2],[2,1,3],[2,3,1],[3,1,2],[3,2,1]]
a.permutation(0).to_a #=> [[]] # one permutation of length 0
a.permutation(4).to_a #=> [] # no permutations of length 4
5772 5773 5774 5775 5776 5777 5778 5779 5780 5781 5782 5783 5784 5785 5786 5787 5788 5789 5790 5791 5792 5793 5794 5795 5796 5797 5798 5799 5800 5801 5802 5803 5804 5805 5806 5807 5808 |
# File 'array.c', line 5772 static VALUE rb_ary_permutation(int argc, VALUE *argv, VALUE ary) { long r, n, i; n = RARRAY_LEN(ary); /* Array length */ RETURN_SIZED_ENUMERATOR(ary, argc, argv, rb_ary_permutation_size); /* Return enumerator if no block */ r = n; if (rb_check_arity(argc, 0, 1) && !NIL_P(argv[0])) r = NUM2LONG(argv[0]); /* Permutation size from argument */ if (r < 0 || n < r) { /* no permutations: yield nothing */ } else if (r == 0) { /* exactly one permutation: the zero-length array */ rb_yield(rb_ary_new2(0)); } else if (r == 1) { /* this is a special, easy case */ for (i = 0; i < RARRAY_LEN(ary); i++) { rb_yield(rb_ary_new3(1, RARRAY_AREF(ary, i))); } } else { /* this is the general case */ volatile VALUE t0; long *p = ALLOCV_N(long, t0, r+roomof(n, sizeof(long))); char *used = (char*)(p + r); VALUE ary0 = ary_make_shared_copy(ary); /* private defensive copy of ary */ RBASIC_CLEAR_CLASS(ary0); MEMZERO(used, char, n); /* initialize array */ permute0(n, r, p, used, ary0); /* compute and yield permutations */ ALLOCV_END(t0); RBASIC_SET_CLASS_RAW(ary0, rb_cArray); } return ary; } |
#pop ⇒ Object? #pop(n) ⇒ Array
Removes the last element from self
and returns it, or nil
if the array is empty.
If a number n
is given, returns an array of the last n
elements (or less) just like array.slice!(-n, n)
does. See also Array#push for the opposite effect.
a = [ "a", "b", "c", "d" ]
a.pop #=> "d"
a.pop(2) #=> ["b", "c"]
a #=> ["a"]
1277 1278 1279 1280 1281 1282 1283 1284 1285 1286 1287 1288 1289 1290 1291 |
# File 'array.c', line 1277 static VALUE rb_ary_pop_m(int argc, VALUE *argv, VALUE ary) { VALUE result; if (argc == 0) { return rb_ary_pop(ary); } rb_ary_modify_check(ary); result = ary_take_first_or_last(argc, argv, ary, ARY_TAKE_LAST); ARY_INCREASE_LEN(ary, -RARRAY_LEN(result)); ary_verify(ary); return result; } |
#product(other_ary, ...) ⇒ Array #product(other_ary, ...) {|p| ... } ⇒ Array
Returns an array of all combinations of elements from all arrays.
The length of the returned array is the product of the length of self
and the argument arrays.
If given a block, #product will yield all combinations and return self
instead.
[1,2,3].product([4,5]) #=> [[1,4],[1,5],[2,4],[2,5],[3,4],[3,5]]
[1,2].product([1,2]) #=> [[1,1],[1,2],[2,1],[2,2]]
[1,2].product([3,4],[5,6]) #=> [[1,3,5],[1,3,6],[1,4,5],[1,4,6],
# [2,3,5],[2,3,6],[2,4,5],[2,4,6]]
[1,2].product() #=> [[1],[2]]
[1,2].product([]) #=> []
6120 6121 6122 6123 6124 6125 6126 6127 6128 6129 6130 6131 6132 6133 6134 6135 6136 6137 6138 6139 6140 6141 6142 6143 6144 6145 6146 6147 6148 6149 6150 6151 6152 6153 6154 6155 6156 6157 6158 6159 6160 6161 6162 6163 6164 6165 6166 6167 6168 6169 6170 6171 6172 6173 6174 6175 6176 6177 6178 6179 6180 6181 6182 6183 6184 6185 6186 6187 6188 6189 6190 6191 6192 6193 6194 6195 6196 6197 6198 6199 6200 6201 6202 6203 6204 6205 6206 |
# File 'array.c', line 6120 static VALUE rb_ary_product(int argc, VALUE *argv, VALUE ary) { int n = argc+1; /* How many arrays we're operating on */ volatile VALUE t0 = tmpary(n); volatile VALUE t1 = Qundef; VALUE *arrays = RARRAY_PTR(t0); /* The arrays we're computing the product of */ int *counters = ALLOCV_N(int, t1, n); /* The current position in each one */ VALUE result = Qnil; /* The array we'll be returning, when no block given */ long i,j; long resultlen = 1; RBASIC_CLEAR_CLASS(t0); /* initialize the arrays of arrays */ ARY_SET_LEN(t0, n); arrays[0] = ary; for (i = 1; i < n; i++) arrays[i] = Qnil; for (i = 1; i < n; i++) arrays[i] = to_ary(argv[i-1]); /* initialize the counters for the arrays */ for (i = 0; i < n; i++) counters[i] = 0; /* Otherwise, allocate and fill in an array of results */ if (rb_block_given_p()) { /* Make defensive copies of arrays; exit if any is empty */ for (i = 0; i < n; i++) { if (RARRAY_LEN(arrays[i]) == 0) goto done; arrays[i] = ary_make_shared_copy(arrays[i]); } } else { /* Compute the length of the result array; return [] if any is empty */ for (i = 0; i < n; i++) { long k = RARRAY_LEN(arrays[i]); if (k == 0) { result = rb_ary_new2(0); goto done; } if (MUL_OVERFLOW_LONG_P(resultlen, k)) rb_raise(rb_eRangeError, "too big to product"); resultlen *= k; } result = rb_ary_new2(resultlen); } for (;;) { int m; /* fill in one subarray */ VALUE = rb_ary_new2(n); for (j = 0; j < n; j++) { rb_ary_push(, rb_ary_entry(arrays[j], counters[j])); } /* put it on the result array */ if (NIL_P(result)) { FL_SET(t0, FL_USER5); rb_yield(); if (! FL_TEST(t0, FL_USER5)) { rb_raise(rb_eRuntimeError, "product reentered"); } else { FL_UNSET(t0, FL_USER5); } } else { rb_ary_push(result, ); } /* * Increment the last counter. If it overflows, reset to 0 * and increment the one before it. */ m = n-1; counters[m]++; while (counters[m] == RARRAY_LEN(arrays[m])) { counters[m] = 0; /* If the first counter overflows, we are done */ if (--m < 0) goto done; counters[m]++; } } done: tmpary_discard(t0); ALLOCV_END(t1); return NIL_P(result) ? ary : result; } |
#push(obj, ...) ⇒ Array #append(obj, ...) ⇒ Array Also known as: append
Append — Pushes the given object(s) on to the end of this array. This expression returns the array itself, so several appends may be chained together. See also Array#pop for the opposite effect.
a = [ "a", "b", "c" ]
a.push("d", "e", "f")
#=> ["a", "b", "c", "d", "e", "f"]
[1, 2, 3].push(4).push(5)
#=> [1, 2, 3, 4, 5]
1234 1235 1236 1237 1238 |
# File 'array.c', line 1234 static VALUE rb_ary_push_m(int argc, VALUE *argv, VALUE ary) { return rb_ary_cat(ary, argv, argc); } |
#rassoc(obj) ⇒ nil
Searches through the array whose elements are also arrays.
Compares obj
with the second element of each contained array using obj.==
.
Returns the first contained array that matches obj
.
See also Array#assoc.
a = [ [ 1, "one"], [2, "two"], [3, "three"], ["ii", "two"] ]
a.rassoc("two") #=> [2, "two"]
a.rassoc("four") #=> nil
4188 4189 4190 4191 4192 4193 4194 4195 4196 4197 4198 4199 4200 4201 4202 |
# File 'array.c', line 4188 VALUE rb_ary_rassoc(VALUE ary, VALUE value) { long i; VALUE v; for (i = 0; i < RARRAY_LEN(ary); ++i) { v = RARRAY_AREF(ary, i); if (RB_TYPE_P(v, T_ARRAY) && RARRAY_LEN(v) > 1 && rb_equal(RARRAY_AREF(v, 1), value)) return v; } return Qnil; } |
#reject {|item| ... } ⇒ Array #reject ⇒ Enumerator
Returns a new array containing the items in self
for which the given block is not true
. The ordering of non-rejected elements is maintained.
See also Array#delete_if
If no block is given, an Enumerator is returned instead.
3609 3610 3611 3612 3613 3614 3615 3616 3617 3618 |
# File 'array.c', line 3609 static VALUE rb_ary_reject(VALUE ary) { VALUE rejected_ary; RETURN_SIZED_ENUMERATOR(ary, 0, 0, ary_enum_length); rejected_ary = rb_ary_new(); ary_reject(ary, rejected_ary); return rejected_ary; } |
#reject! {|item| ... } ⇒ Array? #reject! ⇒ Enumerator
Deletes every element of self
for which the block evaluates to true
, if no changes were made returns nil
.
The array may not be changed instantly every time the block is called.
See also Enumerable#reject and Array#delete_if.
If no block is given, an Enumerator is returned instead.
3588 3589 3590 3591 3592 3593 3594 |
# File 'array.c', line 3588 static VALUE rb_ary_reject_bang(VALUE ary) { RETURN_SIZED_ENUMERATOR(ary, 0, 0, ary_enum_length); rb_ary_modify(ary); return ary_reject_bang(ary); } |
#repeated_combination(n) {|c| ... } ⇒ Array #repeated_combination(n) ⇒ Enumerator
When invoked with a block, yields all repeated combinations of length n
of elements from the array and then returns the array itself.
The implementation makes no guarantees about the order in which the repeated combinations are yielded.
If no block is given, an Enumerator is returned instead.
Examples:
a = [1, 2, 3]
a.repeated_combination(1).to_a #=> [[1], [2], [3]]
a.repeated_combination(2).to_a #=> [[1,1],[1,2],[1,3],[2,2],[2,3],[3,3]]
a.repeated_combination(3).to_a #=> [[1,1,1],[1,1,2],[1,1,3],[1,2,2],[1,2,3],
# [1,3,3],[2,2,2],[2,2,3],[2,3,3],[3,3,3]]
a.repeated_combination(4).to_a #=> [[1,1,1,1],[1,1,1,2],[1,1,1,3],[1,1,2,2],[1,1,2,3],
# [1,1,3,3],[1,2,2,2],[1,2,2,3],[1,2,3,3],[1,3,3,3],
# [2,2,2,2],[2,2,2,3],[2,2,3,3],[2,3,3,3],[3,3,3,3]]
a.repeated_combination(0).to_a #=> [[]] # one combination of length 0
6064 6065 6066 6067 6068 6069 6070 6071 6072 6073 6074 6075 6076 6077 6078 6079 6080 6081 6082 6083 6084 6085 6086 6087 6088 6089 6090 6091 6092 6093 6094 6095 6096 6097 |
# File 'array.c', line 6064 static VALUE rb_ary_repeated_combination(VALUE ary, VALUE num) { long n, i, len; n = NUM2LONG(num); /* Combination size from argument */ RETURN_SIZED_ENUMERATOR(ary, 1, &num, rb_ary_repeated_combination_size); /* Return enumerator if no block */ len = RARRAY_LEN(ary); if (n < 0) { /* yield nothing */ } else if (n == 0) { rb_yield(rb_ary_new2(0)); } else if (n == 1) { for (i = 0; i < RARRAY_LEN(ary); i++) { rb_yield(rb_ary_new3(1, RARRAY_AREF(ary, i))); } } else if (len == 0) { /* yield nothing */ } else { volatile VALUE t0; long *p = ALLOCV_N(long, t0, n); VALUE ary0 = ary_make_shared_copy(ary); /* private defensive copy of ary */ RBASIC_CLEAR_CLASS(ary0); rcombinate0(len, n, p, n, ary0); /* compute and yield repeated combinations */ ALLOCV_END(t0); RBASIC_SET_CLASS_RAW(ary0, rb_cArray); } return ary; } |
#repeated_permutation(n) {|p| ... } ⇒ Array #repeated_permutation(n) ⇒ Enumerator
When invoked with a block, yield all repeated permutations of length n
of the elements of the array, then return the array itself.
The implementation makes no guarantees about the order in which the repeated permutations are yielded.
If no block is given, an Enumerator is returned instead.
Examples:
a = [1, 2]
a.repeated_permutation(1).to_a #=> [[1], [2]]
a.repeated_permutation(2).to_a #=> [[1,1],[1,2],[2,1],[2,2]]
a.repeated_permutation(3).to_a #=> [[1,1,1],[1,1,2],[1,2,1],[1,2,2],
# [2,1,1],[2,1,2],[2,2,1],[2,2,2]]
a.repeated_permutation(0).to_a #=> [[]] # one permutation of length 0
5970 5971 5972 5973 5974 5975 5976 5977 5978 5979 5980 5981 5982 5983 5984 5985 5986 5987 5988 5989 5990 5991 5992 5993 5994 5995 5996 5997 5998 5999 6000 6001 |
# File 'array.c', line 5970 static VALUE rb_ary_repeated_permutation(VALUE ary, VALUE num) { long r, n, i; n = RARRAY_LEN(ary); /* Array length */ RETURN_SIZED_ENUMERATOR(ary, 1, &num, rb_ary_repeated_permutation_size); /* Return Enumerator if no block */ r = NUM2LONG(num); /* Permutation size from argument */ if (r < 0) { /* no permutations: yield nothing */ } else if (r == 0) { /* exactly one permutation: the zero-length array */ rb_yield(rb_ary_new2(0)); } else if (r == 1) { /* this is a special, easy case */ for (i = 0; i < RARRAY_LEN(ary); i++) { rb_yield(rb_ary_new3(1, RARRAY_AREF(ary, i))); } } else { /* this is the general case */ volatile VALUE t0; long *p = ALLOCV_N(long, t0, r); VALUE ary0 = ary_make_shared_copy(ary); /* private defensive copy of ary */ RBASIC_CLEAR_CLASS(ary0); rpermute0(n, r, p, ary0); /* compute and yield repeated permutations */ ALLOCV_END(t0); RBASIC_SET_CLASS_RAW(ary0, rb_cArray); } return ary; } |
#replace(other_ary) ⇒ Array #initialize_copy(other_ary) ⇒ Object
Replaces the contents of self
with the contents of other_ary
, truncating or expanding if necessary.
a = [ "a", "b", "c", "d", "e" ]
a.replace([ "x", "y", "z" ]) #=> ["x", "y", "z"]
a #=> ["x", "y", "z"]
3810 3811 3812 3813 3814 3815 3816 3817 3818 3819 3820 3821 3822 3823 3824 3825 3826 3827 3828 3829 3830 3831 3832 3833 3834 3835 3836 3837 3838 3839 3840 3841 3842 3843 3844 3845 3846 3847 3848 3849 |
# File 'array.c', line 3810 VALUE rb_ary_replace(VALUE copy, VALUE orig) { rb_ary_modify_check(copy); orig = to_ary(orig); if (copy == orig) return copy; if (RARRAY_LEN(orig) <= RARRAY_EMBED_LEN_MAX) { VALUE shared_root = 0; if (ARY_OWNS_HEAP_P(copy)) { ary_heap_free(copy); } else if (ARY_SHARED_P(copy)) { shared_root = ARY_SHARED_ROOT(copy); FL_UNSET_SHARED(copy); } FL_SET_EMBED(copy); ary_memcpy(copy, 0, RARRAY_LEN(orig), RARRAY_CONST_PTR_TRANSIENT(orig)); if (shared_root) { rb_ary_decrement_share(shared_root); } ARY_SET_LEN(copy, RARRAY_LEN(orig)); } else { VALUE shared_root = ary_make_shared(orig); if (ARY_OWNS_HEAP_P(copy)) { ary_heap_free(copy); } else { rb_ary_unshare_safe(copy); } FL_UNSET_EMBED(copy); ARY_SET_PTR(copy, ARY_HEAP_PTR(orig)); ARY_SET_LEN(copy, ARY_HEAP_LEN(orig)); rb_ary_set_shared(copy, shared_root); } ary_verify(copy); return copy; } |
#reverse ⇒ Array
Returns a new array containing self
‘s elements in reverse order.
[ "a", "b", "c" ].reverse #=> ["c", "b", "a"]
[ 1 ].reverse #=> [1]
2586 2587 2588 2589 2590 2591 2592 2593 2594 2595 2596 2597 2598 2599 |
# File 'array.c', line 2586 static VALUE rb_ary_reverse_m(VALUE ary) { long len = RARRAY_LEN(ary); VALUE dup = rb_ary_new2(len); if (len > 0) { const VALUE *p1 = RARRAY_CONST_PTR_TRANSIENT(ary); VALUE *p2 = (VALUE *)RARRAY_CONST_PTR_TRANSIENT(dup) + len - 1; do *p2-- = *p1++; while (--len > 0); } ARY_SET_LEN(dup, RARRAY_LEN(ary)); return dup; } |
#reverse! ⇒ Array
Reverses self
in place.
a = [ "a", "b", "c" ]
a.reverse! #=> ["c", "b", "a"]
a #=> ["c", "b", "a"]
2570 2571 2572 2573 2574 |
# File 'array.c', line 2570 static VALUE rb_ary_reverse_bang(VALUE ary) { return rb_ary_reverse(ary); } |
#reverse_each {|item| ... } ⇒ Array #reverse_each ⇒ Enumerator
Same as Array#each, but traverses self
in reverse order.
a = [ "a", "b", "c" ]
a.reverse_each {|x| print x, " " }
produces:
c b a
2185 2186 2187 2188 2189 2190 2191 2192 2193 2194 2195 2196 2197 2198 2199 2200 2201 |
# File 'array.c', line 2185 static VALUE rb_ary_reverse_each(VALUE ary) { long len; RETURN_SIZED_ENUMERATOR(ary, 0, 0, ary_enum_length); len = RARRAY_LEN(ary); while (len--) { long nlen; rb_yield(RARRAY_AREF(ary, len)); nlen = RARRAY_LEN(ary); if (nlen < len) { len = nlen; } } return ary; } |
#rindex(obj) ⇒ Integer? #rindex {|item| ... } ⇒ Integer? #rindex ⇒ Enumerator
Returns the index of the last object in self
==
to obj
.
If a block is given instead of an argument, returns the index of the first object for which the block returns true
, starting from the last object.
Returns nil
if no match is found.
See also Array#index.
If neither block nor argument is given, an Enumerator is returned instead.
a = [ "a", "b", "b", "b", "c" ]
a.rindex("b") #=> 3
a.rindex("z") #=> nil
a.rindex {|x| x == "b"} #=> 3
1819 1820 1821 1822 1823 1824 1825 1826 1827 1828 1829 1830 1831 1832 1833 1834 1835 1836 1837 1838 1839 1840 1841 1842 1843 1844 1845 1846 1847 1848 1849 1850 |
# File 'array.c', line 1819 static VALUE rb_ary_rindex(int argc, VALUE *argv, VALUE ary) { VALUE val; long i = RARRAY_LEN(ary), len; if (argc == 0) { RETURN_ENUMERATOR(ary, 0, 0); while (i--) { if (RTEST(rb_yield(RARRAY_AREF(ary, i)))) return LONG2NUM(i); if (i > (len = RARRAY_LEN(ary))) { i = len; } } return Qnil; } rb_check_arity(argc, 0, 1); val = argv[0]; if (rb_block_given_p()) rb_warn("given block not used"); while (i--) { VALUE e = RARRAY_AREF(ary, i); if (rb_equal(e, val)) { return LONG2NUM(i); } if (i > RARRAY_LEN(ary)) { break; } } return Qnil; } |
#rotate(count = 1) ⇒ Array
Returns a new array by rotating self
so that the element at count
is the first element of the new array.
If count
is negative then it rotates in the opposite direction, starting from the end of self
where -1
is the last element.
a = [ "a", "b", "c", "d" ]
a.rotate #=> ["b", "c", "d", "a"]
a #=> ["a", "b", "c", "d"]
a.rotate(2) #=> ["c", "d", "a", "b"]
a.rotate(-3) #=> ["b", "c", "d", "a"]
2673 2674 2675 2676 2677 2678 2679 2680 2681 2682 2683 2684 2685 2686 2687 2688 2689 2690 2691 2692 |
# File 'array.c', line 2673 static VALUE rb_ary_rotate_m(int argc, VALUE *argv, VALUE ary) { VALUE rotated; const VALUE *ptr; long len; long cnt = (rb_check_arity(argc, 0, 1) ? NUM2LONG(argv[0]) : 1); len = RARRAY_LEN(ary); rotated = rb_ary_new2(len); if (len > 0) { cnt = rotate_count(cnt, len); ptr = RARRAY_CONST_PTR_TRANSIENT(ary); len -= cnt; ary_memcpy(rotated, 0, len, ptr + cnt); ary_memcpy(rotated, len, cnt, ptr); } ARY_SET_LEN(rotated, RARRAY_LEN(ary)); return rotated; } |
#rotate!(count = 1) ⇒ Array
Rotates self
in place so that the element at count
comes first, and returns self
.
If count
is negative then it rotates in the opposite direction, starting from the end of the array where -1
is the last element.
a = [ "a", "b", "c", "d" ]
a.rotate! #=> ["b", "c", "d", "a"]
a #=> ["b", "c", "d", "a"]
a.rotate!(2) #=> ["d", "a", "b", "c"]
a.rotate!(-3) #=> ["a", "b", "c", "d"]
2648 2649 2650 2651 2652 2653 2654 |
# File 'array.c', line 2648 static VALUE rb_ary_rotate_bang(int argc, VALUE *argv, VALUE ary) { long n = (rb_check_arity(argc, 0, 1) ? NUM2LONG(argv[0]) : 1); rb_ary_rotate(ary, n); return ary; } |
#sample ⇒ Object #sample(random: rng) ⇒ Object #sample(n) ⇒ Array #sample(n, random: rng) ⇒ Array
Choose a random element or n
random elements from the array.
The elements are chosen by using random and unique indices into the array in order to ensure that an element doesn’t repeat itself unless the array already contained duplicate elements.
If the array is empty the first form returns nil
and the second form returns an empty array.
a = [ 1, 2, 3, 4, 5, 6, 7, 8, 9, 10 ]
a.sample #=> 7
a.sample(4) #=> [6, 4, 2, 5]
The optional rng
argument will be used as the random number generator.
a.sample(random: Random.new(1)) #=> 6
a.sample(4, random: Random.new(1)) #=> [6, 10, 9, 2]
5423 5424 5425 5426 5427 5428 5429 5430 5431 5432 5433 5434 5435 5436 5437 5438 5439 5440 5441 5442 5443 5444 5445 5446 5447 5448 5449 5450 5451 5452 5453 5454 5455 5456 5457 5458 5459 5460 5461 5462 5463 5464 5465 5466 5467 5468 5469 5470 5471 5472 5473 5474 5475 5476 5477 5478 5479 5480 5481 5482 5483 5484 5485 5486 5487 5488 5489 5490 5491 5492 5493 5494 5495 5496 5497 5498 5499 5500 5501 5502 5503 5504 5505 5506 5507 5508 5509 5510 5511 5512 5513 5514 5515 5516 5517 5518 5519 5520 5521 5522 5523 5524 5525 5526 5527 5528 5529 5530 5531 5532 5533 5534 5535 5536 5537 5538 5539 5540 5541 5542 5543 5544 5545 5546 5547 5548 5549 5550 5551 5552 5553 5554 5555 5556 5557 5558 5559 5560 5561 5562 5563 |
# File 'array.c', line 5423 static VALUE rb_ary_sample(int argc, VALUE *argv, VALUE ary) { VALUE nv, result; VALUE opts, randgen = rb_cRandom; long n, len, i, j, k, idx[10]; long rnds[numberof(idx)]; long memo_threshold; if (OPTHASH_GIVEN_P(opts)) { VALUE rnd; ID keyword_ids[1]; keyword_ids[0] = id_random; rb_get_kwargs(opts, keyword_ids, 0, 1, &rnd); if (rnd != Qundef) { randgen = rnd; } } len = RARRAY_LEN(ary); if (rb_check_arity(argc, 0, 1) == 0) { if (len < 2) i = 0; else i = RAND_UPTO(len); return rb_ary_elt(ary, i); } nv = argv[0]; n = NUM2LONG(nv); if (n < 0) rb_raise(rb_eArgError, "negative sample number"); if (n > len) n = len; if (n <= numberof(idx)) { for (i = 0; i < n; ++i) { rnds[i] = RAND_UPTO(len - i); } } k = len; len = RARRAY_LEN(ary); if (len < k && n <= numberof(idx)) { for (i = 0; i < n; ++i) { if (rnds[i] >= len) return rb_ary_new_capa(0); } } if (n > len) n = len; switch (n) { case 0: return rb_ary_new_capa(0); case 1: i = rnds[0]; return rb_ary_new_from_values(1, &RARRAY_AREF(ary, i)); case 2: i = rnds[0]; j = rnds[1]; if (j >= i) j++; return rb_ary_new_from_args(2, RARRAY_AREF(ary, i), RARRAY_AREF(ary, j)); case 3: i = rnds[0]; j = rnds[1]; k = rnds[2]; { long l = j, g = i; if (j >= i) l = i, g = ++j; if (k >= l && (++k >= g)) ++k; } return rb_ary_new_from_args(3, RARRAY_AREF(ary, i), RARRAY_AREF(ary, j), RARRAY_AREF(ary, k)); } memo_threshold = len < 2560 ? len / 128 : len < 5120 ? len / 64 : len < 10240 ? len / 32 : len / 16; if (n <= numberof(idx)) { long sorted[numberof(idx)]; sorted[0] = idx[0] = rnds[0]; for (i=1; i<n; i++) { k = rnds[i]; for (j = 0; j < i; ++j) { if (k < sorted[j]) break; ++k; } memmove(&sorted[j+1], &sorted[j], sizeof(sorted[0])*(i-j)); sorted[j] = idx[i] = k; } result = rb_ary_new_capa(n); RARRAY_PTR_USE_TRANSIENT(result, ptr_result, { for (i=0; i<n; i++) { ptr_result[i] = RARRAY_AREF(ary, idx[i]); } }); } else if (n <= memo_threshold / 2) { long max_idx = 0; #undef RUBY_UNTYPED_DATA_WARNING #define RUBY_UNTYPED_DATA_WARNING 0 VALUE vmemo = Data_Wrap_Struct(0, 0, st_free_table, 0); st_table *memo = st_init_numtable_with_size(n); DATA_PTR(vmemo) = memo; result = rb_ary_new_capa(n); RARRAY_PTR_USE(result, ptr_result, { for (i=0; i<n; i++) { long r = RAND_UPTO(len-i) + i; ptr_result[i] = r; if (r > max_idx) max_idx = r; } len = RARRAY_LEN(ary); if (len <= max_idx) n = 0; else if (n > len) n = len; RARRAY_PTR_USE_TRANSIENT(ary, ptr_ary, { for (i=0; i<n; i++) { long j2 = j = ptr_result[i]; long i2 = i; st_data_t value; if (st_lookup(memo, (st_data_t)i, &value)) i2 = (long)value; if (st_lookup(memo, (st_data_t)j, &value)) j2 = (long)value; st_insert(memo, (st_data_t)j, (st_data_t)i2); ptr_result[i] = ptr_ary[j2]; } }); }); DATA_PTR(vmemo) = 0; st_free_table(memo); } else { result = rb_ary_dup(ary); RBASIC_CLEAR_CLASS(result); RB_GC_GUARD(ary); RARRAY_PTR_USE(result, ptr_result, { for (i=0; i<n; i++) { j = RAND_UPTO(len-i) + i; nv = ptr_result[j]; ptr_result[j] = ptr_result[i]; ptr_result[i] = nv; } }); RBASIC_SET_CLASS_RAW(result, rb_cArray); } ARY_SET_LEN(result, n); return result; } |
#select {|item| ... } ⇒ Array #select ⇒ Enumerator #filter {|item| ... } ⇒ Array #filter ⇒ Enumerator
Returns a new array containing all elements of ary
for which the given block
returns a true value.
If no block is given, an Enumerator is returned instead.
[1,2,3,4,5].select {|num| num.even? } #=> [2, 4]
a = %w[ a b c d e f ]
a.select {|v| v =~ /[aeiou]/ } #=> ["a", "e"]
See also Enumerable#select.
Array#filter is an alias for Array#select.
3212 3213 3214 3215 3216 3217 3218 3219 3220 3221 3222 3223 3224 3225 3226 |
# File 'array.c', line 3212 static VALUE rb_ary_select(VALUE ary) { VALUE result; long i; RETURN_SIZED_ENUMERATOR(ary, 0, 0, ary_enum_length); result = rb_ary_new2(RARRAY_LEN(ary)); for (i = 0; i < RARRAY_LEN(ary); i++) { if (RTEST(rb_yield(RARRAY_AREF(ary, i)))) { rb_ary_push(result, rb_ary_elt(ary, i)); } } return result; } |
#select! {|item| ... } ⇒ Array? #select! ⇒ Enumerator #filter! {|item| ... } ⇒ Array? #filter! ⇒ Enumerator
Invokes the given block passing in successive elements from self
, deleting elements for which the block returns a false
value.
The array may not be changed instantly every time the block is called.
If changes were made, it will return self
, otherwise it returns nil
.
If no block is given, an Enumerator is returned instead.
See also Array#keep_if.
Array#filter! is an alias for Array#select!.
3293 3294 3295 3296 3297 3298 3299 3300 3301 3302 3303 3304 |
# File 'array.c', line 3293 static VALUE rb_ary_select_bang(VALUE ary) { struct select_bang_arg args; RETURN_SIZED_ENUMERATOR(ary, 0, 0, ary_enum_length); rb_ary_modify(ary); args.ary = ary; args.len[0] = args.len[1] = 0; return rb_ensure(select_bang_i, (VALUE)&args, select_bang_ensure, (VALUE)&args); } |
#shift ⇒ Object? #shift(n) ⇒ Array
Removes the first element of self
and returns it (shifting all other elements down by one). Returns nil
if the array is empty.
If a number n
is given, returns an array of the first n
elements (or less) just like array.slice!(0, n)
does. With ary
containing only the remainder elements, not including what was shifted to new_ary
. See also Array#unshift for the opposite effect.
args = [ "-m", "-q", "filename" ]
args.shift #=> "-m"
args #=> ["-q", "filename"]
args = [ "-m", "-q", "filename" ]
args.shift(2) #=> ["-m", "-q"]
args #=> ["filename"]
1350 1351 1352 1353 1354 1355 1356 1357 1358 1359 1360 1361 1362 1363 1364 1365 1366 |
# File 'array.c', line 1350 static VALUE rb_ary_shift_m(int argc, VALUE *argv, VALUE ary) { VALUE result; long n; if (argc == 0) { return rb_ary_shift(ary); } rb_ary_modify_check(ary); result = ary_take_first_or_last(argc, argv, ary, ARY_TAKE_FIRST); n = RARRAY_LEN(result); rb_ary_behead(ary,n); return result; } |
#shuffle ⇒ Array #shuffle(random: rng) ⇒ Array
Returns a new array with elements of self
shuffled.
a = [ 1, 2, 3 ] #=> [1, 2, 3]
a.shuffle #=> [2, 3, 1]
a #=> [1, 2, 3]
The optional rng
argument will be used as the random number generator.
a.shuffle(random: Random.new(1)) #=> [1, 3, 2]
5387 5388 5389 5390 5391 5392 5393 |
# File 'array.c', line 5387 static VALUE rb_ary_shuffle(int argc, VALUE *argv, VALUE ary) { ary = rb_ary_dup(ary); rb_ary_shuffle_bang(argc, argv, ary); return ary; } |
#shuffle! ⇒ Array #shuffle!(random: rng) ⇒ Array
Shuffles elements in self
in place.
a = [ 1, 2, 3 ] #=> [1, 2, 3]
a.shuffle! #=> [2, 3, 1]
a #=> [2, 3, 1]
The optional rng
argument will be used as the random number generator.
a.shuffle!(random: Random.new(1)) #=> [1, 3, 2]
5336 5337 5338 5339 5340 5341 5342 5343 5344 5345 5346 5347 5348 5349 5350 5351 5352 5353 5354 5355 5356 5357 5358 5359 5360 5361 5362 5363 5364 5365 5366 5367 5368 |
# File 'array.c', line 5336 static VALUE rb_ary_shuffle_bang(int argc, VALUE *argv, VALUE ary) { VALUE opts, randgen = rb_cRandom; long i, len; if (OPTHASH_GIVEN_P(opts)) { VALUE rnd; ID keyword_ids[1]; keyword_ids[0] = id_random; rb_get_kwargs(opts, keyword_ids, 0, 1, &rnd); if (rnd != Qundef) { randgen = rnd; } } rb_check_arity(argc, 0, 0); rb_ary_modify(ary); i = len = RARRAY_LEN(ary); RARRAY_PTR_USE(ary, ptr, { while (i) { long j = RAND_UPTO(i); VALUE tmp; if (len != RARRAY_LEN(ary) || ptr != RARRAY_CONST_PTR_TRANSIENT(ary)) { rb_raise(rb_eRuntimeError, "modified during shuffle"); } tmp = ptr[--i]; ptr[i] = ptr[j]; ptr[j] = tmp; } }); /* WB: no new reference */ return ary; } |
#[](index) ⇒ Object? #[](start, length) ⇒ Array? #[](range) ⇒ Array? #slice(index) ⇒ Object? #slice(start, length) ⇒ Array? #slice(range) ⇒ Array?
Element Reference — Returns the element at index
, or returns a subarray starting at the start
index and continuing for length
elements, or returns a subarray specified by range
of indices.
Negative indices count backward from the end of the array (-1 is the last element). For start
and range
cases the starting index is just before an element. Additionally, an empty array is returned when the starting index for an element range is at the end of the array.
Returns nil
if the index (or starting index) are out of range.
a = [ "a", "b", "c", "d", "e" ]
a[2] + a[0] + a[1] #=> "cab"
a[6] #=> nil
a[1, 2] #=> [ "b", "c" ]
a[1..3] #=> [ "b", "c", "d" ]
a[4..7] #=> [ "e" ]
a[6..10] #=> nil
a[-3, 3] #=> [ "c", "d", "e" ]
# special cases
a[5] #=> nil
a[6, 1] #=> nil
a[5, 1] #=> []
a[5..10] #=> []
1573 1574 1575 1576 1577 1578 1579 1580 1581 |
# File 'array.c', line 1573 VALUE rb_ary_aref(int argc, const VALUE *argv, VALUE ary) { rb_check_arity(argc, 1, 2); if (argc == 2) { return rb_ary_aref2(ary, argv[0], argv[1]); } return rb_ary_aref1(ary, argv[0]); } |
#slice!(index) ⇒ Object? #slice!(start, length) ⇒ Array? #slice!(range) ⇒ Array?
Deletes the element(s) given by an index
(optionally up to length
elements) or by a range
.
Returns the deleted object (or objects), or nil
if the index
is out of range.
a = [ "a", "b", "c" ]
a.slice!(1) #=> "b"
a #=> ["a", "c"]
a.slice!(-1) #=> "c"
a #=> ["a"]
a.slice!(100) #=> nil
a #=> ["a"]
3482 3483 3484 3485 3486 3487 3488 3489 3490 3491 3492 3493 3494 3495 3496 3497 3498 3499 3500 3501 3502 3503 3504 3505 3506 3507 3508 3509 3510 3511 3512 3513 3514 3515 3516 3517 3518 3519 3520 3521 3522 3523 3524 3525 3526 3527 3528 |
# File 'array.c', line 3482 static VALUE rb_ary_slice_bang(int argc, VALUE *argv, VALUE ary) { VALUE arg1, arg2; long pos, len, orig_len; rb_ary_modify_check(ary); if (argc == 2) { pos = NUM2LONG(argv[0]); len = NUM2LONG(argv[1]); delete_pos_len: if (len < 0) return Qnil; orig_len = RARRAY_LEN(ary); if (pos < 0) { pos += orig_len; if (pos < 0) return Qnil; } else if (orig_len < pos) return Qnil; if (orig_len < pos + len) { len = orig_len - pos; } if (len == 0) return rb_ary_new2(0); arg2 = rb_ary_new4(len, RARRAY_CONST_PTR_TRANSIENT(ary)+pos); RBASIC_SET_CLASS(arg2, rb_obj_class(ary)); rb_ary_splice(ary, pos, len, 0, 0); return arg2; } rb_check_arity(argc, 1, 2); arg1 = argv[0]; if (!FIXNUM_P(arg1)) { switch (rb_range_beg_len(arg1, &pos, &len, RARRAY_LEN(ary), 0)) { case Qtrue: /* valid range */ goto delete_pos_len; case Qnil: /* invalid range */ return Qnil; default: /* not a range */ break; } } return rb_ary_delete_at(ary, NUM2LONG(arg1)); } |
#sort ⇒ Array #sort {|a, b| ... } ⇒ Array
Returns a new array created by sorting self
.
Comparisons for the sort will be done using the <=>
operator or using an optional code block.
The block must implement a comparison between a
and b
and return an integer less than 0 when b
follows a
, 0
when a
and b
are equivalent, or an integer greater than 0 when a
follows b
.
The result is not guaranteed to be stable. When the comparison of two elements returns 0
, the order of the elements is unpredictable.
ary = [ "d", "a", "e", "c", "b" ]
ary.sort #=> ["a", "b", "c", "d", "e"]
ary.sort {|a, b| b <=> a} #=> ["e", "d", "c", "b", "a"]
To produce the reverse order, the following can also be used (and may be faster):
ary.sort.reverse! #=> ["e", "d", "c", "b", "a"]
See also Enumerable#sort_by.
2865 2866 2867 2868 2869 2870 2871 |
# File 'array.c', line 2865 VALUE rb_ary_sort(VALUE ary) { ary = rb_ary_dup(ary); rb_ary_sort_bang(ary); return ary; } |
#sort! ⇒ Array #sort! {|a, b| ... } ⇒ Array
Sorts self
in place.
Comparisons for the sort will be done using the <=>
operator or using an optional code block.
The block must implement a comparison between a
and b
and return an integer less than 0 when b
follows a
, 0
when a
and b
are equivalent, or an integer greater than 0 when a
follows b
.
The result is not guaranteed to be stable. When the comparison of two elements returns 0
, the order of the elements is unpredictable.
ary = [ "d", "a", "e", "c", "b" ]
ary.sort! #=> ["a", "b", "c", "d", "e"]
ary.sort! {|a, b| b <=> a} #=> ["e", "d", "c", "b", "a"]
See also Enumerable#sort_by.
2776 2777 2778 2779 2780 2781 2782 2783 2784 2785 2786 2787 2788 2789 2790 2791 2792 2793 2794 2795 2796 2797 2798 2799 2800 2801 2802 2803 2804 2805 2806 2807 2808 2809 2810 2811 2812 2813 2814 2815 2816 2817 2818 2819 2820 2821 2822 2823 2824 2825 2826 2827 2828 2829 2830 2831 2832 2833 2834 |
# File 'array.c', line 2776 VALUE rb_ary_sort_bang(VALUE ary) { rb_ary_modify(ary); assert(!ARY_SHARED_P(ary)); if (RARRAY_LEN(ary) > 1) { VALUE tmp = ary_make_substitution(ary); /* only ary refers tmp */ struct ary_sort_data data; long len = RARRAY_LEN(ary); RBASIC_CLEAR_CLASS(tmp); data.ary = tmp; data.cmp_opt.opt_methods = 0; data.cmp_opt.opt_inited = 0; RARRAY_PTR_USE(tmp, ptr, { ruby_qsort(ptr, len, sizeof(VALUE), rb_block_given_p()?sort_1:sort_2, &data); }); /* WB: no new reference */ rb_ary_modify(ary); if (ARY_EMBED_P(tmp)) { if (ARY_SHARED_P(ary)) { /* ary might be destructively operated in the given block */ rb_ary_unshare(ary); FL_SET_EMBED(ary); } ary_memcpy(ary, 0, ARY_EMBED_LEN(tmp), ARY_EMBED_PTR(tmp)); ARY_SET_LEN(ary, ARY_EMBED_LEN(tmp)); } else { if (!ARY_EMBED_P(ary) && ARY_HEAP_PTR(ary) == ARY_HEAP_PTR(tmp)) { FL_UNSET_SHARED(ary); ARY_SET_CAPA(ary, RARRAY_LEN(tmp)); } else { assert(!ARY_SHARED_P(tmp)); if (ARY_EMBED_P(ary)) { FL_UNSET_EMBED(ary); } else if (ARY_SHARED_P(ary)) { /* ary might be destructively operated in the given block */ rb_ary_unshare(ary); } else { ary_heap_free(ary); } ARY_SET_PTR(ary, ARY_HEAP_PTR(tmp)); ARY_SET_HEAP_LEN(ary, len); ARY_SET_CAPA(ary, ARY_HEAP_LEN(tmp)); } /* tmp was lost ownership for the ptr */ FL_UNSET(tmp, FL_FREEZE); FL_SET_EMBED(tmp); ARY_SET_EMBED_LEN(tmp, 0); FL_SET(tmp, FL_FREEZE); } /* tmp will be GC'ed. */ RBASIC_SET_CLASS_RAW(tmp, rb_cArray); /* rb_cArray must be marked */ } ary_verify(ary); return ary; } |
#sort_by! {|obj| ... } ⇒ Array #sort_by! ⇒ Enumerator
Sorts self
in place using a set of keys generated by mapping the values in self
through the given block.
The result is not guaranteed to be stable. When two keys are equal, the order of the corresponding elements is unpredictable.
If no block is given, an Enumerator is returned instead.
See also Enumerable#sort_by.
3022 3023 3024 3025 3026 3027 3028 3029 3030 3031 3032 |
# File 'array.c', line 3022 static VALUE rb_ary_sort_by_bang(VALUE ary) { VALUE sorted; RETURN_SIZED_ENUMERATOR(ary, 0, 0, ary_enum_length); rb_ary_modify(ary); sorted = rb_block_call(ary, rb_intern("sort_by"), 0, 0, sort_by_i, 0); rb_ary_replace(ary, sorted); return ary; } |
#sum(init = 0) ⇒ Numeric #sum(init = 0) {|e| ... } ⇒ Numeric
Returns the sum of elements. For example, [e1, e2, e3].sum returns init + e1 + e2 + e3.
If a block is given, the block is applied to each element before addition.
If ary is empty, it returns init.
[].sum #=> 0
[].sum(0.0) #=> 0.0
[1, 2, 3].sum #=> 6
[3, 5.5].sum #=> 8.5
[2.5, 3.0].sum(0.0) {|e| e * e } #=> 15.25
[Object.new].sum #=> TypeError
The (arithmetic) mean value of an array can be obtained as follows.
mean = ary.sum(0.0) / ary.length
This method can be used for non-numeric objects by explicit init argument.
["a", "b", "c"].sum("") #=> "abc"
[[1], [[2]], [3]].sum([]) #=> [1, [2], 3]
However, Array#join and Array#flatten is faster than Array#sum for array of strings and array of arrays.
["a", "b", "c"].join #=> "abc"
[[1], [[2]], [3]].flatten(1) #=> [1, [2], 3]
Array#sum method may not respect method redefinition of “+” methods such as Integer#+.
6564 6565 6566 6567 6568 6569 6570 6571 6572 6573 6574 6575 6576 6577 6578 6579 6580 6581 6582 6583 6584 6585 6586 6587 6588 6589 6590 6591 6592 6593 6594 6595 6596 6597 6598 6599 6600 6601 6602 6603 6604 6605 6606 6607 6608 6609 6610 6611 6612 6613 6614 6615 6616 6617 6618 6619 6620 6621 6622 6623 6624 6625 6626 6627 6628 6629 6630 6631 6632 6633 6634 6635 6636 6637 6638 6639 6640 6641 6642 6643 6644 6645 6646 6647 6648 6649 6650 6651 6652 6653 6654 6655 6656 6657 6658 6659 6660 6661 6662 6663 6664 6665 6666 6667 6668 6669 6670 6671 6672 |
# File 'array.c', line 6564 static VALUE rb_ary_sum(int argc, VALUE *argv, VALUE ary) { VALUE e, v, r; long i, n; int block_given; v = (rb_check_arity(argc, 0, 1) ? argv[0] : LONG2FIX(0)); block_given = rb_block_given_p(); if (RARRAY_LEN(ary) == 0) return v; n = 0; r = Qundef; for (i = 0; i < RARRAY_LEN(ary); i++) { e = RARRAY_AREF(ary, i); if (block_given) e = rb_yield(e); if (FIXNUM_P(e)) { n += FIX2LONG(e); /* should not overflow long type */ if (!FIXABLE(n)) { v = rb_big_plus(LONG2NUM(n), v); n = 0; } } else if (RB_TYPE_P(e, T_BIGNUM)) v = rb_big_plus(e, v); else if (RB_TYPE_P(e, T_RATIONAL)) { if (r == Qundef) r = e; else r = rb_rational_plus(r, e); } else goto not_exact; } v = finish_exact_sum(n, r, v, argc!=0); return v; not_exact: v = finish_exact_sum(n, r, v, i!=0); if (RB_FLOAT_TYPE_P(e)) { /* * Kahan-Babuska balancing compensated summation algorithm * See http://link.springer.com/article/10.1007/s00607-005-0139-x */ double f, c; double x, t; f = NUM2DBL(v); c = 0.0; goto has_float_value; for (; i < RARRAY_LEN(ary); i++) { e = RARRAY_AREF(ary, i); if (block_given) e = rb_yield(e); if (RB_FLOAT_TYPE_P(e)) has_float_value: x = RFLOAT_VALUE(e); else if (FIXNUM_P(e)) x = FIX2LONG(e); else if (RB_TYPE_P(e, T_BIGNUM)) x = rb_big2dbl(e); else if (RB_TYPE_P(e, T_RATIONAL)) x = rb_num2dbl(e); else goto not_float; if (isnan(f)) continue; if (isnan(x)) { f = x; continue; } if (isinf(x)) { if (isinf(f) && signbit(x) != signbit(f)) f = NAN; else f = x; continue; } if (isinf(f)) continue; t = f + x; if (fabs(f) >= fabs(x)) c += ((f - t) + x); else c += ((x - t) + f); f = t; } f += c; return DBL2NUM(f); not_float: v = DBL2NUM(f); } goto has_some_value; for (; i < RARRAY_LEN(ary); i++) { e = RARRAY_AREF(ary, i); if (block_given) e = rb_yield(e); has_some_value: v = rb_funcall(v, idPLUS, 1, e); } return v; } |
#take(n) ⇒ Array
Returns first n
elements from the array.
If a negative number is given, raises an ArgumentError.
See also Array#drop
a = [1, 2, 3, 4, 5, 0]
a.take(3) #=> [1, 2, 3]
6223 6224 6225 6226 6227 6228 6229 6230 6231 |
# File 'array.c', line 6223 static VALUE rb_ary_take(VALUE obj, VALUE n) { long len = NUM2LONG(n); if (len < 0) { rb_raise(rb_eArgError, "attempt to take negative size"); } return rb_ary_subseq(obj, 0, len); } |
#take_while {|obj| ... } ⇒ Array #take_while ⇒ Enumerator
Passes elements to the block until the block returns nil
or false
, then stops iterating and returns an array of all prior elements.
If no block is given, an Enumerator is returned instead.
See also Array#drop_while
a = [1, 2, 3, 4, 5, 0]
a.take_while {|i| i < 3} #=> [1, 2]
6250 6251 6252 6253 6254 6255 6256 6257 6258 6259 6260 |
# File 'array.c', line 6250 static VALUE rb_ary_take_while(VALUE ary) { long i; RETURN_ENUMERATOR(ary, 0, 0); for (i = 0; i < RARRAY_LEN(ary); i++) { if (!RTEST(rb_yield(RARRAY_AREF(ary, i)))) break; } return rb_ary_take(ary, LONG2FIX(i)); } |
#to_a ⇒ Array
Returns self
.
If called on a subclass of Array, converts the receiver to an Array object.
2467 2468 2469 2470 2471 2472 2473 2474 2475 2476 |
# File 'array.c', line 2467 static VALUE rb_ary_to_a(VALUE ary) { if (rb_obj_class(ary) != rb_cArray) { VALUE dup = rb_ary_new2(RARRAY_LEN(ary)); rb_ary_replace(dup, ary); return dup; } return ary; } |
#to_ary ⇒ Array
Returns self
.
2527 2528 2529 2530 2531 |
# File 'array.c', line 2527 static VALUE rb_ary_to_ary_m(VALUE ary) { return ary; } |
#to_h ⇒ Hash #to_h {|item| ... } ⇒ Hash
Returns the result of interpreting ary as an array of [key, value]
pairs.
[[:foo, :bar], [1, 2]].to_h
# => {:foo => :bar, 1 => 2}
If a block is given, the results of the block on each element of the array will be used as pairs.
["foo", "bar"].to_h {|s| [s.ord, s]}
# => {102=>"foo", 98=>"bar"}
2496 2497 2498 2499 2500 2501 2502 2503 2504 2505 2506 2507 2508 2509 2510 2511 2512 2513 2514 2515 2516 2517 2518 |
# File 'array.c', line 2496 static VALUE rb_ary_to_h(VALUE ary) { long i; VALUE hash = rb_hash_new_with_size(RARRAY_LEN(ary)); int block_given = rb_block_given_p(); for (i=0; i<RARRAY_LEN(ary); i++) { const VALUE e = rb_ary_elt(ary, i); const VALUE elt = block_given ? rb_yield_force_blockarg(e) : e; const VALUE key_value_pair = rb_check_array_type(elt); if (NIL_P(key_value_pair)) { rb_raise(rb_eTypeError, "wrong element type %"PRIsVALUE" at %ld (expected array)", rb_obj_class(elt), i); } if (RARRAY_LEN(key_value_pair) != 2) { rb_raise(rb_eArgError, "wrong array length at %ld (expected 2, was %ld)", i, RARRAY_LEN(key_value_pair)); } rb_hash_aset(hash, RARRAY_AREF(key_value_pair, 0), RARRAY_AREF(key_value_pair, 1)); } return hash; } |
#transpose ⇒ Array
Assumes that self
is an array of arrays and transposes the rows and columns.
a = [[1,2], [3,4], [5,6]]
a.transpose #=> [[1, 3, 5], [2, 4, 6]]
If the length of the subarrays don’t match, an IndexError is raised.
3769 3770 3771 3772 3773 3774 3775 3776 3777 3778 3779 3780 3781 3782 3783 3784 3785 3786 3787 3788 3789 3790 3791 3792 3793 3794 3795 |
# File 'array.c', line 3769 static VALUE rb_ary_transpose(VALUE ary) { long elen = -1, alen, i, j; VALUE tmp, result = 0; alen = RARRAY_LEN(ary); if (alen == 0) return rb_ary_dup(ary); for (i=0; i<alen; i++) { tmp = to_ary(rb_ary_elt(ary, i)); if (elen < 0) { /* first element */ elen = RARRAY_LEN(tmp); result = rb_ary_new2(elen); for (j=0; j<elen; j++) { rb_ary_store(result, j, rb_ary_new2(alen)); } } else if (elen != RARRAY_LEN(tmp)) { rb_raise(rb_eIndexError, "element size differs (%ld should be %ld)", RARRAY_LEN(tmp), elen); } for (j=0; j<elen; j++) { rb_ary_store(rb_ary_elt(result, j), i, rb_ary_elt(tmp, j)); } } return result; } |
#union(other_ary1, other_ary2, ...) ⇒ Array
Set Union — Returns a new array by joining other_ary
s with self
, excluding any duplicates and preserving the order from the given arrays.
It compares elements using their #hash and #eql? methods for efficiency.
[ "a", "b", "c" ].union( [ "c", "d", "a" ] ) #=> [ "a", "b", "c", "d" ]
[ "a" ].union( ["e", "b"], ["a", "c", "b"] ) #=> [ "a", "e", "b", "c" ]
[ "a" ].union #=> [ "a" ]
See also Array#|.
4776 4777 4778 4779 4780 4781 4782 4783 4784 4785 4786 4787 4788 4789 4790 4791 4792 4793 4794 4795 4796 4797 4798 4799 4800 4801 4802 4803 4804 |
# File 'array.c', line 4776 static VALUE rb_ary_union_multi(int argc, VALUE *argv, VALUE ary) { int i; long sum; VALUE hash, ary_union; sum = RARRAY_LEN(ary); for (i = 0; i < argc; i++) { argv[i] = to_ary(argv[i]); sum += RARRAY_LEN(argv[i]); } if (sum <= SMALL_ARRAY_LEN) { ary_union = rb_ary_new(); rb_ary_union(ary_union, ary); for (i = 0; i < argc; i++) rb_ary_union(ary_union, argv[i]); return ary_union; } hash = ary_make_hash(ary); for (i = 0; i < argc; i++) rb_ary_union_hash(hash, argv[i]); ary_union = rb_hash_values(hash); ary_recycle_hash(hash); return ary_union; } |
#uniq ⇒ Array #uniq {|item| ... } ⇒ Array
Returns a new array by removing duplicate values in self
.
If a block is given, it will use the return value of the block for comparison.
It compares values using their #hash and #eql? methods for efficiency.
self
is traversed in order, and the first occurrence is kept.
a = [ "a", "a", "b", "b", "c" ]
a.uniq # => ["a", "b", "c"]
b = [["student","sam"], ["student","george"], ["teacher","matz"]]
b.uniq {|s| s.first} # => [["student", "sam"], ["teacher", "matz"]]
5018 5019 5020 5021 5022 5023 5024 5025 5026 5027 5028 5029 5030 5031 5032 5033 5034 5035 5036 5037 5038 5039 5040 5041 |
# File 'array.c', line 5018 static VALUE rb_ary_uniq(VALUE ary) { VALUE hash, uniq; if (RARRAY_LEN(ary) <= 1) { hash = 0; uniq = rb_ary_dup(ary); } else if (rb_block_given_p()) { hash = ary_make_hash_by(ary); uniq = rb_hash_values(hash); } else { hash = ary_make_hash(ary); uniq = rb_hash_values(hash); } RBASIC_SET_CLASS(uniq, rb_obj_class(ary)); if (hash) { ary_recycle_hash(hash); } return uniq; } |
#uniq! ⇒ Array? #uniq! {|item| ... } ⇒ Array?
Removes duplicate elements from self
.
If a block is given, it will use the return value of the block for comparison.
It compares values using their #hash and #eql? methods for efficiency.
self
is traversed in order, and the first occurrence is kept.
Returns nil
if no changes are made (that is, no duplicates are found).
a = [ "a", "a", "b", "b", "c" ]
a.uniq! # => ["a", "b", "c"]
b = [ "a", "b", "c" ]
b.uniq! # => nil
c = [["student","sam"], ["student","george"], ["teacher","matz"]]
c.uniq! {|s| s.first} # => [["student", "sam"], ["teacher", "matz"]]
4966 4967 4968 4969 4970 4971 4972 4973 4974 4975 4976 4977 4978 4979 4980 4981 4982 4983 4984 4985 4986 4987 4988 4989 4990 4991 4992 4993 4994 4995 |
# File 'array.c', line 4966 static VALUE rb_ary_uniq_bang(VALUE ary) { VALUE hash; long hash_size; rb_ary_modify_check(ary); if (RARRAY_LEN(ary) <= 1) return Qnil; if (rb_block_given_p()) hash = ary_make_hash_by(ary); else hash = ary_make_hash(ary); hash_size = RHASH_SIZE(hash); if (RARRAY_LEN(ary) == hash_size) { return Qnil; } rb_ary_modify_check(ary); ARY_SET_LEN(ary, 0); if (ARY_SHARED_P(ary) && !ARY_EMBED_P(ary)) { rb_ary_unshare(ary); FL_SET_EMBED(ary); } ary_resize_capa(ary, hash_size); rb_hash_foreach(hash, push_value, ary); ary_recycle_hash(hash); return ary; } |
#unshift(obj, ...) ⇒ Array #prepend(obj, ...) ⇒ Array Also known as: prepend
Prepends objects to the front of self
, moving other elements upwards. See also Array#shift for the opposite effect.
a = [ "b", "c", "d" ]
a.unshift("a") #=> ["a", "b", "c", "d"]
a.unshift(1, 2) #=> [ 1, 2, "a", "b", "c", "d"]
1476 1477 1478 1479 1480 1481 1482 1483 1484 1485 1486 1487 1488 1489 1490 1491 |
# File 'array.c', line 1476 static VALUE rb_ary_unshift_m(int argc, VALUE *argv, VALUE ary) { long len = RARRAY_LEN(ary); VALUE target_ary; if (argc == 0) { rb_ary_modify_check(ary); return ary; } target_ary = ary_ensure_room_for_unshift(ary, argc); ary_memcpy0(ary, 0, argc, argv, target_ary); ARY_SET_LEN(ary, len + argc); return ary; } |
#values_at(selector, ...) ⇒ Array
Returns an array containing the elements in self
corresponding to the given selector
(s).
The selectors may be either integer indices or ranges.
See also Array#select.
a = %w{ a b c d e f }
a.values_at(1, 3, 5) # => ["b", "d", "f"]
a.values_at(1, 3, 5, 7) # => ["b", "d", "f", nil]
a.values_at(-1, -2, -2, -7) # => ["f", "e", "e", nil]
a.values_at(4..6, 3...6) # => ["e", "f", nil, "d", "e", "f"]
3177 3178 3179 3180 3181 3182 3183 3184 3185 3186 3187 |
# File 'array.c', line 3177 static VALUE rb_ary_values_at(int argc, VALUE *argv, VALUE ary) { long i, olen = RARRAY_LEN(ary); VALUE result = rb_ary_new_capa(argc); for (i = 0; i < argc; ++i) { append_values_at_single(result, ary, olen, argv[i]); } RB_GC_GUARD(ary); return result; } |
#zip(arg, ...) ⇒ Array #zip(arg, ...) {|arr| ... } ⇒ nil
Converts any arguments to arrays, then merges elements of self
with corresponding elements from each argument.
This generates a sequence of ary.size
n-element arrays, where n is one more than the count of arguments.
If the size of any argument is less than the size of the initial array, nil
values are supplied.
If a block is given, it is invoked for each output array
, otherwise an array of arrays is returned.
a = [ 4, 5, 6 ]
b = [ 7, 8, 9 ]
[1, 2, 3].zip(a, b) #=> [[1, 4, 7], [2, 5, 8], [3, 6, 9]]
[1, 2].zip(a, b) #=> [[1, 4, 7], [2, 5, 8]]
a.zip([1, 2], [8]) #=> [[4, 1, 8], [5, 2, nil], [6, nil, nil]]
3698 3699 3700 3701 3702 3703 3704 3705 3706 3707 3708 3709 3710 3711 3712 3713 3714 3715 3716 3717 3718 3719 3720 3721 3722 3723 3724 3725 3726 3727 3728 3729 3730 3731 3732 3733 3734 3735 3736 3737 3738 3739 3740 3741 3742 3743 3744 3745 3746 3747 3748 3749 3750 3751 3752 3753 3754 |
# File 'array.c', line 3698 static VALUE rb_ary_zip(int argc, VALUE *argv, VALUE ary) { int i, j; long len = RARRAY_LEN(ary); VALUE result = Qnil; for (i=0; i<argc; i++) { argv[i] = take_items(argv[i], len); } if (rb_block_given_p()) { int arity = rb_block_arity(); if (arity > 1) { VALUE work, *tmp; tmp = ALLOCV_N(VALUE, work, argc+1); for (i=0; i<RARRAY_LEN(ary); i++) { tmp[0] = RARRAY_AREF(ary, i); for (j=0; j<argc; j++) { tmp[j+1] = rb_ary_elt(argv[j], i); } rb_yield_values2(argc+1, tmp); } if (work) ALLOCV_END(work); } else { for (i=0; i<RARRAY_LEN(ary); i++) { VALUE tmp = rb_ary_new2(argc+1); rb_ary_push(tmp, RARRAY_AREF(ary, i)); for (j=0; j<argc; j++) { rb_ary_push(tmp, rb_ary_elt(argv[j], i)); } rb_yield(tmp); } } } else { result = rb_ary_new_capa(len); for (i=0; i<len; i++) { VALUE tmp = rb_ary_new_capa(argc+1); rb_ary_push(tmp, RARRAY_AREF(ary, i)); for (j=0; j<argc; j++) { rb_ary_push(tmp, rb_ary_elt(argv[j], i)); } rb_ary_push(result, tmp); } } return result; } |
#|(other_ary) ⇒ Array
Set Union — Returns a new array by joining ary
with other_ary
, excluding any duplicates and preserving the order from the given arrays.
It compares elements using their #hash and #eql? methods for efficiency.
[ "a", "b", "c" ] | [ "c", "d", "a" ] #=> [ "a", "b", "c", "d" ]
[ "c", "d", "a" ] | [ "a", "b", "c" ] #=> [ "c", "d", "a", "b" ]
See also Array#union.
4739 4740 4741 4742 4743 4744 4745 4746 4747 4748 4749 4750 4751 4752 4753 4754 4755 4756 4757 4758 |
# File 'array.c', line 4739 static VALUE rb_ary_or(VALUE ary1, VALUE ary2) { VALUE hash, ary3; ary2 = to_ary(ary2); if (RARRAY_LEN(ary1) + RARRAY_LEN(ary2) <= SMALL_ARRAY_LEN) { ary3 = rb_ary_new(); rb_ary_union(ary3, ary1); rb_ary_union(ary3, ary2); return ary3; } hash = ary_make_hash(ary1); rb_ary_union_hash(hash, ary2); ary3 = rb_hash_values(hash); ary_recycle_hash(hash); return ary3; } |