From 71df3a6f8a3fc2c5ed5377ea1145f70cf0c6c9e2 Mon Sep 17 00:00:00 2001 From: ocean Date: Tue, 13 Jul 2004 15:34:34 +0000 Subject: * array.c: rdoc patch. merged patch from Johan Holmberg [ruby-core:3170] git-svn-id: svn+ssh://ci.ruby-lang.org/ruby/branches/ruby_1_8@6622 b2dd03c8-39d4-4d8f-98ff-823fe69b080e --- ChangeLog | 5 ++ array.c | 224 +++++++++++++++++++++++++++++++------------------------------- 2 files changed, 118 insertions(+), 111 deletions(-) diff --git a/ChangeLog b/ChangeLog index 601fd4cfd4..1075d1a8d5 100644 --- a/ChangeLog +++ b/ChangeLog @@ -1,3 +1,8 @@ +Wed Jul 14 00:31:15 Hirokazu Yamamoto + + * array.c: rdoc patch. merged patch from Johan Holmberg + [ruby-core:3170] + Tue Jul 13 19:39:12 2004 akira yamada * lib/uri/generic.rb (URI::Generic#merge_path): diff --git a/array.c b/array.c index 48652fef58..b55c7389f2 100644 --- a/array.c +++ b/array.c @@ -79,7 +79,7 @@ rb_ary_freeze(ary) /* * call-seq: - * array.frozen? => true or false + * array.frozen? -> true or false * * Return true if this array is frozen (or temporarily frozen * while being sorted). @@ -226,7 +226,7 @@ static VALUE rb_ary_replace _((VALUE, VALUE)); * call-seq: * Array.new(size=0, obj=nil) * Array.new(array) - * Array.new(size) {|i| ...} + * Array.new(size) {|index| block } * Returns a new array. In the first form, the new array is * empty. In the second it is created with _size_ copies of _obj_ @@ -386,7 +386,7 @@ rb_ary_store(ary, idx, val) /* * call-seq: - * array << obj => array + * array << obj -> array * * Append---Pushes the given object on to the end of this array. This * expression returns the array itself, so several appends @@ -408,7 +408,7 @@ rb_ary_push(ary, item) /* * call-seq: - * array.push(obj, ... ) => array + * array.push(obj, ... ) -> array * * Append---Pushes the given object(s) on to the end of this array. This * expression returns the array itself, so several appends @@ -433,7 +433,7 @@ rb_ary_push_m(argc, argv, ary) /* * call-seq: - * array.pop => obj or nil + * array.pop -> obj or nil * * Removes the last element from self and returns it, or * nil if the array is empty. @@ -476,7 +476,7 @@ ary_make_shared(ary) /* * call-seq: - * array.shift => obj or nil + * array.shift -> obj or nil * * Returns the first element of self and removes it (shifting all * other elements down by one). Returns nil if the array @@ -528,7 +528,7 @@ rb_ary_unshift(ary, item) /* * call-seq: - * array.unshift(obj, ...) => array + * array.unshift(obj, ...) -> array * * Prepends objects to the front of array. * other elements up one. @@ -608,15 +608,15 @@ rb_ary_subseq(ary, beg, len) /* * call-seq: - * array[int] => obj or nil - * array[start, length] => an_array or nil - * array[range] => an_array or nil - * array.slice(int) => obj or nil - * array.slice(start, length) => an_array or nil - * array.slice(range) => an_array or nil + * array[index] -> obj or nil + * array[start, length] -> an_array or nil + * array[range] -> an_array or nil + * array.slice(index) -> obj or nil + * array.slice(start, length) -> an_array or nil + * array.slice(range) -> an_array or nil * - * Element Reference---Returns the element at index _int_, - * or returns a subarray starting at index _start_ and + * Element Reference---Returns the element at _index_, + * or returns a subarray starting at _start_ and * continuing for _length_ elements, or returns a subarray * specified by _range_. * Negative indices count backward from the end of the @@ -685,13 +685,13 @@ rb_ary_aref(argc, argv, ary) /* * call-seq: - * array.at(int) #=> obj or nil + * array.at(index) -> obj or nil * - * Returns the element at index int. A + * Returns the element at _index_. A * negative index counts from the end of _self_. Returns +nil+ - * if the index is out of range. See also Array.[]. - * (Array.at is slightly faster than Array.[], as it - * does not accept ranges and so on.) + * if the index is out of range. See also Array#[]. + * (Array#at is slightly faster than Array#[], + * as it does not accept ranges and so on.) * * a = [ "a", "b", "c", "d", "e" ] * a.at(0) #=> "a" @@ -707,7 +707,7 @@ rb_ary_at(ary, pos) /* * call-seq: - * array.first => obj or nil + * array.first -> obj or nil * * Returns the first element of the array. If the array is empty, * returns nil. @@ -743,8 +743,8 @@ rb_ary_first(argc, argv, ary) /* * call-seq: - * array.last => obj or nil - * array.last(n) => an_array + * array.last -> obj or nil + * array.last(n) -> an_array * * Returns the last element(s) of self. If the array is empty, * the first form returns nil. @@ -779,9 +779,9 @@ rb_ary_last(argc, argv, ary) /* * call-seq: - * array.fetch(index) => obj - * array.fetch(index, default ) => obj - * array.fetch(index) {|i| block } => obj + * array.fetch(index) -> obj + * array.fetch(index, default ) -> obj + * array.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 @@ -829,7 +829,7 @@ rb_ary_fetch(argc, argv, ary) /* * call-seq: - * array.index(obj) => int or nil + * array.index(obj) -> int or nil * * Returns the index of the first object in self such that is * == to obj. Returns nil if @@ -856,9 +856,9 @@ rb_ary_index(ary, val) /* * call-seq: - * array.rindex(obj) => int or nil + * array.rindex(obj) -> int or nil * - * Returns the index of the last object in arr + * Returns the index of the last object in array * == to obj. Returns nil if * no match is found. * @@ -883,8 +883,8 @@ rb_ary_rindex(ary, val) /* * call-seq: - * array.indexes( i1, i2, ... iN ) => an_array - * array.indices( i1, i2, ... iN ) => an_array + * array.indexes( i1, i2, ... iN ) -> an_array + * array.indices( i1, i2, ... iN ) -> an_array * * Deprecated; use Array#select. */ @@ -987,30 +987,30 @@ rb_ary_update(ary, beg, len, rpl) /* * call-seq: - * array[int] = obj => obj - * array[start, length] = an_array => an_array - * array[range] = an_array => an_array + * array[index] = obj -> obj + * array[start, length] = obj or an_array or nil -> obj or an_array or nil + * array[range] = obj or an_array or nil -> obj or an_array or nil * - * Element Assignment---Sets the element at index _int_, - * or replaces a subarray starting at index _start_ and + * 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 _int_ is greater than + * specified by _range_. If indices are greater than * the current capacity of the array, the array grows - * automatically. A negative _int_ will count backward + * automatically. A negative indices will count backward * from the end of the array. Inserts elements if _length_ is - * zero. If _an_array is +nil+, deletes elements from _self_. - * An +IndexError+ is raised if a + * zero. If +nil+ is used in the second and third form, + * deletes elements from _self_. An +IndexError+ is raised if a * negative index points past the beginning of the array. See also - * Array.push, and Array.unshift. + * Array#push, and Array#unshift. * * a = Array.new - * a[4] = "4"; - * a[0, 3] = [ 'a', 'b', 'c' ] - * a[1..2] = [ 1, 2 ]; - * a[0, 2] = "?"; - * a[0..2] = "A"; - * a[-1] = "Z"; - * a[1..-1] = nil; + * 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"] */ static VALUE @@ -1055,7 +1055,7 @@ fixnum: /* * call-seq: - * array.insert(index, obj...) => array + * array.insert(index, obj...) -> array * * Inserts the given values before the element with the given index * (which may be negative). @@ -1091,7 +1091,7 @@ rb_ary_insert(argc, argv, ary) /* * call-seq: - * array.each {|item| block } => array + * array.each {|item| block } -> array * * Calls block once for each element in self, passing that * element as a parameter. @@ -1118,7 +1118,7 @@ rb_ary_each(ary) /* * call-seq: - * array.each_index {|index| block } => array + * array.each_index {|index| block } -> array * * Same as Array#each, but passes the index of the element * instead of the element itself. @@ -1191,7 +1191,7 @@ rb_ary_length(ary) /* * call-seq: - * array.empty? => true or false + * array.empty? -> true or false * * Returns true if self array contains no elements. * @@ -1281,7 +1281,7 @@ rb_ary_join(ary, sep) /* * call-seq: - * array.join(sep=$,) => str + * array.join(sep=$,) -> str * * Returns a string created by converting each element of the array to * a string, separated by sep. @@ -1427,7 +1427,7 @@ inspect_ary(ary) /* * call-seq: - * array.inspect => string + * array.inspect -> string * * Create a printable version of array. */ @@ -1443,7 +1443,7 @@ rb_ary_inspect(ary) /* * call-seq: - * array.to_a => array + * array.to_a -> array * * Returns _self_. If called on a subclass of Array, converts * the receiver to an Array object. @@ -1498,7 +1498,7 @@ rb_ary_reverse(ary) /* * call-seq: - * array.reverse! => array + * array.reverse! -> array * * Reverses _self_ in place. * @@ -1578,8 +1578,8 @@ sort_unlock(ary) /* * call-seq: - * array.sort! => array - * array.sort! {| a,b | block } => array + * array.sort! -> array + * array.sort! {| a,b | block } -> array * * Sorts _self_. Comparisons for * the sort will be done using the <=> operator or using @@ -1606,8 +1606,8 @@ rb_ary_sort_bang(ary) /* * call-seq: - * array.sort => an_array - * array.sort {| a,b | block } => an_array + * array.sort -> an_array + * array.sort {| a,b | block } -> an_array * * Returns a new array created by sorting self. Comparisons for * the sort will be done using the <=> operator or using @@ -1631,8 +1631,8 @@ rb_ary_sort(ary) /* * call-seq: - * array.collect {|obj| block } -> an_array - * array.map {|obj| block } -> an_array + * array.collect {|item| block } -> an_array + * array.map {|item| block } -> an_array * * Invokes block once for each element of self. Creates a * new array containing the values returned by the block. @@ -1663,12 +1663,12 @@ rb_ary_collect(ary) /* * call-seq: - * array.collect! {|obj} ...} => array - * array.map! {|obj} ...} => array + * array.collect! {|item| block } -> array + * array.map! {|item| block } -> array * - * Invokes the block once for each element of _self_self, replacing the + * Invokes the block once for each element of _self_, replacing the * element with the value returned by _block_. - * See also Enumerable.collect. + * See also Enumerable#collect. * * a = [ "a", "b", "c", "d" ] * a.collect! {|x| x + "!" } @@ -1723,12 +1723,12 @@ rb_values_at(obj, olen, argc, argv, func) /* * call-seq: - * array.values_at(selector,... ) => an_array + * array.values_at(selector,... ) -> an_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 .select. + * See also Array#select. * * a = %w{ a b c d e f } * a.values_at(1, 3, 5) @@ -1748,9 +1748,9 @@ rb_ary_values_at(argc, argv, ary) /* * call-seq: - * array.select {|i| block } -> an_array + * array.select {|item| block } -> an_array * - * Invokes the block passing in successive elements from arr, + * Invokes the block passing in successive elements from array, * returning an array containing those elements for which the block * returns a true value (equivalent to Enumerable#select). * @@ -1781,8 +1781,8 @@ rb_ary_select(argc, argv, ary) /* * call-seq: - * array.delete(obj) => obj or nil - * array.delete(obj) {| | block } => obj or nil + * array.delete(obj) -> obj or nil + * array.delete(obj) { block } -> obj or nil * * Deletes items from self that are equal to obj. If * the item is not found, returns nil. If the optional @@ -1875,9 +1875,9 @@ rb_ary_delete_at_m(ary, pos) /* * call-seq: - * array.slice!(int) => obj or nil - * array.slice!(start, length) => sub_array or nil - * array.slice!(range) => sub_array or nil + * array.slice!(index) -> obj or nil + * array.slice!(start, length) -> sub_array or nil + * array.slice!(range) -> sub_array or nil * * Deletes the element(s) given by an index (optionally with a length) * or by a range. Returns the deleted object, subarray, or @@ -1929,7 +1929,7 @@ rb_ary_slice_bang(argc, argv, ary) /* * call-seq: - * array.reject! {| | block } -> array or nil + * array.reject! {|item| block } -> array or nil * * Equivalent to Array#delete_if, deleting elements from * _self_ for which the block evaluates to true, but returns @@ -1959,7 +1959,7 @@ rb_ary_reject_bang(ary) /* * call-seq: - * arr.reject {|item| block } -> an_array + * array.reject {|item| block } -> an_array * * Returns a new array containing the items in _self_ * for which the block is not true. @@ -2000,9 +2000,9 @@ rb_ary_delete_if(ary) * * 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 + * 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, + * the size of any argument is less than enumObj.size, * nil values are supplied. If a block given, it is * invoked for each output array, otherwise an array of arrays is * returned. @@ -2096,7 +2096,7 @@ rb_ary_transpose(ary) /* * call-seq: - * array.replace(other_array) => array + * array.replace(other_array) -> array * * Replaces the contents of self with the contents of * other_array, truncating or expanding if necessary. @@ -2125,9 +2125,10 @@ rb_ary_replace(copy, orig) } /* - * call-seq: - * array.clear => array - * Removes all elements from _self_. + * call-seq: + * array.clear -> array + * + * Removes all elements from _self_. * * a = [ "a", "b", "c", "d", "e" ] * a.clear #=> [ ] @@ -2148,17 +2149,17 @@ rb_ary_clear(ary) /* * call-seq: - * array.fill(obj) -> array - * array.fill(obj, start [, length]) => array - * array.fill(obj, range ) => array - * array.fill {|i| block } => array - * array.fill(start [, length] ) {|i| block } => array - * array.fill(range) {|i| block } => array + * array.fill(obj) -> array + * array.fill(obj, start [, length]) -> array + * array.fill(obj, range ) -> array + * array.fill {|index| block } -> array + * array.fill(start [, length] ) {|index| block } -> array + * array.fill(range) {|index| block } -> 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 arr.length. The last three + * nil is equivalent to self.length. The last three * forms fill the array with the value of the block. The block is * passed the absolute index of each element to be filled. * @@ -2243,7 +2244,7 @@ rb_ary_fill(argc, argv, ary) /* * call-seq: - * array + other_array => an_array + * array + other_array -> an_array * * Concatenation---Returns a new array built by concatenating the * two arrays together to produce a third array. @@ -2269,7 +2270,7 @@ rb_ary_plus(x, y) /* * call-seq: - * self.concat(other_array) => array + * array.concat(other_array) -> array * * Appends the elements in other_array to _self_. * @@ -2291,8 +2292,8 @@ rb_ary_concat(x, y) /* * call-seq: - * array * int => an_array - * array * str => a_string + * array * int -> an_array + * array * str -> a_string * * Repetition---With a String argument, equivalent to * self.join(str). Otherwise, returns a new array @@ -2300,6 +2301,7 @@ rb_ary_concat(x, y) * * * [ 1, 2, 3 ] * 3 #=> [ 1, 2, 3, 1, 2, 3, 1, 2, 3 ] + * [ 1, 2, 3 ] * "," #=> "1,2,3" * */ @@ -2338,7 +2340,7 @@ rb_ary_times(ary, times) /* * call-seq: - * array.assoc(obj) => an_array or nil + * array.assoc(obj) -> an_array or nil * * Searches through an array whose elements are also arrays * comparing _obj_ with the first element of each contained array @@ -2346,7 +2348,7 @@ rb_ary_times(ary, times) * Returns the first contained array that matches (that * is, the first associated array), * or +nil+ if no match is found. - * See also Array.rassoc. + * See also Array#rassoc. * * s1 = [ "colors", "red", "blue", "green" ] * s2 = [ "letters", "a", "b", "c" ] @@ -2410,7 +2412,7 @@ rb_ary_rassoc(ary, value) /* * call-seq: - * array == other_array => bool + * array == other_array -> bool * * Equality---Two arrays are equal if they contain the same number * of elements and if each element is equal to (according to @@ -2445,7 +2447,7 @@ rb_ary_equal(ary1, ary2) /* * call-seq: - * array.eql?(other) => true or false + * array.eql?(other) -> true or false * * Returns true if _array_ and _other_ are the same object, * or are both arrays with the same content. @@ -2469,7 +2471,7 @@ rb_ary_eql(ary1, ary2) /* * call-seq: - * array.hash => fixnum + * array.hash -> fixnum * * Compute a hash-code for this array. Two arrays with the same content * will have the same hash code (and will compare using eql?). @@ -2493,7 +2495,7 @@ rb_ary_hash(ary) /* * call-seq: - * array.include?(obj) => true or false + * array.include?(obj) -> true or false * * Returns true if the given object is present in * self (that is, if any object == anObject), @@ -2522,7 +2524,7 @@ rb_ary_includes(ary, item) /* * call-seq: - * array <=> other_array => -1, 0, +1 + * array <=> other_array -> -1, 0, +1 * * Comparison---Returns an integer (-1, 0, * or +1) if this array is less than, equal to, or greater than @@ -2531,7 +2533,7 @@ rb_ary_includes(ary, item) * equal, then that inequality is the return value. If all the * values found are equal, then the return is based on a * comparison of the array lengths. Thus, two arrays are - * ``equal'' according to Array.<=> if and only if they have + * ``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. * @@ -2583,7 +2585,7 @@ ary_make_hash(ary1, ary2) /* * call-seq: - * array - other_array => an_array + * array - other_array -> an_array * * Array Difference---Returns a new array that is a copy of * the original array, removing any items that also appear in @@ -2645,7 +2647,7 @@ rb_ary_and(ary1, ary2) /* * call-seq: - * array | other_array => an_array + * array | other_array -> an_array * * Set Union---Returns a new array by joining this array with * other_array, removing duplicates. @@ -2683,7 +2685,7 @@ rb_ary_or(ary1, ary2) /* * call-seq: - * array.uniq! => array or nil + * array.uniq! -> array or nil * * Removes duplicate elements from _self_. * Returns nil if no changes are made (that is, no @@ -2725,7 +2727,7 @@ rb_ary_uniq_bang(ary) /* * call-seq: - * array.uniq => an_array + * array.uniq -> an_array * * Returns a new array by removing duplicate values in self. * @@ -2744,10 +2746,10 @@ rb_ary_uniq(ary) /* * call-seq: - * array.compact! => array or nil + * array.compact! -> array or nil * * Removes +nil+ elements from array. - * Returns +niL+ if no changes were made. + * Returns +nil+ if no changes were made. * [ "a", nil, "b", nil, "c" ].compact! #=> [ "a", "b", "c" ] * [ "a", "b", "c" ].compact! #=> nil */ @@ -2777,7 +2779,7 @@ rb_ary_compact_bang(ary) /* * call-seq: - * array.compact => an_array + * array.compact -> an_array * * Returns a copy of _self_ with all +nil+ elements removed. * @@ -2851,11 +2853,11 @@ flatten(ary, idx, ary2, memo) /* * call-seq: - * arr.flatten! -> arr or nil + * array.flatten! -> array or nil * * Flattens _self_ in place. * Returns nil if no modifications were made (i.e., - * arr contains no subarrays.) + * array contains no subarrays.) * * a = [ 1, 2, [3, [4, 5] ] ] * a.flatten! #=> [1, 2, 3, 4, 5] -- cgit v1.2.3