ruby-changes:15844
From: marcandre <ko1@a...>
Date: Thu, 13 May 2010 14:52:34 +0900 (JST)
Subject: [ruby-changes:15844] Ruby:r27778 (ruby_1_9_2): * array.c: Harmonize documentation, in particular regarding:
marcandre 2010-05-13 14:52:16 +0900 (Thu, 13 May 2010) New Revision: 27778 http://svn.ruby-lang.org/cgi-bin/viewvc.cgi?view=rev&revision=27778 Log: * array.c: Harmonize documentation, in particular regarding: - methods returning enumerators - array methods and argument naming (array -> ary, an_array -> new_ary) - minor improvements, typo fixed and styling issues Other documentation errors fixed: - return value was self instead of a new array (or vice-versa) for Array#{pop,shift,permutation,repeated_permutation,keep_if} - Array#rindex was missing the form with a block. * dir.c: ditto. * enum.c: ditto. Modified Enumerable#reverse_each' documentation to clarify that #each will be finish before any element is yielded. * error.c: ditto. * gc.c: ditto. * hash.c: ditto. * io.c: ditto. IO#{codepoints,each_codepoint} fixed as per [ruby-core:23948] * numeric.c: ditto. * range.c: ditto. * string.c: ditto. * struct.c: ditto. * vm_eval.c: ditto. Modified files: branches/ruby_1_9_2/array.c branches/ruby_1_9_2/dir.c branches/ruby_1_9_2/enum.c branches/ruby_1_9_2/error.c branches/ruby_1_9_2/gc.c branches/ruby_1_9_2/hash.c branches/ruby_1_9_2/io.c branches/ruby_1_9_2/numeric.c branches/ruby_1_9_2/range.c branches/ruby_1_9_2/string.c branches/ruby_1_9_2/struct.c branches/ruby_1_9_2/vm_eval.c Index: ruby_1_9_2/array.c =================================================================== --- ruby_1_9_2/array.c (revision 27777) +++ ruby_1_9_2/array.c (revision 27778) @@ -278,7 +278,7 @@ /* * call-seq: - * array.frozen? -> true or false + * ary.frozen? -> true or false * * Return <code>true</code> if this array is frozen (or temporarily frozen * while being sorted). @@ -474,9 +474,9 @@ * call-seq: * Array.try_convert(obj) -> array or nil * - * Try to convert <i>obj</i> into an array, using to_ary method. - * Returns converted array or nil if <i>obj</i> cannot be converted - * for any reason. This method is to check if an argument is an + * Try to convert <i>obj</i> into an array, using +to_ary+ method. + * Returns converted array or +nil+ if <i>obj</i> cannot be converted + * for any reason. This method can be used to check if an argument is an * array. * * Array.try_convert([1]) # => [1] @@ -704,7 +704,7 @@ /* * call-seq: - * array << obj -> array + * ary << obj -> ary * * Append---Pushes the given object on to the end of this array. This * expression returns the array itself, so several appends @@ -737,7 +737,7 @@ /* * call-seq: - * array.push(obj, ... ) -> array + * ary.push(obj, ... ) -> ary * * Append---Pushes the given object(s) on to the end of this array. This * expression returns the array itself, so several appends @@ -777,10 +777,10 @@ /* * call-seq: - * array.pop -> obj or nil - * array.pop(n) -> array + * ary.pop -> obj or nil + * ary.pop(n) -> new_ary * - * Removes the last element from <i>self</i> and returns it, or + * Removes the last element from +self+ and returns it, or * <code>nil</code> if the array is empty. * * If a number _n_ is given, returns an array of the last n elements @@ -837,10 +837,10 @@ /* * call-seq: - * array.shift -> obj or nil - * array.shift(n) -> array + * ary.shift -> obj or nil + * ary.shift(n) -> new_ary * - * Returns the first element of <i>self</i> and removes it (shifting all + * Returns the first element of +self+ and removes it (shifting all * other elements down by one). Returns <code>nil</code> if the array * is empty. * @@ -885,10 +885,10 @@ /* * call-seq: - * array.unshift(obj, ...) -> array + * ary.unshift(obj, ...) -> ary * - * Prepends objects to the front of <i>array</i>. - * other elements up one. + * Prepends objects to the front of +self+, + * moving other elements upwards. * * a = [ "b", "c", "d" ] * a.unshift("a") #=> ["a", "b", "c", "d"] @@ -959,19 +959,19 @@ /* * call-seq: - * 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 + * ary[index] -> obj or nil + * ary[start, length] -> new_ary or nil + * ary[range] -> new_ary or nil + * ary.slice(index) -> obj or nil + * ary.slice(start, length) -> new_ary or nil + * ary.slice(range) -> new_ary or nil * * Element Reference---Returns the element at _index_, * or returns a subarray starting at _start_ and * continuing for _length_ elements, or returns a subarray * specified by _range_. * Negative indices count backward from the end of the - * array (-1 is the last element). Returns nil if the index + * array (-1 is the last element). Returns +nil+ if the index * (or starting index) are out of range. * * a = [ "a", "b", "c", "d", "e" ] @@ -1025,10 +1025,10 @@ /* * call-seq: - * array.at(index) -> obj or nil + * ary.at(index) -> obj or nil * * Returns the element at _index_. A - * negative index counts from the end of _self_. Returns +nil+ + * 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" ] @@ -1044,8 +1044,8 @@ /* * call-seq: - * array.first -> obj or nil - * array.first(n) -> an_array + * ary.first -> obj or nil + * ary.first(n) -> new_ary * * 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 @@ -1070,10 +1070,10 @@ /* * call-seq: - * array.last -> obj or nil - * array.last(n) -> an_array + * ary.last -> obj or nil + * ary.last(n) -> new_ary * - * Returns the last element(s) of <i>self</i>. If the array is empty, + * Returns the last element(s) of +self+. If the array is empty, * the first form returns <code>nil</code>. * * a = [ "w", "x", "y", "z" ] @@ -1095,9 +1095,9 @@ /* * call-seq: - * array.fetch(index) -> obj - * array.fetch(index, default ) -> obj - * array.fetch(index) {|index| block } -> obj + * ary.fetch(index) -> obj + * ary.fetch(index, default ) -> obj + * ary.fetch(index) {|index| block } -> obj * * Tries to return the element at position <i>index</i>. If the index * lies outside the array, the first form throws an @@ -1143,14 +1143,18 @@ /* * call-seq: - * array.index(obj) -> int or nil - * array.index {|item| block} -> int or nil + * ary.index(obj) -> int or nil + * ary.index {|item| block} -> int or nil + * ary.index -> an_enumerator * - * Returns the index of the first object in <i>self</i> such that is + * Returns the index of the first object in +self+ such that is * <code>==</code> to <i>obj</i>. If a block is given instead of an * argument, returns first object for which <em>block</em> is true. * Returns <code>nil</code> if no match is found. + * See also <code>Array#rindex</code>. * + * If neither block nor argument is given, an enumerator is returned instead. + * * a = [ "a", "b", "c" ] * a.index("b") #=> 1 * a.index("z") #=> nil @@ -1186,13 +1190,19 @@ /* * call-seq: - * array.rindex(obj) -> int or nil + * ary.rindex(obj) -> int or nil + * ary.rindex {|item| block} -> int or nil + * ary.rindex -> an_enumerator * - * Returns the index of the last object in <i>array</i> + * Returns the index of the last object in +self+ * <code>==</code> to <i>obj</i>. If a block is given instead of an * argument, returns first object for which <em>block</em> is - * true. Returns <code>nil</code> if no match is found. + * true, starting from the last object. + * Returns <code>nil</code> if no match is found. + * See also <code>Array#index</code>. * + * 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 @@ -1298,9 +1308,9 @@ /* * call-seq: - * 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 + * ary[index] = obj -> obj + * 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 @@ -1358,7 +1368,7 @@ /* * call-seq: - * array.insert(index, obj...) -> array + * ary.insert(index, obj...) -> ary * * Inserts the given values before the element with the given index * (which may be negative). @@ -1391,11 +1401,14 @@ /* * call-seq: - * array.each {|item| block } -> array + * ary.each {|item| block } -> ary + * ary.each -> an_enumerator * - * Calls <i>block</i> once for each element in <i>self</i>, passing that + * Calls <i>block</i> once for each element in +self+, passing that * element as a parameter. * + * If no block is given, an enumerator is returned instead. + * * a = [ "a", "b", "c" ] * a.each {|x| print x, " -- " } * @@ -1418,11 +1431,15 @@ /* * call-seq: - * array.each_index {|index| block } -> array + * ary.each_index {|index| block } -> ary + * ary.each_index -> an_enumerator * * Same as <code>Array#each</code>, but passes the index of the element * instead of the element itself. * + * If no block is given, an enumerator is returned instead. + * + * * a = [ "a", "b", "c" ] * a.each_index {|x| print x, " -- " } * @@ -1445,9 +1462,10 @@ /* * call-seq: - * array.reverse_each {|item| block } + * ary.reverse_each {|item| block } -> ary + * ary.reverse_each -> an_enumerator * - * Same as <code>Array#each</code>, but traverses <i>self</i> in reverse + * Same as <code>Array#each</code>, but traverses +self+ in reverse * order. * * a = [ "a", "b", "c" ] @@ -1476,9 +1494,9 @@ /* * call-seq: - * array.length -> int + * ary.length -> int * - * Returns the number of elements in <i>self</i>. May be zero. + * Returns the number of elements in +self+. May be zero. * * [ 1, 2, 3, 4, 5 ].length #=> 5 */ @@ -1492,9 +1510,9 @@ /* * call-seq: - * array.empty? -> true or false + * ary.empty? -> true or false * - * Returns <code>true</code> if <i>self</i> array contains no elements. + * Returns <code>true</code> if +self+ contains no elements. * * [].empty? #=> true */ @@ -1659,7 +1677,7 @@ /* * call-seq: - * array.join(sep=$,) -> str + * ary.join(sep=$,) -> str * * Returns a string created by converting each element of the array to * a string, separated by <i>sep</i>. @@ -1704,10 +1722,10 @@ /* * call-seq: - * array.to_s -> string - * array.inspect -> string + * ary.to_s -> string + * ary.inspect -> string * - * Create a printable version of <i>array</i>. + * Creates a string representation of +self+. */ static VALUE @@ -1725,9 +1743,9 @@ /* * call-seq: - * array.to_a -> array + * ary.to_a -> ary * - * Returns _self_. If called on a subclass of Array, converts + * Returns +self+. If called on a subclass of Array, converts * the receiver to an Array object. */ @@ -1744,9 +1762,9 @@ /* * call-seq: - * array.to_ary -> array + * ary.to_ary -> ary * - * Returns _self_. + * Returns +self+. */ static VALUE @@ -1782,9 +1800,9 @@ /* * call-seq: - * array.reverse! -> array + * ary.reverse! -> ary * - * Reverses _self_ in place. + * Reverses +self+ in place. * * a = [ "a", "b", "c" ] * a.reverse! #=> ["c", "b", "a"] @@ -1799,9 +1817,9 @@ /* * call-seq: - * array.reverse -> an_array + * ary.reverse -> new_ary * - * Returns a new array containing <i>self</i>'s elements in reverse order. + * Returns a new array containing +self+'s elements in reverse order. * * [ "a", "b", "c" ].reverse #=> ["c", "b", "a"] * [ 1 ].reverse #=> [1] @@ -1850,10 +1868,10 @@ /* * call-seq: - * array.rotate!([cnt = 1]) -> array + * ary.rotate!(cnt=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 + * Rotates +self+ in place so that the element at +cnt+ comes first, + * and returns +self+. If +cnt+ is negative then it rotates in * counter direction. * * a = [ "a", "b", "c", "d" ] @@ -1879,10 +1897,10 @@ /* * call-seq: - * array.rotate([n = 1]) -> an_array + * ary.rotate([n = 1]) -> new_ary * - * Returns new array by rotating _self_, whose first element is the - * element at +cnt+ in _self_. If +cnt+ is negative then it rotates + * Returns new array by rotating +self+, whose first element is the + * element at +cnt+ in +self+. If +cnt+ is negative then it rotates * in counter direction. * * a = [ "a", "b", "c", "d" ] @@ -1988,10 +2006,10 @@ /* * call-seq: - * array.sort! -> array - * array.sort! {| a,b | block } -> array + * ary.sort! -> ary + * ary.sort! {| a,b | block } -> ary * - * Sorts _self_. Comparisons for + * 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 * <i>a</i> and <i>b</i>, returning -1, 0, or +1. See also @@ -2064,10 +2082,10 @@ /* * call-seq: - * array.sort -> an_array - * array.sort {| a,b | block } -> an_array + * ary.sort -> new_ary + * ary.sort {| a,b | block } -> new_ary * - * Returns a new array created by sorting <i>self</i>. Comparisons for + * 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 * <i>a</i> and <i>b</i>, returning -1, 0, or +1. See also @@ -2095,10 +2113,14 @@ /* * call-seq: - * array.sort_by! {| obj | block } -> array + * ary.sort_by! {| obj | block } -> ary + * ary.sort_by! -> an_enumerator * - * Sorts <i>array</i> in place using a set of keys generated by mapping the - * values in <i>array</i> through the given block. + * 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. + * */ static VALUE @@ -2116,13 +2138,17 @@ /* * call-seq: - * array.collect {|item| block } -> an_array - * array.map {|item| block } -> an_array + * ary.collect {|item| block } -> new_ary + * ary.map {|item| block } -> new_ary + * ary.collect -> an_enumerator + * ary.map -> an_enumerator * - * Invokes <i>block</i> once for each element of <i>self</i>. Creates a + * Invokes <i>block</i> once for each element of +self+. Creates a * new array containing the values returned by the block. * See also <code>Enumerable#collect</code>. * + * If no block is given, an enumerator is returned instead. + * * a = [ "a", "b", "c", "d" ] * a.collect {|x| x + "!" } #=> ["a!", "b!", "c!", "d!"] * a #=> ["a", "b", "c", "d"] @@ -2145,13 +2171,17 @@ /* * call-seq: - * array.collect! {|item| block } -> array - * array.map! {|item| block } -> array + * ary.collect! {|item| block } -> ary + * ary.map! {|item| block } -> ary + * ary.collect -> an_enumerator + * ary.map -> an_enumerator * - * Invokes the block once for each element of _self_, replacing the + * Invokes the block once for each element of +self+, replacing the * element with the value returned by _block_. * See also <code>Enumerable#collect</code>. * + * If no block is given, an enumerator is returned instead. + * * a = [ "a", "b", "c", "d" ] * a.collect! {|x| x + "!" } * a #=> [ "a!", "b!", "c!", "d!" ] @@ -2200,10 +2230,10 @@ /* * call-seq: - * array.values_at(selector,... ) -> an_array + * ary.values_at(selector,... ) -> new_ary * * Returns an array containing the elements in - * _self_ corresponding to the given selector(s). The selectors + * +self+ corresponding to the given selector(s). The selectors * may be either integer indices or ranges. * See also <code>Array#select</code>. * @@ -2223,12 +2253,15 @@ /* * call-seq: - * array.select {|item| block } -> an_array + * ary.select {|item| block } -> new_ary + * ary.select -> an_enumerator * - * Invokes the block passing in successive elements from <i>array</i>, + * 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 <code>Enumerable#select</code>). * + * 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"] */ @@ -2251,12 +2284,17 @@ /* * call-seq: - * array.select! {|item| block } -> an_array + * ary.select! {|item| block } -> new_ary or nil + * ary.select! -> an_enumerator * * Invokes the block passing in successive elements from - * <i>array</i>, deleting elements for which the block returns a - * false value. but returns <code>nil</code> if no changes were - * made. Also see <code>Array#keep_if</code> + * +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 <code>Array#keep_if</code> + * + * If no block is given, an enumerator is returned instead. + * */ static VALUE @@ -2283,11 +2321,15 @@ /* * call-seq: - * array.keep_if {|item| block } -> an_array + * ary.keep_if {|item| block } -> ary + * ary.keep_if -> an_enumerator * - * Deletes every element of <i>self</i> for which <i>block</i> evaluates - * to <code>false</code>. + * Deletes every element of +self+ for which <i>block</i> evaluates + * to false. + * See also <code>Array#select!</code> * + * 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"] */ @@ -2302,10 +2344,10 @@ /* * call-seq: - * array.delete(obj) -> obj or nil - * array.delete(obj) { block } -> obj or nil + * ary.delete(obj) -> obj or nil + * ary.delete(obj) { block } -> obj or nil * - * Deletes items from <i>self</i> that are equal to <i>obj</i>. + * Deletes items from +self+ that are equal to <i>obj</i>. * If any items are found, returns <i>obj</i>. If * the item is not found, returns <code>nil</code>. If the optional * code block is given, returns the result of <i>block</i> if the item @@ -2379,7 +2421,7 @@ /* * call-seq: - * array.delete_at(index) -> obj or nil + * 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 @@ -2399,12 +2441,12 @@ /* * call-seq: - * array.slice!(index) -> obj or nil - * array.slice!(start, length) -> sub_array or nil - * array.slice!(range) -> sub_array or nil + * ary.slice!(index) -> obj or nil + * 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, subarray, or + * or by a range. Returns the deleted object (or objects), or * <code>nil</code> if the index is out of range. * * a = [ "a", "b", "c" ] @@ -2469,12 +2511,16 @@ /* * call-seq: - * array.reject! {|item| block } -> array or nil + * ary.reject! {|item| block } -> ary or nil + * ary.reject! -> an_enumerator * * Equivalent to <code>Array#delete_if</code>, deleting elements from - * _self_ for which the block evaluates to true, but returns - * <code>nil</code> if no changes were made. Also see - * <code>Enumerable#reject</code>. + * +self+ for which the block evaluates to true, but returns + * <code>nil</code> if no changes were made. + * See also <code>Enumerable#reject</code> and <code>Array#delete_if</code>. + * + * If no block is given, an enumerator is returned instead. + * */ static VALUE @@ -2501,10 +2547,15 @@ /* * call-seq: - * array.reject {|item| block } -> an_array + * ary.reject {|item| block } -> new_ary + * ary.reject -> an_enumerator * - * Returns a new array containing the items in _self_ + * Returns a new array containing the items in +self+ * for which the block is not true. + * See also <code>Array#delete_if</code> + * + * If no block is given, an enumerator is returned instead. + * */ static VALUE @@ -2518,11 +2569,15 @@ /* * call-seq: - * array.delete_if {|item| block } -> array + * ary.delete_if {|item| block } -> ary + * ary.delete_if -> an_enumerator * - * Deletes every element of <i>self</i> for which <i>block</i> evaluates - * to <code>true</code>. + * Deletes every element of +self+ for which <i>block</i> evaluates + * to true. + * See also <code>Array#reject!</code> * + * If no block is given, an enumerator is returned instead. + * * a = [ "a", "b", "c" ] * a.delete_if {|x| x >= "b" } #=> ["a"] */ @@ -2560,15 +2615,15 @@ /* * call-seq: - * array.zip(arg, ...) -> an_array - * array.zip(arg, ...) {| arr | block } -> nil + * ary.zip(arg, ...) -> new_ary + * ary.zip(arg, ...) {| arr | block } -> nil * * Converts any arguments to arrays, then merges elements of - * <i>self</i> with corresponding elements from each argument. This + * +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 given, it is + * <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. * @@ -2613,9 +2668,9 @@ /* * call-seq: - * array.transpose -> an_array + * ary.transpose -> new_ary * - * Assumes that <i>self</i> is an array of arrays and transposes the + * Assumes that +self+ is an array of arrays and transposes the * rows and columns. * * a = [[1,2], [3,4], [5,6]] @@ -2652,10 +2707,10 @@ /* * call-seq: - * array.replace(other_array) -> array + * ary.replace(other_ary) -> ary * - * Replaces the contents of <i>self</i> with the contents of - * <i>other_array</i>, truncating or expanding if necessary. + * Replaces the contents of +self+ with the contents of + * <i>other_ary</i>, truncating or expanding if necessary. * * a = [ "a", "b", "c", "d", "e" ] * a.replace([ "x", "y", "z" ]) #=> ["x", "y", "z"] @@ -2706,9 +2761,9 @@ /* * call-seq: - * array.clear -> array + * ary.clear -> ary * - * Removes all elements from _self_. + * Removes all elements from +self+. * * a = [ "a", "b", "c", "d", "e" ] * a.clear #=> [ ] @@ -2727,14 +2782,14 @@ /* * call-seq: - * 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 + * ary.fill(obj) -> ary + * ary.fill(obj, start [, length]) -> ary + * ary.fill(obj, range ) -> ary + * ary.fill {|index| block } -> ary + * ary.fill(start [, length] ) {|index| block } -> ary + * ary.fill(range) {|index| block } -> ary * - * The first three forms set the selected elements of <i>self</i> (which + * The first three forms set the selected elements of +self+ (which * may be the entire array) to <i>obj</i>. A <i>start</i> of * <code>nil</code> is equivalent to zero. A <i>length</i> of * <code>nil</code> is equivalent to <i>self.length</i>. The last three @@ -2823,7 +2878,7 @@ /* * call-seq: - * array + other_array -> an_array + * ary + other_ary -> new_ary * * Concatenation---Returns a new array built by concatenating the * two arrays together to produce a third array. @@ -2848,9 +2903,9 @@ /* * call-seq: - * array.concat(other_array) -> array + * ary.concat(other_ary) -> ary * - * Appends the elements in other_array to _self_. + * Appends the elements of <i>other_ary</i> to +self+. * * [ "a", "b" ].concat( ["c", "d"] ) #=> [ "a", "b", "c", "d" ] */ @@ -2870,12 +2925,12 @@ /* * call-seq: - * array * int -> an_array - * array * str -> a_string + * ary * int -> new_ary + * 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_. + * built by concatenating the _int_ copies of +self+. * * * [ 1, 2, 3 ] * 3 #=> [ 1, 2, 3, 1, 2, 3, 1, 2, 3 ] @@ -2924,7 +2979,7 @@ /* * call-seq: - * array.assoc(obj) -> an_array or nil + * 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 @@ -2959,7 +3014,7 @@ /* * call-seq: - * array.rassoc(obj) -> an_array or nil + * 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 @@ -3002,7 +3057,7 @@ /* * call-seq: - * array == other_array -> bool + * 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 @@ -3043,9 +3098,9 @@ /* * call-seq: - * array.eql?(other) -> true or false + * ary.eql?(other) -> true or false * - * Returns <code>true</code> if _array_ and _other_ are the same object, + * Returns <code>true</code> if +self+ and _other_ are the same object, * or are both arrays with the same content. */ @@ -3081,7 +3136,7 @@ /* * call-seq: - * array.hash -> fixnum + * 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>). @@ -3095,10 +3150,10 @@ /* * call-seq: - * array.include?(obj) -> true or false + * ary.include?(obj) -> true or false * * Returns <code>true</code> if the given object is present in - * <i>self</i> (that is, if any object <code>==</code> <i>anObject</i>), + * +self+ (that is, if any object <code>==</code> <i>anObject</i>), * <code>false</code> otherwise. * * a = [ "a", "b", "c" ] @@ -3141,11 +3196,11 @@ /* * call-seq: - * array <=> other_array -> -1, 0, +1 or nil + * 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_array. Each object in each array is compared + * <i>other_ary</i>. Each object in each array is compared * (using <=>). If any value isn't * equal, then that inequality is the return value. If all the * values found are equal, then the return is based on a @@ -3236,11 +3291,11 @@ /* * call-seq: - * array - other_array -> an_array + * 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_array. (If you need set-like behavior, see the + * <i>other_ary</i>. (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 ] @@ -3266,7 +3321,7 @@ /* * call-seq: - * array & other_array + * ary & other_ary -> new_ary * * Set Intersection---Returns a new array * containing elements common to the two arrays, with no duplicates. @@ -3302,10 +3357,10 @@ /* * call-seq: - * array | other_array -> an_array + * ary | other_ary -> new_ary * * Set Union---Returns a new array by joining this array with - * other_array, removing duplicates. + * <i>other_ary</i>, removing duplicates. * * [ "a", "b", "c" ] | [ "c", "d", "a" ] * #=> [ "a", "b", "c", "d" ] @@ -3347,9 +3402,9 @@ /* * call-seq: - * array.uniq! -> array or nil + * ary.uniq! -> ary or nil * - * Removes duplicate elements from _self_. + * Removes duplicate elements from +self+. * Returns <code>nil</code> if no changes are made (that is, no * duplicates are found). * @@ -3399,9 +3454,9 @@ /* * call-seq: - * array.uniq -> an_array + * ary.uniq -> new_ary * - * Returns a new array by removing duplicate values in <i>self</i>. + * Returns a new array by removing duplicate values in +self+. * * a = [ "a", "a", "b", "b", "c" ] * a.uniq #=> ["a", "b", "c"] @@ -3439,11 +3494,11 @@ /* * call-seq: - * array.compact! -> array or nil + * ary.compact! -> ary or nil * - * Removes +nil+ elements from array. - * Returns +nil+ if no changes were made, otherwise return - * </i>array</i>. + * Removes +nil+ elements from the array. + * Returns +nil+ if no changes were made, otherwise returns + * </i>ary</i>. * * [ "a", nil, "b", nil, "c" ].compact! #=> [ "a", "b", "c" ] * [ "a", "b", "c" ].compact! #=> nil @@ -3477,9 +3532,9 @@ /* * call-seq: - * array.compact -> an_array + * ary.compact -> new_ary * - * Returns a copy of _self_ with all +nil+ elements removed. + * Returns a copy of +self+ with all +nil+ elements removed. * * [ "a", nil, "b", nil, "c", nil ].compact * #=> [ "a", "b", "c" ] @@ -3495,9 +3550,9 @@ /* * call-seq: - * array.count -> int - * array.count(obj) -> int - * array.count { |item| block } -> int + * ary.count -> int + * 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 <i>obj</i>. If a block is @@ -3596,12 +3651,12 @@ /* * call-seq: - * array.flatten! -> array or nil - * array.flatten!(level) -> array or nil + * ary.flatten! -> ary or nil + * ary.flatten!(level) -> array or nil * - * Flattens _self_ in place. + * Flattens +self+ in place. * Returns <code>nil</code> if no modifications were made (i.e., - * <i>array</i> contains no subarrays.) If the optional <i>level</i> + * <i>ary</i> contains no subarrays.) If the optional <i>level</i> * argument determines the level of recursion to flatten. * * a = [ 1, 2, [3, [4, 5] ] ] @@ -3637,8 +3692,8 @@ /* * call-seq: - * array.flatten -> an_array - * array.flatten(level) -> an_array + * 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, @@ -3671,9 +3726,9 @@ /* * call-seq: - * array.shuffle! -> array + * ary.shuffle! -> ary * - * Shuffles elements in _self_ in place. + * Shuffles elements in +self+ in place. */ @@ -3697,7 +3752,7 @@ /* * call-seq: - * array.shuffle -> an_array + * ary.shuffle -> new_ary * * Returns a new array with elements of this array shuffled. * @@ -3716,8 +3771,8 @@ /* * call-seq: - * array.sample -> obj - * array.sample(n) -> an_array + * ary.sample -> obj + * ary.sample(n) -> 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 @@ -3805,14 +3860,17 @@ /* * call-seq: - * ary.cycle {|obj| block } - * ary.cycle(n) {|obj| block } + * ary.cycle(n=nil) {|obj| block } -> nil + * ary.cycle(n=nil) -> an_enumerator * * Calls <i>block</i> 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 + * 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. * + * 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. @@ -3895,10 +3953,10 @@ /* * call-seq: - * ary.permutation { |p| block } -> array - * ary.permutation -> enumerator - * ary.permutation(n) { |p| block } -> array - * ary.permutation(n) -> enumerator + * ary.permutation { |p| block } -> ary + * ary.permutation -> an_enumerator + * ary.permutation(n) { |p| block } -> ary + * ary.permutation(n) -> an_enumerator * * When invoked with a block, yield all permutations of length <i>n</i> * of the elements of <i>ary</i>, then return the array itself. @@ -3906,7 +3964,7 @@ * The implementation makes no guarantees about the order in which * the permutations are yielded. * - * When invoked without a block, return an enumerator object instead. + * If no block is given, an enumerator is returned instead. * * Examples: * @@ -3962,14 +4020,14 @@ /* * call-seq: * ary.combination(n) { |c| block } -> ary - * ary.combination(n) -> enumerator + * ary.combination(n) -> an_enumerator * * When invoked with a block, yields all combinations of length <i>n</i> * of elements from <i>ary</i> and then returns <i>ary</i> itself. * The implementation makes no guarantees about the order in which * the combinations are yielded. * - * When invoked without a block, returns an enumerator object instead. + * If no block is given, an enumerator is returned instead. * * Examples: * @@ -4073,15 +4131,15 @@ /* * call-seq: - * ary.repeated_permutation(n) { |p| block } -> array - * ary.repeated_permutation(n) -> enumerator + * ary.repeated_permutation(n) { |p| block } -> ary + * ary.repeated_permutation(n) -> an_enumerator * * When invoked with a block, yield all repeated permutations of length * <i>n</i> of the elements of <i>ary</i>, then return the array itself. * The implementation makes no guarantees about the order in which * the repeated permutations are yielded. * - * When invoked without a block, return an enumerator object instead. + * If no block is given, an enumerator is returned instead. * * Examples: * @@ -4153,7 +4211,7 @@ /* * call-seq: * ary.repeated_combination(n) { |c| block } -> ary - * ary.repeated_combination(n) -> enumerator + * ary.repeated_combination(n) -> an_enumerator * * When invoked with a block, yields all repeated combinations of * length <i>n</i> of elements from <i>ary</i> and then returns @@ -4161,7 +4219,7 @@ * The implementation makes no guarantees about the order in which * the repeated combinations are yielded. * - * When invoked without a block, returns an enumerator object instead. + * If no block is given, an enumerator is returned instead. * * Examples: * @@ -4214,14 +4272,14 @@ /* * call-seq: - * ary.product(other_ary, ...) -> array + * ary.product(other_ary, ...) -> new_ary * 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 ary and the argument arrays. + * of +self+ and the argument arrays. * If given a block, <i>product</i> will yield all combinations - * and return self instead. + * and return +self+ instead. * * * [1,2,3].product([4,5]) # => [[1,4],[1,5],[2,4],[2,5],[3,4],[3,5]] @@ -4318,7 +4376,7 @@ /* * call-seq: - * ary.take(n) => array + * ary.take(n) -> new_ary * * Returns first n elements from <i>ary</i>. * @@ -4339,11 +4397,14 @@ /* * call-seq: - * ary.take_while {|arr| block } => array + * ary.take_while {|arr| block } -> new_ary + * ary.take_while -> an_enumerator * - * Passes elements to the block until the block returns nil or false, + * 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. + * * a = [1, 2, 3, 4, 5, 0] * a.take_while {|i| i < 3 } # => [1, 2] * @@ -4363,7 +4424,7 @@ /* * call-seq: - * ary.drop(n) => array + * ary.drop(n) -> new_ary * * Drops first n elements from <i>ary</i>, and returns rest elements * in an array. @@ -4389,12 +4450,15 @@ /* * call-seq: - * ary.drop_while {|arr| block } => array + * ary.drop_while {|arr| block } -> new_ary + * ary.drop_while -> an_enumerator * * Drops elements up to, but not including, the first element for - * which the block returns nil or false and returns an array + * 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. + * * a = [1, 2, 3, 4, 5, 0] * a.drop_while {|i| i < 3 } # => [3, 4, 5, 0] * Index: ruby_1_9_2/enum.c =================================================================== --- ruby_1_9_2/enum.c (revision 27777) +++ ruby_1_9_2/enum.c (revision 27778) @@ -181,12 +181,16 @@ * call-seq: * enum.detect(ifnone = nil) {| obj | block } => obj or nil * enum.find(ifnone = nil) {| obj | block } => obj or nil + * enum.detect(ifnone = nil) => an_enumerator + * enum.find(ifnone = nil) => an_enumerator * * Passes each entry in <i>enum</i> to <em>block</em>. Returns the - * first for which <em>block</em> is not <code>false</code>. If no + * first for which <em>block</em> is not false. If no * object matches, calls <i>ifnone</i> and returns its result when it - * is specified, or returns <code>nil</code> + * is specified, or returns <code>nil</code> otherwise. * + * If no block is given, an enumerator is returned instead. + * * (1..10).detect {|i| i % 5 == 0 and i % 7 == 0 } #=> nil * (1..100).detect {|i| i % 5 == 0 and i % 7 == 0 } #=> 35 * @@ -242,12 +246,15 @@ * call-seq: * enum.find_index(value) => int or nil * enum.find_index {| obj | block } => int or nil + * enum.find_index => an_enumerator * * Compares each entry in <i>enum</i> with <em>value</em> or passes * to <em>block</em>. Returns the index for the first for which the * evaluated value is non-false. If no object matches, returns * <code>nil</code> * + * If neither block nor argument is given, an enumerator is returned instead. + * * (1..10).find_index {|i| i % 5 == 0 and i % 7 == 0 } #=> nil * (1..100).find_index {|i| i % 5 == 0 and i % 7 == 0 } #=> 34 * (1..100).find_index(50) #=> 49 @@ -293,11 +300,16 @@ * call-seq: * enum.find_all {| obj | block } => array * enum.select {| obj | block } => array + * enum.find_all => an_enumerator + * enum.select => an_enumerator * * Returns an array containing all elements of <i>enum</i> for which * <em>block</em> is not <code>false</code> (see also * <code>Enumerable#reject</code>). * + * If no block is given, an enumerator is returned instead. + * + * * (1..10).find_all {|i| i % 3 == 0 } #=> [3, 6, 9] * */ @@ -329,10 +341,13 @@ /* * call-seq: * enum.reject {| obj | block } => array + * enum.reject => an_enumerator * * Returns an array for all elements of <i>enum</i> for which * <em>block</em> is false (see also <code>Enumerable#find_all</code>). * + * If no block is given, an enumerator is returned instead. + * * (1..10).reject {|i| i % 3 == 0 } #=> [1, 2, 4, 5, 7, 8, 10] * */ @@ -371,10 +386,14 @@ * call-seq: * enum.collect {| obj | block } => array * enum.map {| obj | block } => array + * enum.collect => an_enumerator + * enum.map => an_enumerator * * Returns a new array with the results of running <em>block</em> once * for every element in <i>enum</i>. * + * If no block is given, an enumerator is returned instead. + * * (1..4).collect {|i| i*i } #=> [1, 4, 9, 16] * (1..4).collect { "cat" } #=> ["cat", "cat", "cat", "cat"] * @@ -414,10 +433,14 @@ * call-seq: * enum.flat_map {| obj | block } => array * enum.collect_concat {| obj | block } => array + * enum.flat_map => an_enumerator + * enum.collect_concat => an_enumerator * * Returns a new array with the concatenated results of running * <em>block</em> once for every element in <i>enum</i>. * + * If no block is given, an enumerator is returned instead. + * * [[1,2],[3,4]].flat_map {|i| i } #=> [1, 2, 3, 4] * */ @@ -581,11 +604,14 @@ /* * call-seq: * enum.partition {| obj | block } => [ true_array, false_array ] + * enum.partition => an_enumerator * * Returns two arrays, the first containing the elements of * <i>enum</i> for which the block evaluates to true, the second * containing the rest. * + * If no block is given, an enumerator is returned instead. + * * (1..6).partition {|i| (i&1).zero?} #=> [[2, 4, 6], [1, 3, 5]] * */ @@ -627,11 +653,14 @@ /* * call-seq: * enum.group_by {| obj | block } => a_hash + * enum.group_by => an_enumerator * * Returns a hash, which keys are evaluated result from the * block, and values are arrays of elements in <i>enum</i> * corresponding to the key. * + * If no block is given, an enumerator is returned instead. + * * (1..6).group_by {|i| i%3} #=> {0=>[3, 6], 1=>[1, 4], 2=>[2, 5]} * */ @@ -764,10 +793,13 @@ /* * call-seq: * enum.sort_by {| obj | block } => array + * enum.sort_by => an_enumerator * * Sorts <i>enum</i> using a set of keys generated by mapping the * values in <i>enum</i> through the given block. * + * If no block is given, an enumerator is returned instead. + * * %w{ apple pear fig }.sort_by {|word| word.length} * #=> ["fig", "pear", "apple"] * @@ -777,11 +809,10 @@ * the keysets are simple * * require 'benchmark' - * include Benchmark * * a = (1..100000).map {rand(100000)} * - * bm(10) do |b| + * Benchmark.bm(10) do |b| * b.report("Sort") { a.sort } * b.report("Sort by") { a.sort_by {|a| a} } * end @@ -1335,10 +1366,13 @@ /* * call-seq: * enum.min_by {|obj| block } => obj + * enum.min_by => an_enumerator * * Returns the object in <i>enum</i> that gives the minimum * value from the given block. * + * If no block is given, an enumerator is returned instead. + * * a = %w(albatross dog horse) * a.min_by {|x| x.length } #=> "dog" */ @@ -1378,10 +1412,13 @@ /* * call-seq: * enum.max_by {|obj| block } => obj + * enum.max_by => an_enumerator * * Returns the object in <i>enum</i> that gives the maximum * value from the given block. * + * If no block is given, an enumerator is returned instead. + * * a = %w(albatross dog horse) * a.max_by {|x| x.length } #=> "albatross" */ @@ -1472,11 +1509,14 @@ /* * call-seq: * enum.minmax_by {|obj| block } => [min, max] + * enum.minmax_by => an_enumerator * * Returns two elements array array containing the objects in * <i>enum</i> that gives the minimum and maximum values respectively * from the given block. * + * If no block is given, an enumerator is returned instead. + * * a = %w(albatross dog horse) * a.minmax_by {|x| x.length } #=> ["dog", "albatross"] */ @@ -1544,12 +1584,15 @@ /* * call-seq: - * enum.each_with_index {|obj, i| block } -> enum + * enum.each_with_index(*args) {|obj, i| block } -> enum + * enum.each_with_index(*args) -> an_enumerator * * Calls <em>block</em> with two arguments, the item and its index, * for each item in <i>enum</i>. Given arguments are passed through * to #each(). * + * If no block is given, an enumerator is returned instead. + * * hash = Hash.new * %w(cat dog wombat).each_with_index {|item, index| * hash[item] = index @@ -1573,9 +1616,13 @@ /* * call-seq: - * enum.reverse_each {|item| block } + * enum.reverse_each(*args) {|item| block } -> enum + * enum.reverse_each(*args) -> an_enumerator * - * Traverses <i>enum</i> in reverse order. + * Builds a temporary array and traverses that array in reverse order. + * + * If no block is given, an enumerator is returned instead. + * */ static VALUE @@ -1607,11 +1654,14 @@ /* * call-seq: * enum.each_entry {|obj| block} => enum + * enum.each_entry => an_enumerator * - * Calls <i>block</i> once for each element in <i>self</i>, passing that + * Calls <i>block</i> once for each element in +self+, passing that * element as a parameter, converting multiple values from yield to an * array. * + * If no block is given, an enumerator is returned instead. + * * class Foo * include Enumerable * def each @@ -1654,8 +1704,8 @@ /* * call-seq: - * e.each_slice(n) {...} - * e.each_slice(n) + * enum.each_slice(n) {...} -> nil + * enum.each_slice(n) -> an_enumerator * * Iterates the given block for each slice of <n> elements. If no * block is given, returns an enumerator. @@ -1708,8 +1758,8 @@ /* * call-seq: - * each_cons(n) {...} - * each_cons(n) + * enum.each_cons(n) {...} -> nil + * enum.each_cons(n) -> an_enumerator * * Iterates the given block for each array of consecutive <n> * elements. If no block is given, returns an enumerator. @@ -1752,8 +1802,8 @@ /* * call-seq: - * each_with_object(obj) {|(*args), memo_obj| ... } - * each_with_object(obj) + * enum.each_with_object(obj) {|(*args), memo_obj| ... } -> obj + * enum.each_with_object(obj) -> an_enumerator * * Iterates the given block for each element with an arbitrary * object given, and returns the initially given object. @@ -1854,7 +1904,7 @@ /* * call-seq: - * enum.zip(arg, ...) => enumerator + * enum.zip(arg, ...) => an_enumerator * enum.zip(arg, ...) {|arr| block } => nil * * Takes one element from <i>enum</i> and merges corresponding @@ -1958,10 +2008,13 @@ /* * call-seq: * enum.take_while {|arr| block } => array + * enum.take_while => an_enumerator * - * Passes elements to the block until the block returns nil or false, + * 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. + * * a = [1, 2, 3, 4, 5, 0] * a.take_while {|i| i < 3 } # => [1, 2] * @@ -2036,11 +2089,14 @@ /* * call-seq: * enum.drop_while {|arr| block } => array + * enum.drop_while => an_enumerator * * Drops elements up to, but not including, the first element for - * which the block returns nil or false and returns an array + * 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. + * * a = [1, 2, 3, 4, 5, 0] * a.drop_while {|i| i < 3 } # => [3, 4, 5, 0] * @@ -2070,17 +2126,19 @@ /* * call-seq: - * enum.cycle {|obj| block } - * enum.cycle(n) {|obj| block } + * enum.cycle(n=nil) {|obj| block } -> nil + * enum.cycle(n=nil) -> an_enumerator * * Calls <i>block</i> for each element of <i>enum</i> repeatedly _n_ - * times or forever if none or nil is given. If a non-positive + * times or forever if none or +nil+ is given. If a non-positive * number is given or the collection is empty, does nothing. Returns - * nil if the loop has finished without getting interrupted. + * +nil+ if the loop has finished without getting interrupted. * * Enumerable#cycle saves elements in an internal array so changes * to <i>enum</i> after the first pass have no effect. * + * 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. @@ -2114,7 +2172,7 @@ rb_yield(RARRAY_PTR(ary)[i]); } } - return Qnil; /* not reached */ + return Qnil; } struct chunk_arg { @@ -2199,8 +2257,8 @@ /* * call-seq: - * enum.chunk {|elt| ... } => enumerator - * enum.chunk(initial_state) {|elt, state| ... } => enumerator + * enum.chunk {|elt| ... } => an_enumerator + * enum.chunk(initial_state) {|elt, state| ... } => an_enumerator * * Creates an enumerator for each chunked elements. * The consecutive elements which have same block value are chunked. @@ -2374,9 +2432,9 @@ /* * call-seq: - * enum.slice_before(pattern) => enumerator - * enum.slice_before {|elt| bool } => enumerator - * enum.slice_before(initial_state) {|elt, state| bool } => enumerator + * enum.slice_before(pattern) => an_enumerator + * enum.slice_before {|elt| bool } => an_enumerator + * enum.slice_before(initial_state) {|elt, state| bool } => an_enumerator * * Creates an enumerator for each chunked elements. * The beginnings of chunks are defined by _pattern_ and the block. Index: ruby_1_9_2/string.c =================================================================== --- ruby_1_9_2/string.c (revision 27777) +++ ruby_1_9_2/string.c (revision 27778) @@ -2859,13 +2859,16 @@ /* * call-seq: * str.upto(other_str, exclusive=false) {|s| block } => str + * str.upto(other_str, exclusive=false) => an_enumerator * * Iterates through successive values, starting at <i>str</i> and * ending at <i>other_str</i> inclusive, passing each value in turn to * the block. The <code>String#succ</code> method is used to generate - * each value. If optional second argument exclusive is omitted or is <code>false</code>, + * each value. If optional second argument exclusive is omitted or is false, * the last value will be included; otherwise it will be excluded. * + * If no block is given, an enumerator is returned instead. + * * "a8".upto("b6") {|s| print s, ' ' } * for s in "a8".."b6" * print s, ' ' @@ -3548,6 +3551,7 @@ * call-seq: * str.sub(pattern, replacement) => new_str * str.sub(pattern) {|match| block } => new_str + * str.sub(pattern) => an_enumerator * * Returns a copy of <i>str</i> with the <em>first</em> occurrence of * <i>pattern</i> replaced with either <i>replacement</i> or the value of the @@ -3566,6 +3570,8 @@ * <code>$&</code>, and <code>$'</code> will be set appropriately. The value * returned by the block will be substituted for the match on each call. * + * If no block and no <i>replacement</i> is given, an enumerator is returned instead. + * * The result inherits any tainting in the original string or any supplied * replacement string. * @@ -5659,10 +5665,10 @@ /* * call-seq: * str.each_line(separator=$/) {|substr| block } => str - * str.each_line(separator=$/) => anEnumerator + * str.each_line(separator=$/) => an_enumerator * * str.lines(separator=$/) {|substr| block } => str - * str.lines(separator=$/) => anEnumerator + * str.lines(separator=$/) => an_enumerator * * Splits <i>str</i> using the supplied parameter as the record separator * (<code>$/</code> by default), passing each substring in turn to the supplied @@ -5794,10 +5800,10 @@ /* * call-seq: * str.bytes {|fixnum| block } => str - * str.bytes => anEnumerator + * str.bytes => an_enumerator * * str.each_byte {|fixnum| block } => str - * str.each_byte => anEnumerator + * str.each_byte => an_enumerator * * Passes each byte in <i>str</i> to the given block, or returns * an enumerator if no block is given. @@ -5825,10 +5831,10 @@ /* * call-seq: * str.chars {|cstr| block } => str - * str.chars => anEnumerator + * str.chars => an_enumerator * * str.each_char {|cstr| block } => str - * str.each_char => anEnumerator + * str.each_char => an_enumerator * * Passes each character in <i>str</i> to the given block, or returns * an enumerator if no block is given. @@ -5873,10 +5879,10 @@ /* * call-seq: * str.codepoints {|integer| block } => str - * str.codepoints => anEnumerator + * str.codepoints => an_enumerator * * str.each_codepoint {|integer| block } => str - * str.each_codepoint => anEnumerator + * str.each_codepoint => an_enumerator * * Passes the <code>Integer</code> ordinal of each character in <i>str</i>, * also known as a <i>codepoint</i> when applied to Unicode strings to the Index: ruby_1_9_2/io.c =================================================================== --- ruby_1_9_2/io.c (revision 27777) +++ ruby_1_9_2/io.c (revision 27778) @@ -2703,17 +2703,17 @@ * ios.each(sep=$/) {|line| block } => ios * ios.each(limit) {|line| block } => ios * ios.each(sep,limit) {|line| block } => ios - * ios.each(...) => anEnumerator + * ios.each(...) => an_enumerator * * ios.each_line(sep=$/) {|line| block } => ios * ios.each_line(limit) {|line| block } => ios * ios.each_line(sep,limit) {|line| block } => ios - * ios.each_line(...) => anEnumerator + * ios.each_line(...) => an_enumerator * * ios.lines(sep=$/) {|line| block } => ios * ios.lines(limit) {|line| block } => ios * ios.lines(sep,limit) {|line| block } => ios - * ios.lines(...) => anEnumerator + * ios.lines(...) => an_enumerator * * Executes the block for every line in <em>ios</em>, where lines are * separated by <i>sep</i>. <em>ios</em> must be opened for @@ -2749,10 +2749,10 @@ /* * call-seq: * ios.bytes {|byte| block } => ios - * ios.bytes => anEnumerator + * ios.bytes => an_enumerator * * ios.each_byte {|byte| block } => ios - * ios.each_byte => anEnumerator + * ios.each_byte => an_enumerator * * Calls the given block once for each byte (0..255) in <em>ios</em>, * passing the byte as an argument. The stream must be opened for @@ -2898,10 +2898,10 @@ /* * call-seq: * ios.chars {|c| block } => ios - * ios.chars => anEnumerator + * ios.chars => an_enumerator * * ios.each_char {|c| block } => ios - * ios.each_char => anEnumerator + * ios.each_char => an_enumerator * * Calls the given block once for each character in <em>ios</em>, * passing the character as an argument. The stream must be opened for @@ -2933,23 +2933,19 @@ } - /* * call-seq: - * ios.codepoints => anEnumerator - * - * Returns an enumerator that gives each codepoint in <em>ios</em>. - * The stream must be opened for reading or an <code>IOError</code> - * will be raised. - */ - -/* - * call-seq: * ios.each_codepoint {|c| block } => ios + * ios.codepoints {|c| block } => ios + * ios.each_codepoint => an_enumerator + * ios.codepoints => an_enumerator * * Passes the <code>Integer</code> ordinal of each character in <i>ios</i>, * passing the codepoint as an argument. The stream must be opened for * reading or an <code>IOError</code> will be raised. + * + * If no block is given, an enumerator is returned instead. + * */ static VALUE @@ -7833,10 +7829,13 @@ * IO.foreach(name, sep=$/ [, open_args]) {|line| block } => nil * IO.foreach(name, limit [, open_args]) {|line| block } => nil * IO.foreach(name, sep, limit [, open_args]) {|line| block } => nil + * IO.foreach(...) => an_enumerator * * Executes the block for every line in the named I/O port, where lines * are separated by <em>sep</em>. * + * If no block is given, an enumerator is returned instead. + * * IO.foreach("testfile") {|x| print "GOT ", x } * * <em>produces:</em> @@ -9222,15 +9221,15 @@ * call-seq: * ARGF.each(sep=$/) {|line| block } => ARGF * ARGF.each(sep=$/,limit) {|line| block } => ARGF - * ARGF.each(...) => anEnumerator + * ARGF.each(...) => an_enumerator * * ARGF.each_line(sep=$/) {|line| block } => ARGF * ARGF.each_line(sep=$/,limit) {|line| block } => ARGF - * ARGF.each_line(...) => anEnumerator + * ARGF.each_line(...) => an_enumerator * * ARGF.lines(sep=$/) {|line| block } => ARGF * ARGF.lines(sep=$/,limit) {|line| block } => ARGF - * ARGF.lines(...) => anEnumerator + * ARGF.lines(...) => an_enumerator * * Returns an enumerator which iterates over each line (separated by _sep_, * which defaults to your platform's newline character) of each file in @@ -9268,10 +9267,10 @@ /* * call-seq: * ARGF.bytes {|byte| block } => ARGF - * ARGF.bytes => anEnumerator + * ARGF.bytes => an_enumerator * * ARGF.each_byte {|byte| block } => ARGF - * ARGF.each_byte => anEnumerator + * ARGF.each_byte => an_enumerator * * Iterates over each byte of each file in +ARGV+. * A byte is returned as a +Fixnum+ in the range 0..255. @@ -9303,10 +9302,10 @@ /* * call-seq: * ARGF.chars {|char| block } => ARGF - * ARGF.chars => anEnumerator + * ARGF.chars => an_enumerator * * ARGF.each_char {|char| block } => ARGF - * ARGF.each_char => anEnumerator + * ARGF.each_char => an_enumerator * * Iterates over each character of each file in +ARGF+. * @@ -9590,9 +9589,9 @@ /* * call-seq: - * ARGF.argv => Array + * ARGF.argv => ARGV * - * Returns the +ARGV+ Array, which contains the arguments passed to your + * Returns the +ARGV+ array, which contains the arguments passed to your * script, one per element. * * For example: Index: ruby_1_9_2/vm_eval.c =================================================================== --- ruby_1_9_2/vm_eval.c (revision 27777) +++ ruby_1_9_2/vm_eval.c (revision 27778) @@ -792,10 +792,13 @@ /* * call-seq: - * loop {|| block } + * loop { block } + * loop -> an_enumerator * * Repeatedly executes the block. * + * If no block is given, an enumerator is returned instead. + * * loop do * print "Input: " * line = gets Index: ruby_1_9_2/range.c =================================================================== --- ruby_1_9_2/range.c (revision 27777) +++ ruby_1_9_2/range.c (revision 27778) @@ -319,6 +319,7 @@ /* * call-seq: * rng.step(n=1) {| obj | block } => rng + * rng.step(n=1) => an_enumerator * * Iterates over <i>rng</i>, passing each <i>n</i>th element to the block. If * the range contains numbers, <i>n</i> is added for each iteration. Otherwise @@ -326,6 +327,8 @@ * elements. The following code uses class <code>Xs</code>, which is defined * in the class-level documentation. * + * If no block is given, an enumerator is returned instead. + * * range = Xs.new(1)..Xs.new(10) * range.step(2) {|x| puts x} * range.step(3) {|x| puts x} @@ -453,12 +456,15 @@ /* * call-seq: * rng.each {| i | block } => rng + * rng.each => an_enumerator * * Iterates over the elements <i>rng</i>, passing each in turn to the * block. You can only iterate if the start object of the range * supports the +succ+ method (which means that you can't iterate over * ranges of +Float+ objects). * + * If no block is given, an enumerator is returned instead. + * * (10..15).each do |n| * print n, ' ' * end Index: ruby_1_9_2/dir.c =================================================================== --- ruby_1_9_2/dir.c (revision 27777) +++ ruby_1_9_2/dir.c (revision 27778) @@ -592,10 +592,13 @@ /* * call-seq: * dir.each { |filename| block } => dir + * dir.each => an_enumerator * * Calls the block once for each entry in this directory, passing the * filename of each entry as a parameter to the block. * + * If no block is given, an enumerator is returned instead. + * * d = Dir.new("testdir") * d.each {|x| puts "Got #{x}" } * @@ -1820,10 +1823,13 @@ /* * call-seq: * Dir.foreach( dirname ) {| filename | block } => nil + * Dir.foreach( dirname ) => an_enumerator * * Calls the block once for each entry in the named directory, passing * the filename of each entry as a parameter to the block. * + * If no block is given, an enumerator is returned instead. + * * Dir.foreach("testdir") {|x| puts "Got #{x}" } * * <em>produces:</em> Index: ruby_1_9_2/struct.c =================================================================== --- ruby_1_9_2/struct.c (revision 27777) +++ ruby_1_9_2/struct.c (revision 27778) @@ -442,10 +442,13 @@ /* * call-seq: * struct.each {|obj| block } => struct + * struct.each => an_enumerator * * Calls <i>block</i> once for each instance variable, passing the * value as a parameter. * + * If no block is given, an enumerator is returned instead. + * * Customer = Struct.new(:name, :address, :zip) * joe = Customer.new("Joe Smith", "123 Maple, Anytown NC", 12345) * joe.each {|x| puts(x) } @@ -472,10 +475,13 @@ /* * call-seq: * struct.each_pair {|sym, obj| block } => struct + * struct.each_pair => an_enumerator * * Calls <i>block</i> once for each instance variable, passing the name * (as a symbol) and the value as parameters. * + * If no block is given, an enumerator is returned instead. + * * Customer = Struct.new(:name, :address, :zip) * joe = Customer.new("Joe Smith", "123 Maple, Anytown NC", 12345) * joe.each_pair {|name, value| puts("#{name} => #{value}") } @@ -734,7 +740,7 @@ * struct.values_at(selector,... ) => an_array * * Returns an array containing the elements in - * _self_ corresponding to the given selector(s). The selectors + * +self+ corresponding to the given selector(s). The selectors * may be either integer indices or ranges. * See also </code>.select<code>. * @@ -754,6 +760,7 @@ /* * call-seq: * struct.select {|i| block } => array + * struct.select => an_enumerator * * Invokes the block passing in successive elements from * <i>struct</i>, returning an array containing those elements Index: ruby_1_9_2/gc.c =================================================================== --- ruby_1_9_2/gc.c (revision 27777) +++ ruby_1_9_2/gc.c (revision 27778) @@ -2424,6 +2424,7 @@ /* * call-seq: * ObjectSpace.each_object([module]) {|obj| ... } => fixnum + * ObjectSpace.each_object([module]) => an_enumerator * * Calls the block once for each living, nonimmediate object in this * Ruby process. If <i>module</i> is specified, calls the block @@ -2435,6 +2436,8 @@ * returns both the numbers we defined and several constants defined in * the <code>Math</code> module. * + * If no block is given, an enumerator is returned instead. + * * a = 102.7 * b = 95 # Won't be returned * c = 12345678987654321 Index: ruby_1_9_2/hash.c =================================================================== --- ruby_1_9_2/hash.c (revision 27777) +++ ruby_1_9_2/hash.c (revision 27778) @@ -882,10 +882,13 @@ /* * call-seq: * hsh.delete_if {| key, value | block } -> hsh + * hsh.delete_if -> an_enumerator * * Deletes every key-value pair from <i>hsh</i> for which <i>block</i> * evaluates to <code>true</code>. * + * If no block is given, an enumerator is returned instead. + * * h = { "a" => 100, "b" => 200, "c" => 300 } * h.delete_if {|key, value| key >= "b" } #=> {"a"=>100} * @@ -903,6 +906,7 @@ /* * call-seq: * hsh.reject! {| key, value | block } -> hsh or nil + * hsh.reject! -> an_enumerator * * Equivalent to <code>Hash#delete_if</code>, but returns * <code>nil</code> if no changes were made. @@ -974,9 +978,12 @@ /* * call-seq: * hsh.select {|key, value| block} => a_hash + * hsh.select => an_enumerator * * Returns a new hash consisting of entries for which the block returns true. * + * If no block is given, an enumerator is returned instead. + * * h = { "a" => 100, "b" => 200, "c" => 300 } * h.select {|k,v| k > "a"} #=> {"b" => 200, "c" => 300} * h.select {|k,v| v < 200} #=> {"a" => 100} @@ -1006,6 +1013,7 @@ /* * call-seq: * hsh.select! {| key, value | block } -> hsh or nil + * hsh.select! -> an_enumerator * * Equivalent to <code>Hash#keep_if</code>, but returns * <code>nil</code> if no changes were made. @@ -1029,10 +1037,13 @@ /* * call-seq: * hsh.keep_if {| key, value | block } -> hsh + * hsh.keep_if -> an_enumerator * * Deletes every key-value pair from <i>hsh</i> for which <i>block</i> - * evaluates to <code>false</code>. + * evaluates to false. * + * If no block is given, an enumerator is returned instead. + * */ VALUE @@ -1203,10 +1214,13 @@ /* * call-seq: * hsh.each_value {| value | block } -> hsh + * hsh.each_value -> an_enumerator * * Calls <i>block</i> once for each key in <i>hsh</i>, passing the * value as a parameter. * + * If no block is given, an enumerator is returned instead. + * * h = { "a" => 100, "b" => 200 } * h.each_value {|value| puts value } * @@ -1235,10 +1249,13 @@ /* * call-seq: * hsh.each_key {| key | block } -> hsh + * hsh.each_key -> an_enumerator * * Calls <i>block</i> once for each key in <i>hsh</i>, passing the key * as a parameter. * + * If no block is given, an enumerator is returned instead. + * * h = { "a" => 100, "b" => 200 } * h.each_key {|key| puts key } * @@ -1265,12 +1282,16 @@ /* * call-seq: - * hsh.each {| key, value | block } -> hsh + * hsh.each {| key, value | block } -> hsh * hsh.each_pair {| key, value | block } -> hsh + * hsh.each -> an_enumerator + * hsh.each_pair -> an_enumerator * * Calls <i>block</i> once for each key in <i>hsh</i>, passing the key-value * pair as parameters. * + * If no block is given, an enumerator is returned instead. + * * h = { "a" => 100, "b" => 200 } * h.each {|key, value| puts "#{key} is #{value}" } * @@ -1377,7 +1398,7 @@ * call-seq: * hsh.to_hash => hsh * - * Returns <i>self</i>. + * Returns +self+. */ static VALUE Index: ruby_1_9_2/error.c =================================================================== --- ruby_1_9_2/error.c (revision 27777) +++ ruby_1_9_2/error.c (revision 27778) @@ -1058,7 +1058,7 @@ * system_call_error === other => true or false * * Return +true+ if the receiver is a generic +SystemCallError+, or - * if the error numbers _self_ and _other_ are the same. + * if the error numbers +self+ and _other_ are the same. */ static VALUE Index: ruby_1_9_2/numeric.c =================================================================== --- ruby_1_9_2/numeric.c (revision 27777) +++ ruby_1_9_2/numeric.c (revision 27778) @@ -494,7 +494,7 @@ * call-seq: * num.nonzero? -> self or nil * - * Returns <i>self</i> if <i>num</i> is not zero, <code>nil</code> + * Returns +self+ if <i>num</i> is not zero, <code>nil</code> * otherwise. This behavior is useful when chaining comparisons: * * a = %w( z Bb bB bb BB a aA Aa AA A ) @@ -1232,7 +1232,7 @@ * call-seq: * flt.to_f -> self * - * As <code>flt</code> is already a float, returns <i>self</i>. + * As <code>flt</code> is already a float, returns +self+. */ static VALUE @@ -1594,7 +1594,7 @@ /* * call-seq: * num.step(limit[, step]) {|i| block } -> self - * num.step(limit[, step]) -> enumerator + * num.step(limit[, step]) -> an_enumerator * * Invokes <em>block</em> with the sequence of numbers starting at * <i>num</i>, incremented by <i>step</i> (default 1) on each @@ -1610,6 +1610,8 @@ * the counter against <i>limit</i>, and increments itself using the * <code>+</code> operator. * + * If no block is given, an enumerator is returned instead. + * * 1.step(10, 2) { |i| print i, " " } * Math::E.step(Math::PI, 0.2) { |f| print f, " " } * @@ -3016,11 +3018,13 @@ /* * call-seq: * int.upto(limit) {|i| block } -> self - * int.upto(limit) -> enumerator + * int.upto(limit) -> an_enumerator * * Iterates <em>block</em>, passing in integer values from <i>int</i> * up to and including <i>limit</i>. * + * If no block is given, an enumerator is returned instead. + * * 5.upto(10) { |i| print i, " " } * * <em>produces:</em> @@ -3055,11 +3059,13 @@ /* * call-seq: * int.downto(limit) {|i| block } -> self - * int.downto(limit) -> enumerator + * int.downto(limit) -> an_enumerator * * Iterates <em>block</em>, passing decreasing values from <i>int</i> * down to and including <i>limit</i>. * + * If no block is given, an enumerator is returned instead. + * * 5.downto(1) { |n| print n, ".. " } * print " Liftoff!\n" * @@ -3095,11 +3101,13 @@ /* * call-seq: * int.times {|i| block } -> self - * int.times -> enumerator + * int.times -> an_enumerator * * Iterates block <i>int</i> times, passing in values from zero to * <i>int</i> - 1. * + * If no block is given, an enumerator is returned instead. + * * 5.times do |i| * print i, " " * end -- ML: ruby-changes@q... Info: http://www.atdot.net/~ko1/quickml/