Project

General

Profile

Download (67.4 KB)

Feature #6517 ยป 0001-Array-documentation-examples-and-formatting.patch

zzak (zzak _), 05/31/2012 09:28 AM

View differences:

array.c
}
}
/*
* call-seq:
* ary.freeze -> ary
*
* Calls Object#freeze on +ary+ to prevent any further
* modification. A +RuntimeError+ will be raised if a modification
* attempt is made.
*
*/
VALUE
rb_ary_freeze(VALUE ary)
{
......
* call-seq:
* ary.frozen? -> true or false
*
* Return <code>true</code> if this array is frozen (or temporarily frozen
* while being sorted).
* Return +true+ if this array is frozen (or temporarily frozen
* while being sorted). See also Object#frozen?
*/
static VALUE
......
*
* 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.
* 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]
*/
static VALUE
......
* ary.pop(n) -> new_ary
*
* Removes the last element from +self+ and returns it, or
* <code>nil</code> if the array is empty.
* +nil+ if the array is empty.
*
* If a number +n+ is given, returns an array of the last n elements
* (or less) just like <code>array.slice!(-n, n)</code> does.
* If a number +n+ is given, returns an array of the last +n+ elements
* (or less) just like <code>array.slice!(-n, n)</code> does. See also
* Array#push for the opposite effect.
*
* a = [ "a", "b", "c", "d" ]
* a.pop #=> "d"
......
* ary.shift(n) -> new_ary
*
* Returns the first element of +self+ and removes it (shifting all
* other elements down by one). Returns <code>nil</code> if the array
* 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 <code>array.slice!(0, n)</code> does.
* If a number +n+ is given, returns an array of the first +n+ elements
* (or less) just like <code>array.slice!(0, n)</code> 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"
......
* call-seq:
* ary.unshift(obj, ...) -> ary
*
* Prepends objects to the front of +self+,
* moving other elements upwards.
* 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"]
......
* call-seq:
* ary.at(index) -> obj or nil
*
* 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 <code>Array#[]</code>.
* 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
* <code>Array#[]</code>.
*
* a = [ "a", "b", "c", "d", "e" ]
* a.at(0) #=> "a"
......
*
* Returns the first element, or the first +n+ elements, of the array.
* If the array is empty, the first form returns <code>nil</code>, and the
* second form returns an empty array.
* second form returns an empty array. See also <code>Array#last</code> for
* the opposite effect.
*
* a = [ "q", "r", "s", "t" ]
* a.first #=> "q"
......
* ary.last(n) -> new_ary
*
* Returns the last element(s) of +self+. If the array is empty,
* the first form returns <code>nil</code>.
* the first form returns <code>nil</code>.
*
* See also <code>Array#first</code> for the opposite effect.
*
* a = [ "w", "x", "y", "z" ]
* a.last #=> "z"
......
* ary.fetch(index, default ) -> obj
* ary.fetch(index) {|index| block } -> obj
*
* Tries to return the element at position +index+. If the index lies outside
* the array, the first form throws an IndexError exception, the second form
* returns +default+, and the third form returns the value of invoking the
* block, passing in the index. Negative values of +index+ count from the end
* of the array.
*
* Tries to return the element at position +index+, but throws an IndexError
* exception if the referenced index lies outside of the array bounds. This
* 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 the second argument is a block it will
* only be executed when an invalid index is referenced. Negative values of
* +index+ count from the end of the array.
* +default+ value.
*
* Alternatively, if the second argument is a block 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
......
* call-seq:
* ary.index(obj) -> int or nil
* ary.index {|item| block} -> int or nil
* ary.index -> an_enumerator
* ary.index -> Enumerator
*
* Returns the _index_ of the first object in +self+ such that the object is
* <code>==</code> to +obj+.
*
* If a block is given instead of an argument, returns the _index_ of first
* the object for which the block returns +true+. Returns +nil+ if no match
* is found.
*
* Returns the index of the first object in +self+ such that the object is
* <code>==</code> to +obj+. If a block is given instead of an
* argument, returns index of first object for which <em>block</em> is true.
* Returns <code>nil</code> if no match is found.
* See also <code>Array#rindex</code>.
* See also Array#rindex.
*
* If neither block nor argument is given, an enumerator is returned instead.
* 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
*
* This is an alias of <code>#find_index</code>.
* This is an alias of Array#find_index.
*/
static VALUE
......
* call-seq:
* ary.rindex(obj) -> int or nil
* ary.rindex {|item| block} -> int or nil
* ary.rindex -> an_enumerator
* ary.rindex -> Enumerator
*
* Returns the _index_ of the last object in +self+ <code>==</code> to +obj+.
*
* If a block is given instead of an argument, returns _index_ of first object
* for which block returns +true+, starting from the last object.
*
* Returns +nil+ if no match is found.
*
* Returns the index of the last object in +self+
* <code>==</code> to +obj+. If a block is given instead of an
* argument, returns index of first object for which <em>block</em> is
* true, starting from the last object.
* Returns <code>nil</code> if no match is found.
* See also Array#index.
*
* If neither block nor argument is given, an enumerator is returned instead.
* If neither block nor argument is given, an Enumerator is returned instead.
*
* a = [ "a", "b", "b", "b", "c" ]
* a.rindex("b") #=> 3
......
* ary[start, length] = obj or other_ary or nil -> obj or other_ary or nil
* ary[range] = obj or other_ary or nil -> obj or other_ary or nil
*
* Element Assignment---Sets the element at +index+,
* or replaces a subarray starting at +start+ and
* continuing for +length+ elements, or replaces a subarray
* specified by +range+. If indices are greater than
* the current capacity of the array, the array grows
* automatically. A negative indices will count backward
* from the end of the array. Inserts elements if +length+ is
* zero. An IndexError is raised if a negative index points
* past the beginning of the array. See also
* Array#push, and Array#unshift.
* Element Assignment---Sets the element at _index_, or replaces a subarray
* from _start_ for _length_ elements, or replaces a subarray specified by
* _range_.
*
* If indices are greater than the current capacity of the array, the array
* grows automatically. A negative indices will count backward from the end of
* the array. Inserts elements if +length+ is zero.
*
* 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"]
......
* call-seq:
* ary.insert(index, obj...) -> ary
*
* Inserts the given values before the element with the given index
* (which may be negative).
* 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.
*
* a = %w{ a b c d }
* a.insert(2, 99) #=> ["a", "b", 99, "c", "d"]
......
/*
* call-seq:
* ary.each {|item| block } -> ary
* ary.each -> an_enumerator
* ary.each -> Enumerator
*
* Calls +block+ once for each element in +self+, passing that
* element as a parameter.
* Calls the given block once for each element in +self+, passing that element
* as a parameter.
*
* If no block is given, an enumerator is returned instead.
* An Enumerator is returned instead, if no block is given.
*
* a = [ "a", "b", "c" ]
* a.each {|x| print x, " -- " }
......
/*
* call-seq:
* ary.each_index {|index| block } -> ary
* ary.each_index -> an_enumerator
* ary.each_index -> Enumerator
*
* Same as Array#each, but passes the index of the element instead of the
* Same as Array#each, but passes the _index_ of the element instead of the
* element itself.
*
* If no block is given, an enumerator is returned instead.
* An Enumerator is returned instead, if no block is given.
*
*
* a = [ "a", "b", "c" ]
......
/*
* call-seq:
* ary.reverse_each {|item| block } -> ary
* ary.reverse_each -> an_enumerator
* ary.reverse_each -> Enumerator
*
* Same as Array#each, but traverses +self+ in reverse order.
*
......
* Returns the number of elements in +self+. May be zero.
*
* [ 1, 2, 3, 4, 5 ].length #=> 5
* [].length #=> 0
*/
static VALUE
......
* call-seq:
* ary.empty? -> true or false
*
* Returns <code>true</code> if +self+ contains no elements.
* Returns +true+ if +self+ contains no elements.
*
* [].empty? #=> true
*/
......
/*
* call-seq:
* ary.join(sep=$,) -> str
* ary.join(separator=$) -> str
*
* Returns a string created by converting each element of the array to
* a string, separated by +sep+.
* a string, separated by the given +separator+.
*
* [ "a", "b", "c" ].join #=> "abc"
* [ "a", "b", "c" ].join("-") #=> "a-b-c"
......
/*
* call-seq:
* ary.to_s -> string
* ary.inspect -> string
* ary.to_s -> string
*
* Creates a string representation of +self+.
*
* [ "a", "b", "c" ].to_s #=> "[\"a\", \"b\", \"c\"]"
*/
static VALUE
......
* call-seq:
* ary.to_a -> ary
*
* Returns +self+. If called on a subclass of Array, converts
* the receiver to an Array object.
* Returns +self+.
*
* If called on a subclass of Array, converts the receiver to an Array object.
*/
static VALUE
......
/*
* call-seq:
* ary.reverse -> new_ary
* ary.reverse -> new_ary
*
* Returns a new array containing +self+'s elements in reverse order.
*
......
/*
* call-seq:
* ary.rotate!(cnt=1) -> ary
* ary.rotate!(count=1) -> ary
*
* Rotates +self+ in place so that the element at +cnt+ comes first,
* and returns +self+. If +cnt+ is negative then it rotates in
* the opposite direction.
* 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"]
......
/*
* call-seq:
* ary.rotate(cnt=1) -> new_ary
* ary.rotate(count=1) -> new_ary
*
* Returns new array by rotating +self+ so that the element at +count+ is the
* first element of the new array.
*
* Returns new array by rotating +self+ so that the element at
* +cnt+ in +self+ is the first element of the new array. If +cnt+
* is negative then it rotates in the opposite direction.
* 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"]
......
* ary.sort! -> ary
* ary.sort! {| a,b | block } -> ary
*
* Sorts +self+. Comparisons for
* the sort will be done using the <code><=></code> operator or using
* an optional code block. The block implements a comparison between
* +a+ and +b+, returning -1, 0, or +1. See also
* Enumerable#sort_by.
* Sorts +self+.
*
* Comparisons for the sort will be done using the <code><=></code> operator
* or using an optional code block.
*
* The given block implements a comparison between +a+ and +b+, returning
* +-1+, +0+, or ++1+.
*
* See also Enumerable#sort_by.
*
* a = [ "d", "a", "e", "c", "b" ]
* a.sort! #=> ["a", "b", "c", "d", "e"]
......
* ary.sort -> new_ary
* ary.sort {| a,b | block } -> new_ary
*
* Returns a new array created by sorting +self+. Comparisons for
* the sort will be done using the <code><=></code> operator or using
* an optional code block. The block implements a comparison between
* +a+ and +b+, returning -1, 0, or +1. See also
* Enumerable#sort_by.
* Returns a new array created by sorting +self+.
*
* Comparisons for the sort will be done using the <code><=></code> operator
* or using an optional code block.
*
* The given block implements a comparison between +a+ and +b+, returning
* +-1+, +0+, or ++1+.
*
* See also Enumerable#sort_by.
*
* a = [ "d", "a", "e", "c", "b" ]
* a.sort #=> ["a", "b", "c", "d", "e"]
......
/*
* call-seq:
* ary.sort_by! {| obj | block } -> ary
* ary.sort_by! -> an_enumerator
* ary.sort_by! -> Enumerator
*
* Sorts +self+ in place using a set of keys generated by mapping the
* values in +self+ through the given block.
*
* If no block is given, an enumerator is returned instead.
* If no block is given, an Enumerator is returned instead.
*
*/
......
* call-seq:
* ary.collect {|item| block } -> new_ary
* ary.map {|item| block } -> new_ary
* ary.collect -> an_enumerator
* ary.map -> an_enumerator
* ary.collect -> Enumerator
* ary.map -> Enumerator
*
* Invokes the given block once for each element of +self+.
*
* Creates a new array containing the values returned by the given block.
*
* Invokes +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.
* If no block is given, an Enumerator is returned instead.
*
* a = [ "a", "b", "c", "d" ]
* a.map {|x| x + "!" } #=> ["a!", "b!", "c!", "d!"]
......
* call-seq:
* ary.collect! {|item| block } -> ary
* ary.map! {|item| block } -> ary
* ary.collect -> an_enumerator
* ary.map -> an_enumerator
* ary.collect -> Enumerator
* ary.map -> Enumerator
*
* Invokes the given block once for each element of +self+, replacing the
* element with the value returned by the block.
*
* Invokes the block once for each element of +self+, replacing the
* element with the value returned by +block+.
* See also Enumerable#collect.
*
* If no block is given, an enumerator is returned instead.
* If no block is given, an Enumerator is returned instead.
*
* a = [ "a", "b", "c", "d" ]
* a.map! {|x| x + "!" }
......
* call-seq:
* ary.values_at(selector,... ) -> new_ary
*
* Returns an array containing the elements in
* +self+ corresponding to the given selector(s). The selectors
* may be either integer indices or ranges.
* 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 }
......
/*
* call-seq:
* ary.select {|item| block } -> new_ary
* ary.select -> an_enumerator
* ary.select -> Enumerator
*
* Invokes the block passing in successive elements from +self+,
* returning an array containing those elements for which the block
* returns a true value (equivalent to Enumerable#select).
* Invokes the given block passing in successive elements from +self+,
* returning an array containing those elements for which the block returns
* a +true+ value.
*
* If no block is given, an enumerator is returned instead.
* See also Enumerable#select.
*
* If no block is given, an Enumerator is returned instead.
*
* a = %w{ a b c d e f }
* a.select {|v| v =~ /[aeiou]/} #=> ["a", "e"]
......
/*
* call-seq:
* ary.select! {|item| block } -> ary or nil
* ary.select! -> an_enumerator
* ary.select! -> Enumerator
*
* Invokes the given block passing in successive elements from +self+,
* deleting elements for which the block returns a +false+ value.
*
* If changes were made, it will return +self+, otherwise it returns +nil+.
*
* Invokes the block passing in successive elements from
* +self+, deleting elements for which the block returns a
* false value. It returns +self+ if changes were made,
* otherwise it returns <code>nil</code>.
* See also Array#keep_if
*
* If no block is given, an enumerator is returned instead.
* If no block is given, an Enumerator is returned instead.
*
*/
......
/*
* call-seq:
* ary.keep_if {|item| block } -> ary
* ary.keep_if -> an_enumerator
* ary.keep_if -> Enumerator
*
* Deletes every element of +self+ for which the given block evaluates to
* +false+.
*
* Deletes every element of +self+ for which +block+ evaluates
* to false.
* See also Array#select!
*
* If no block is given, an enumerator is returned instead.
* 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"]
......
* ary.delete(obj) { block } -> obj or nil
*
* Deletes items from +self+ that are equal to +obj+.
* If any items are found, returns +obj+. If
* the item is not found, returns <code>nil</code>. If the optional
* code block is given, returns the result of +block+ if the item
* is not found. (To remove <code>nil</code> elements and
* get an informative return value, use #compact!)
*
* If any items are found, returns +obj+, otherwise +nil+ is returned instead.
*
* 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"
......
* call-seq:
* ary.delete_at(index) -> obj or nil
*
* Deletes the element at the specified index, returning that element,
* or <code>nil</code> if the index is out of range. See also
* Array#slice!.
* 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"
......
* ary.slice!(start, length) -> new_ary or nil
* ary.slice!(range) -> new_ary or nil
*
* Deletes the element(s) given by an index (optionally with a length)
* or by a range. Returns the deleted object (or objects), or
* <code>nil</code> if the index is out of range.
* Deletes the element(s) given by an +index+ (optionally with a +length+) 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"
......
/*
* call-seq:
* ary.reject! {|item| block } -> ary or nil
* ary.reject! -> an_enumerator
* ary.reject! -> Enumerator
*
* Equivalent to Array#delete_if, deleting elements from +self+ for which the
* block evaluates to +true+, but returns +nil+ if no changes were made.
*
* The array is changed instantly every time the block is called, not after the iteration is over.
*
* Equivalent to Array#delete_if, deleting elements from
* +self+ for which the block evaluates to true, but returns
* <code>nil</code> if no changes were made.
* The array is changed instantly every time the block is called and
* not after the iteration is over.
* See also Enumerable#reject and Array#delete_if.
*
* If no block is given, an enumerator is returned instead.
* If no block is given, an Enumerator is returned instead.
*
*/
......
/*
* call-seq:
* ary.reject {|item| block } -> new_ary
* ary.reject -> an_enumerator
* ary.reject -> Enumerator
*
* Returns a new array containing the items in +self+ for which the given
* block is not +true+.
*
* Returns a new array containing the items in +self+
* for which the block is not true.
* See also Array#delete_if
*
* If no block is given, an enumerator is returned instead.
* If no block is given, an Enumerator is returned instead.
*
*/
......
/*
* call-seq:
* ary.delete_if {|item| block } -> ary
* ary.delete_if -> an_enumerator
* ary.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.
*
* Deletes every element of +self+ for which +block+ evaluates
* to true.
* The array is changed instantly every time the block is called and
* not after the iteration is over.
* See also Array#reject!
*
* If no block is given, an enumerator is returned instead.
* If no block is given, an Enumerator is returned instead.
*
* a = [ "a", "b", "c" ]
* a.delete_if {|x| x >= "b" } #=> ["a"]
......
* ary.zip(arg, ...) -> new_ary
* ary.zip(arg, ...) {| arr | block } -> nil
*
* Converts any arguments to arrays, then merges elements of
* +self+ with corresponding elements from each argument. This
* generates a sequence of <code>self.size</code> <em>n</em>-element
* arrays, where <em>n</em> is one more that the count of arguments. If
* the size of any argument is less than <code>enumObj.size</code>,
* <code>nil</code> values are supplied. If a block is given, it is
* invoked for each output array, otherwise an array of arrays is
* returned.
* Converts any arguments to arrays, then merges elements of +self+ with
* corresponding elements from each argument.
*
* This generates a sequence of +self.size+ _n_-element arrays, where _n_ is
* one more that the count of arguments.
*
* If the size of any argument is less than +enumObj.size+, +nil+ values are
* supplied.
*
* If a block is given, it is invoked for each output +array+, otherwise an
* array of arrays is returned.
*
* a = [ 4, 5, 6 ]
* b = [ 7, 8, 9 ]
......
* call-seq:
* ary.transpose -> new_ary
*
* Assumes that +self+ is an array of arrays and transposes the
* rows and columns.
* 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.
*/
static VALUE
......
* call-seq:
* ary.replace(other_ary) -> ary
*
* Replaces the contents of +self+ with the contents of
* +other_ary+, truncating or expanding if necessary.
* 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"]
......
* ary.fill(range) {|index| block } -> ary
*
* The first three forms set the selected elements of +self+ (which
* may be the entire array) to +obj+. A +start+ of
* <code>nil</code> is equivalent to zero. A +length+ of
* <code>nil</code> is equivalent to <code>self.length</code>. The last three
* forms fill the array with the value of the block. The block is
* passed the absolute index of each element to be filled.
* Negative values of +start+ count from the end of the array.
* may be the entire array) to +obj+.
*
* A +start+ of +nil+ is equivalent to zero.
*
* A +length+ of +nil+ is equivalent to +self.length+.
*
* The last three forms fill the array with the value of the 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"]
......
* two arrays together to produce a third array.
*
* [ 1, 2, 3 ] + [ 4, 5 ] #=> [ 1, 2, 3, 4, 5 ]
* a = [ "a", "b", "c" ]
* a + [ "d", "e", "f" ]
* a #=> [ "a", "b", "c", "d", "e", "f" ]
*/
VALUE
......
* Appends the elements of +other_ary+ to +self+.
*
* [ "a", "b" ].concat( ["c", "d"] ) #=> [ "a", "b", "c", "d" ]
* a = [ 1, 2, 3 ]
* a.concat( [ 4, 5 ] )
* a #=> [ 1, 2, 3, 4, 5 ]
*/
VALUE
rb_ary_concat(VALUE x, VALUE y)
{
......
* ary * str -> new_string
*
* Repetition---With a String argument, equivalent to
* self.join(str). Otherwise, returns a new array
* built by concatenating the +int+ copies of +self+.
* <code>self.join(str)</code>.
*
* 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 ]
......
* call-seq:
* ary.assoc(obj) -> new_ary or 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.
* Searches through an array whose elements are also arrays comparing +obj+
* with the first element of each contained array using <code>obj.==</code>.
*
* 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" ]
......
* call-seq:
* ary.rassoc(obj) -> new_ary or nil
*
* Searches through the array whose elements are also arrays. Compares
* +obj+ with the second element of each contained array using
* <code>==</code>. Returns the first contained array that matches. See
* also Array#assoc.
* Searches through the array whose elements are also arrays.
*
* Compares +obj+ with the second element of each contained array using
* <code>obj.==</code>.
*
* 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"]
......
* call-seq:
* ary == other_ary -> bool
*
* Equality---Two arrays are equal if they contain the same number
* of elements and if each element is equal to (according to
* Object.==) the corresponding element in the other array.
* 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
......
* call-seq:
* ary.eql?(other) -> true or false
*
* Returns <code>true</code> if +self+ and +other+ are the same object,
* Returns +true+ if +self+ and +other+ are the same object,
* or are both arrays with the same content.
*/
......
* call-seq:
* ary.hash -> fixnum
*
* Compute a hash-code for this array. Two arrays with the same content
* will have the same hash code (and will compare using <code>eql?</code>).
* Compute a hash-code for this array.
*
* Two arrays with the same content will have the same hash code (and will
* compare using +eql?+).
*/
static VALUE
......
* call-seq:
* ary.include?(object) -> true or false
*
* Returns <code>true</code> if the given +object+ is present in
* +self+ (that is, if any object <code>==</code> +object+),
* <code>false</code> otherwise.
* Returns +true+ if the given +object+ is present in +self+ (that is, if any
* object <code>==</code> +object+), otherwise returns +false+.
*
* a = [ "a", "b", "c" ]
* a.include?("b") #=> true
......
* call-seq:
* ary <=> other_ary -> -1, 0, +1 or nil
*
* Comparison---Returns an integer (-1, 0,
* or +1) if this array is less than, equal to, or greater than
* +other_ary+.
* Comparison---Returns an integer (+-1+, +0+, or <code>+1</code>) if this
* array is less than, equal to, or greater than +other_ary+.
*
* Each object in each array is compared (using Array#<=>).
*
* Arrays are compared in an "element-wise" manner; the first two elements
* that are not equal will determine the return value for the whole
* comparison.
*
* Each object in each array is compared (using <=>). Arrays are compared in
* an "element-wise" manner; the first two elements that are not equal will
* determine the return value for the whole comparison. If all the values
* are equal, then the return is based on a comparison of the array lengths.
* Thus, two arrays are "equal" according to Array#<=> if and only if they
* have the same length and the value of each element is equal to the
* value of the corresponding element in the other array.
* If all the values are equal, then the return is based on a comparison of
* the array lengths. Thus, two arrays are "equal" according to Array#<=> if,
* and only if, they have the same length and the value of each element is
* equal to the value of the corresponding element in the other array.
*
* [ "a", "a", "c" ] <=> [ "a", "b", "c" ] #=> -1
* [ 1, 2, 3, 4, 5, 6 ] <=> [ 1, 2 ] #=> +1
......
* call-seq:
* ary - other_ary -> new_ary
*
* Array Difference---Returns a new array that is a copy of
* the original array, removing any items that also appear in
* +other_ary+. (If you need set-like behavior, see the
* library class Set.)
* Array Difference---Returns a new array that is a copy of the original
* array, removing any items that also appear in +other_ary+. (If you need
* set-like behavior, see the library class Set.)
*
* [ 1, 1, 2, 2, 3, 3, 4, 5 ] - [ 1, 2, 4 ] #=> [ 3, 3, 5 ]
*/
......
* call-seq:
* ary & other_ary -> new_ary
*
* Set Intersection---Returns a new array
* containing elements common to the two arrays, with no duplicates.
* Set Intersection---Returns a new array containing elements common to the
* two arrays, excluding any duplicates.
*
* [ 1, 1, 3, 5 ] & [ 1, 2, 3 ] #=> [ 1, 3 ]
* [ 1, 1, 3, 5 ] & [ 1, 2, 3 ] #=> [ 1, 3 ]
* [ 'a', 'b', 'b', 'z' ] & [ 'a', 'b', 'c' ] #=> [ 'a', 'b' ]
*/
......
* call-seq:
* ary | other_ary -> new_ary
*
* Set Union---Returns a new array by joining this array with
* +other_ary+, removing duplicates.
* Set Union---Returns a new array by joining +ary+ with +other_ary+,
* excluding any duplicates.
*
* [ "a", "b", "c" ] | [ "c", "d", "a" ]
* #=> [ "a", "b", "c", "d" ]
* [ "a", "b", "c" ] | [ "c", "d", "a" ] #=> [ "a", "b", "c", "d" ]
*/
static VALUE
......
* ary.uniq! -> ary or nil
* ary.uniq! { |item| ... } -> ary or nil
*
* Removes duplicate elements from +self+. If a block is given,
* it will use the return value of the block for comparison.
* Returns <code>nil</code> if no changes are made (that is, no
* duplicates are found).
* Removes duplicate elements from +self+.
*
* If a block is given, it will use the return value of the block for
* comparison.
*
* Returns +nil+ if no changes are made (that is, no duplicates are found).
*
* a = [ "a", "a", "b", "b", "c" ]
* a.uniq! # => ["a", "b", "c"]
......
* ary.compact! -> ary or nil
*
* 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" ]
......
* ary.count(obj) -> int
* ary.count { |item| block } -> int
*
* Returns the number of elements. If an argument is given, counts
* the number of elements which equals to +obj+. If a block is
* given, counts the number of elements for which the block returns a true
* value.
* Returns the number of elements.
*
* If an argument is given, counts the number of elements which equals to
* +obj+ using <code>===</code>.
*
* 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.flatten!(level) -> array or nil
*
* Flattens +self+ in place.
* Returns <code>nil</code> if no modifications were made (i.e.,
* the array contains no subarrays.) If the optional +level+
* argument determines the level of recursion to flatten.
*
* 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]
......
* ary.flatten -> new_ary
* ary.flatten(level) -> new_ary
*
* Returns a new array that is a one-dimensional flattening of this
* array (recursively). That is, for every element that is an array,
* extract its elements into the new array. If the optional
* +level+ argument determines the level of recursion to flatten.
* 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]]
......
* ary.shuffle!(random: rng) -> ary
*
* Shuffles elements in +self+ in place.
* If +rng+ is given, it will be used as the random number generator.
*
* The optional +rng+ argument will be used as random number generator.
*/
static VALUE
......
* ary.shuffle -> new_ary
* ary.shuffle(random: rng) -> new_ary
*
* Returns a new array with elements of this array shuffled.
* Returns a new array with elements of +self+ shuffled.
*
* a = [ 1, 2, 3 ] #=> [1, 2, 3]
* a.shuffle #=> [2, 3, 1]
*
* If +rng+ is given, it will be used as the random number generator.
* The optional +rng+ argument will be used as the random number generator.
*
* a.shuffle(random: Random.new(1)) #=> [1, 3, 2]
*/
......
* ary.sample(n) -> new_ary
* ary.sample(n, random: rng) -> new_ary
*
* 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
* <code>nil</code> and the second form returns an empty array.
* Choose a random element or +n+ random elements from the array.
*
* If +rng+ is given, it will be used as the random number generator.
* 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.
*
* The optional +rng+ argument will be used as the random number generator.
*
* a = [ 1, 2, 3, 4, 5, 6, 7, 8, 9, 10 ]
* a.sample #=> 7
......
/*
* call-seq:
* ary.cycle(n=nil) {|obj| block } -> nil
* ary.cycle(n=nil) -> an_enumerator
* ary.cycle(n=nil) -> Enumerator
*
* Calls the given block for each element repeatedly +n+ times or forever if
* none or +nil+ is given.
*
* Calls +block+ for each element repeatedly +n+ times or
* forever if none or +nil+ is given. If a non-positive number is
* given or the array is empty, does nothing. Returns +nil+ if the
* loop has finished without getting interrupted.
* Does nothing if a non-positive number is given or the array is empty.
*
* If no block is given, an enumerator is returned instead.
* 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.
......
#define tmpary_discard(a) (ary_discard(a), RBASIC(a)->klass = rb_cArray)
/*
* Recursively compute permutations of r elements of the set [0..n-1].
* Recursively compute permutations of +r+ elements of the set
* <code>[0..n-1]</code>.
*
* When we have a complete permutation of array indexes, copy the values
* at those indexes into a new array and yield that array.
*
......
/*
* call-seq:
* ary.permutation { |p| block } -> ary
* ary.permutation -> an_enumerator
* ary.permutation -> Enumerator
* ary.permutation(n) { |p| block } -> ary
* ary.permutation(n) -> an_enumerator
* ary.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.
*
* 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.
* 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:
*
......
long r, n, i;
n = RARRAY_LEN(ary); /* Array length */
RETURN_ENUMERATOR(ary, argc, argv); /* Return enumerator if no block */
RETURN_ENUMERATOR(ary, argc, argv); /* Return Enumerator if no block */
rb_scan_args(argc, argv, "01", &num);
r = NIL_P(num) ? n : NUM2LONG(num); /* Permutation size from argument */
......
/*
* call-seq:
* ary.combination(n) { |c| block } -> ary
* ary.combination(n) -> an_enumerator
* ary.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.
*
* 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.
* The implementation makes no guarantees about the order in which the
* combinations are yielded.
*
* If no block is given, an enumerator is returned instead.
* If no block is given, an Enumerator is returned instead.
*
* Examples:
*
......
}
/*
* Recursively compute repeated permutations of r elements of the set
* [0..n-1].
* Recursively compute repeated permutations of +r+ elements of the set
* <code>[0..n-1]</code>.
*
* When we have a complete repeated permutation of array indexes, copy the
* values at those indexes into a new array and yield that array.
*
......
/*
* call-seq:
* ary.repeated_permutation(n) { |p| block } -> ary
* ary.repeated_permutation(n) -> an_enumerator
* ary.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.
* When invoked with a block, yield all repeated permutations of length +n+ of
* the elements of the array, then return the array itself.
*
* If no block is given, an enumerator is returned instead.
* 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:
*
......
long r, n, i;
n = RARRAY_LEN(ary); /* Array length */
RETURN_ENUMERATOR(ary, 1, &num); /* Return enumerator if no block */
RETURN_ENUMERATOR(ary, 1, &num); /* Return Enumerator if no block */
r = NUM2LONG(num); /* Permutation size from argument */
if (r < 0) {
......
/*
* call-seq:
* ary.repeated_combination(n) { |c| block } -> ary
* ary.repeated_combination(n) -> an_enumerator
* ary.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.
*
* 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.
* 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.
* If no block is given, an Enumerator is returned instead.
*
* Examples:
*
......
long n, i, len;
n = NUM2LONG(num); /* Combination size from argument */
RETURN_ENUMERATOR(ary, 1, &num); /* Return enumerator if no block */
RETURN_ENUMERATOR(ary, 1, &num); /* Return Enumerator if no block */
len = RARRAY_LEN(ary);
if (n < 0) {
/* yield nothing */
......
* ary.product(other_ary, ...) { |p| block } -> ary
*
* 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.
*
* 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]]
......
*
* Returns first +n+ elements from the array.
*
* If a non-positive number is given, raises an ArgumentError.
*
* a = [1, 2, 3, 4, 5, 0]
* a.take(3) #=> [1, 2, 3]
*
......
/*
* call-seq:
* ary.take_while {|arr| block } -> new_ary
* ary.take_while -> an_enumerator
* ary.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.
* 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.
* If no block is given, an Enumerator is returned instead.
*
* a = [1, 2, 3, 4, 5, 0]
* a.take_while {|i| i < 3 } #=> [1, 2]
......
* call-seq:
* ary.drop(n) -> new_ary
*
* Drops first n elements from +ary+ and returns the rest of
* the elements in an array.
* Drops first +n+ elements from +ary+ and returns the rest of the elements in
* an array.
*
* If a non-positive number is given, raises an ArgumentError.
*
* a = [1, 2, 3, 4, 5, 0]
* a.drop(3) #=> [4, 5, 0]
......
/*
* call-seq:
* ary.drop_while {|arr| block } -> new_ary
* ary.drop_while -> an_enumerator
* ary.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.
* 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.
* If no block is given, an Enumerator is returned instead.
*
* a = [1, 2, 3, 4, 5, 0]
* a.drop_while {|i| i < 3 } #=> [3, 4, 5, 0]
......
}
/*
* 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
* <code>[]</code>. 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) #=> [0, 0, 0]
*
* Note that the second argument populates the array with references the same
* object. Therefore, it is only recommended in cases when you need to
* instantiate arrays with natively immutable objects such 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 } #=> [{}, {}, {}, {}]
*
* 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]]
*
* == 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.
*
* 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]
*
* 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
* <code><<</code>
*
* 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) #=> [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 a non-destructive (#uniq) and a 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]
... This diff was truncated because it exceeds the maximum size that can be displayed.
    (1-1/1)