From 4afa9ed0418555ba20158e55cf3bf9ec563fbecb Mon Sep 17 00:00:00 2001 From: marcandre Date: Thu, 13 May 2010 05:49:55 +0000 Subject: * 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. git-svn-id: svn+ssh://ci.ruby-lang.org/ruby/trunk@27777 b2dd03c8-39d4-4d8f-98ff-823fe69b080e --- array.c | 466 +++++++++++++++++++++++++++++++++++--------------------------- dir.c | 6 + enum.c | 112 +++++++++++---- error.c | 2 +- gc.c | 3 + hash.c | 27 +++- io.c | 51 ++++--- numeric.c | 20 ++- range.c | 6 + string.c | 24 ++-- struct.c | 9 +- vm_eval.c | 5 +- 12 files changed, 456 insertions(+), 275 deletions(-) diff --git a/array.c b/array.c index 068eb6c29a..0e3c250ca1 100644 --- a/array.c +++ b/array.c @@ -278,7 +278,7 @@ rb_ary_freeze(VALUE ary) /* * call-seq: - * array.frozen? -> true or false + * ary.frozen? -> true or false * * Return true if this array is frozen (or temporarily frozen * while being sorted). @@ -474,9 +474,9 @@ rb_check_array_type(VALUE ary) * call-seq: * Array.try_convert(obj) -> array or nil * - * Try to convert obj into an array, using to_ary method. - * Returns converted array or nil if obj cannot be converted - * for any reason. This method is to check if an argument is an + * Try to convert obj into an array, using +to_ary+ method. + * Returns converted array or +nil+ if obj 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 @@ static VALUE rb_ary_push_1(VALUE ary, VALUE item); /* * 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 @@ rb_ary_push_1(VALUE ary, VALUE item) /* * 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 @@ rb_ary_pop(VALUE ary) /* * 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 self and returns it, or + * Removes the last element from +self+ and returns it, or * nil if the array is empty. * * If a number _n_ is given, returns an array of the last n elements @@ -837,10 +837,10 @@ rb_ary_shift(VALUE ary) /* * 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 self and removes it (shifting all + * Returns the first element of +self+ and removes it (shifting all * other elements down by one). Returns nil if the array * is empty. * @@ -885,10 +885,10 @@ rb_ary_shift_m(int argc, VALUE *argv, VALUE ary) /* * call-seq: - * array.unshift(obj, ...) -> array + * ary.unshift(obj, ...) -> ary * - * Prepends objects to the front of array. - * 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 @@ rb_ary_subseq(VALUE ary, long beg, long len) /* * 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 @@ rb_ary_aref(int argc, VALUE *argv, VALUE ary) /* * 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 Array#[]. * * a = [ "a", "b", "c", "d", "e" ] @@ -1044,8 +1044,8 @@ rb_ary_at(VALUE ary, VALUE pos) /* * 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 nil, and the @@ -1070,10 +1070,10 @@ rb_ary_first(int argc, VALUE *argv, VALUE ary) /* * 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 self. If the array is empty, + * Returns the last element(s) of +self+. If the array is empty, * the first form returns nil. * * a = [ "w", "x", "y", "z" ] @@ -1095,9 +1095,9 @@ rb_ary_last(int argc, VALUE *argv, VALUE ary) /* * 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 index. If the index * lies outside the array, the first form throws an @@ -1143,13 +1143,17 @@ rb_ary_fetch(int argc, VALUE *argv, VALUE ary) /* * 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 self such that is + * Returns the index of the first object in +self+ such that is * == to obj. If a block is given instead of an * argument, returns first object for which block is true. * Returns nil if no match is found. + * See also Array#rindex. + * + * If neither block nor argument is given, an enumerator is returned instead. * * a = [ "a", "b", "c" ] * a.index("b") #=> 1 @@ -1186,12 +1190,18 @@ rb_ary_index(int argc, VALUE *argv, VALUE ary) /* * 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 array + * Returns the index of the last object in +self+ * == to obj. If a block is given instead of an * argument, returns first object for which block is - * true. Returns nil if no match is found. + * true, starting from the last object. + * Returns nil if no match is found. + * See also Array#index. + * + * If neither block nor argument is given, an enumerator is returned instead. * * a = [ "a", "b", "b", "b", "c" ] * a.rindex("b") #=> 3 @@ -1298,9 +1308,9 @@ rb_ary_splice(VALUE ary, long beg, long len, VALUE rpl) /* * 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 @@ fixnum: /* * 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 @@ rb_ary_insert(int argc, VALUE *argv, VALUE ary) /* * call-seq: - * array.each {|item| block } -> array + * ary.each {|item| block } -> ary + * ary.each -> an_enumerator * - * Calls block once for each element in self, passing that + * Calls block 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 @@ rb_ary_each(VALUE ary) /* * call-seq: - * array.each_index {|index| block } -> array + * ary.each_index {|index| block } -> ary + * ary.each_index -> an_enumerator * * 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. + * + * * a = [ "a", "b", "c" ] * a.each_index {|x| print x, " -- " } * @@ -1445,9 +1462,10 @@ rb_ary_each_index(VALUE ary) /* * call-seq: - * array.reverse_each {|item| block } + * ary.reverse_each {|item| block } -> ary + * ary.reverse_each -> an_enumerator * - * Same as Array#each, but traverses self in reverse + * Same as Array#each, but traverses +self+ in reverse * order. * * a = [ "a", "b", "c" ] @@ -1476,9 +1494,9 @@ rb_ary_reverse_each(VALUE ary) /* * call-seq: - * array.length -> int + * ary.length -> int * - * Returns the number of elements in self. May be zero. + * Returns the number of elements in +self+. May be zero. * * [ 1, 2, 3, 4, 5 ].length #=> 5 */ @@ -1492,9 +1510,9 @@ rb_ary_length(VALUE ary) /* * call-seq: - * array.empty? -> true or false + * ary.empty? -> true or false * - * Returns true if self array contains no elements. + * Returns true if +self+ contains no elements. * * [].empty? #=> true */ @@ -1659,7 +1677,7 @@ rb_ary_join(VALUE ary, VALUE sep) /* * 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 sep. @@ -1704,10 +1722,10 @@ inspect_ary(VALUE ary, VALUE dummy, int recur) /* * call-seq: - * array.to_s -> string - * array.inspect -> string + * ary.to_s -> string + * ary.inspect -> string * - * Create a printable version of array. + * Creates a string representation of +self+. */ static VALUE @@ -1725,9 +1743,9 @@ rb_ary_to_s(VALUE ary) /* * 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 @@ rb_ary_to_a(VALUE ary) /* * call-seq: - * array.to_ary -> array + * ary.to_ary -> ary * - * Returns _self_. + * Returns +self+. */ static VALUE @@ -1782,9 +1800,9 @@ rb_ary_reverse(VALUE ary) /* * 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 @@ rb_ary_reverse_bang(VALUE ary) /* * call-seq: - * array.reverse -> an_array + * ary.reverse -> new_ary * - * Returns a new array containing self'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 @@ rb_ary_rotate(VALUE ary, long cnt) /* * 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 @@ rb_ary_rotate_bang(int argc, VALUE *argv, VALUE ary) /* * 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 @@ sort_2(const void *ap, const void *bp, void *dummy) /* * 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 <=> operator or using * an optional code block. The block implements a comparison between * a and b, returning -1, 0, or +1. See also @@ -2064,10 +2082,10 @@ rb_ary_sort_bang(VALUE ary) /* * 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 self. Comparisons for + * Returns a new array created by sorting +self+. Comparisons for * the sort will be done using the <=> operator or using * an optional code block. The block implements a comparison between * a and b, returning -1, 0, or +1. See also @@ -2095,10 +2113,14 @@ sort_by_i(VALUE i) /* * call-seq: - * array.sort_by! {| obj | block } -> array + * ary.sort_by! {| obj | block } -> ary + * ary.sort_by! -> an_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. * - * Sorts array in place using a set of keys generated by mapping the - * values in array through the given block. */ static VALUE @@ -2116,13 +2138,17 @@ rb_ary_sort_by_bang(VALUE ary) /* * 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 block once for each element of self. Creates a + * 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. + * * a = [ "a", "b", "c", "d" ] * a.collect {|x| x + "!" } #=> ["a!", "b!", "c!", "d!"] * a #=> ["a", "b", "c", "d"] @@ -2145,13 +2171,17 @@ rb_ary_collect(VALUE ary) /* * 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 Enumerable#collect. * + * 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 @@ rb_get_values_at(VALUE obj, long olen, int argc, VALUE *argv, VALUE (*func) (VAL /* * 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 Array#select. * @@ -2223,12 +2253,15 @@ rb_ary_values_at(int argc, VALUE *argv, VALUE ary) /* * 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 array, + * 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). * + * 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 @@ rb_ary_select(VALUE ary) /* * 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 - * array, deleting elements for which the block returns a - * false value. but returns nil if no changes were - * made. Also see Array#keep_if + * +self+, deleting elements for which the block returns a + * false value. It returns +self+ if changes were made, + * otherwise it returns nil. + * See also Array#keep_if + * + * If no block is given, an enumerator is returned instead. + * */ static VALUE @@ -2283,10 +2321,14 @@ rb_ary_select_bang(VALUE ary) /* * call-seq: - * array.keep_if {|item| block } -> an_array + * ary.keep_if {|item| block } -> ary + * ary.keep_if -> an_enumerator + * + * Deletes every element of +self+ for which block evaluates + * to false. + * See also Array#select! * - * Deletes every element of self for which block evaluates - * to false. + * 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 @@ rb_ary_keep_if(VALUE ary) /* * 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 self that are equal to obj. + * Deletes items from +self+ that are equal to obj. * If any items are found, returns obj. If * the item is not found, returns nil. If the optional * code block is given, returns the result of block if the item @@ -2379,7 +2421,7 @@ rb_ary_delete_at(VALUE ary, long pos) /* * 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 nil if the index is out of range. See also @@ -2399,12 +2441,12 @@ rb_ary_delete_at_m(VALUE ary, VALUE pos) /* * 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 * nil if the index is out of range. * * a = [ "a", "b", "c" ] @@ -2469,12 +2511,16 @@ rb_ary_slice_bang(int argc, VALUE *argv, VALUE ary) /* * call-seq: - * array.reject! {|item| block } -> array or nil + * ary.reject! {|item| block } -> ary or nil + * ary.reject! -> an_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. Also see - * Enumerable#reject. + * +self+ for which the block evaluates to true, but returns + * nil if no changes were made. + * See also Enumerable#reject and Array#delete_if. + * + * If no block is given, an enumerator is returned instead. + * */ static VALUE @@ -2501,10 +2547,15 @@ rb_ary_reject_bang(VALUE ary) /* * 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 Array#delete_if + * + * If no block is given, an enumerator is returned instead. + * */ static VALUE @@ -2518,10 +2569,14 @@ rb_ary_reject(VALUE ary) /* * call-seq: - * array.delete_if {|item| block } -> array + * ary.delete_if {|item| block } -> ary + * ary.delete_if -> an_enumerator * - * Deletes every element of self for which block evaluates - * to true. + * Deletes every element of +self+ for which block evaluates + * to true. + * See also Array#reject! + * + * 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 @@ take_items(VALUE obj, long n) /* * 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 - * self with corresponding elements from each argument. This + * +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 given, it is + * nil 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 @@ rb_ary_zip(int argc, VALUE *argv, VALUE ary) /* * call-seq: - * array.transpose -> an_array + * ary.transpose -> new_ary * - * Assumes that self 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 @@ rb_ary_transpose(VALUE ary) /* * call-seq: - * array.replace(other_array) -> array + * ary.replace(other_ary) -> ary * - * Replaces the contents of self with the contents of - * other_array, 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"] @@ -2706,9 +2761,9 @@ rb_ary_replace(VALUE copy, VALUE orig) /* * 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 @@ rb_ary_clear(VALUE ary) /* * 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 - * - * The first three forms set the selected elements of self (which + * 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 +self+ (which * 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 @@ -2823,7 +2878,7 @@ rb_ary_fill(int argc, VALUE *argv, VALUE ary) /* * 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 @@ rb_ary_plus(VALUE x, VALUE y) /* * call-seq: - * array.concat(other_array) -> array + * ary.concat(other_ary) -> ary * - * Appends the elements in other_array to _self_. + * Appends the elements of other_ary to +self+. * * [ "a", "b" ].concat( ["c", "d"] ) #=> [ "a", "b", "c", "d" ] */ @@ -2870,12 +2925,12 @@ rb_ary_concat(VALUE x, VALUE y) /* * 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 @@ rb_ary_times(VALUE ary, VALUE times) /* * 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 @@ rb_ary_assoc(VALUE ary, VALUE key) /* * 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 @@ recursive_equal(VALUE ary1, VALUE ary2, int recur) /* * 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 @@ recursive_eql(VALUE ary1, VALUE ary2, int recur) /* * call-seq: - * array.eql?(other) -> true or false + * ary.eql?(other) -> true or false * - * Returns true if _array_ and _other_ are the same object, + * Returns true if +self+ and _other_ are the same object, * or are both arrays with the same content. */ @@ -3081,7 +3136,7 @@ recursive_hash(VALUE ary, VALUE dummy, int recur) /* * 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 eql?). @@ -3095,10 +3150,10 @@ rb_ary_hash(VALUE ary) /* * call-seq: - * array.include?(obj) -> true or false + * ary.include?(obj) -> true or false * * Returns true if the given object is present in - * self (that is, if any object == anObject), + * +self+ (that is, if any object == anObject), * false otherwise. * * a = [ "a", "b", "c" ] @@ -3141,11 +3196,11 @@ recursive_cmp(VALUE ary1, VALUE ary2, int recur) /* * 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 + * other_ary. 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 @@ ary_recycle_hash(VALUE hash) /* * 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 + * 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 ] @@ -3266,7 +3321,7 @@ rb_ary_diff(VALUE ary1, VALUE ary2) /* * 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 @@ rb_ary_and(VALUE ary1, VALUE ary2) /* * 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. + * other_ary, removing duplicates. * * [ "a", "b", "c" ] | [ "c", "d", "a" ] * #=> [ "a", "b", "c", "d" ] @@ -3347,9 +3402,9 @@ push_value(st_data_t key, st_data_t val, st_data_t ary) /* * call-seq: - * array.uniq! -> array or nil + * ary.uniq! -> ary or nil * - * Removes duplicate elements from _self_. + * Removes duplicate elements from +self+. * Returns nil if no changes are made (that is, no * duplicates are found). * @@ -3399,9 +3454,9 @@ rb_ary_uniq_bang(VALUE ary) /* * call-seq: - * array.uniq -> an_array + * ary.uniq -> new_ary * - * Returns a new array by removing duplicate values in self. + * 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 @@ rb_ary_uniq(VALUE ary) /* * 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 - * array. + * Removes +nil+ elements from the array. + * Returns +nil+ if no changes were made, otherwise returns + * ary. * * [ "a", nil, "b", nil, "c" ].compact! #=> [ "a", "b", "c" ] * [ "a", "b", "c" ].compact! #=> nil @@ -3477,9 +3532,9 @@ rb_ary_compact_bang(VALUE ary) /* * 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 @@ rb_ary_compact(VALUE ary) /* * 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 obj. If a block is @@ -3596,12 +3651,12 @@ flatten(VALUE ary, int level, int *modified) /* * 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 nil if no modifications were made (i.e., - * array contains no subarrays.) If the optional level + * ary contains no subarrays.) If the optional level * argument determines the level of recursion to flatten. * * a = [ 1, 2, [3, [4, 5] ] ] @@ -3637,8 +3692,8 @@ rb_ary_flatten_bang(int argc, VALUE *argv, VALUE ary) /* * 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 @@ rb_ary_flatten(int argc, VALUE *argv, VALUE ary) /* * call-seq: - * array.shuffle! -> array + * ary.shuffle! -> ary * - * Shuffles elements in _self_ in place. + * Shuffles elements in +self+ in place. */ @@ -3697,7 +3752,7 @@ rb_ary_shuffle_bang(VALUE ary) /* * call-seq: - * array.shuffle -> an_array + * ary.shuffle -> new_ary * * Returns a new array with elements of this array shuffled. * @@ -3716,8 +3771,8 @@ rb_ary_shuffle(VALUE ary) /* * 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 @@ rb_ary_sample(int argc, VALUE *argv, VALUE ary) /* * 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 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 + * 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 @@ permute0(long n, long r, long *p, long index, char *used, VALUE values) /* * 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 n * of the elements of ary, then return the array itself. @@ -3906,7 +3964,7 @@ permute0(long n, long r, long *p, long index, char *used, VALUE values) * 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 @@ rb_ary_permutation(int argc, VALUE *argv, VALUE ary) /* * 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 n * of elements from ary and then returns ary 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 @@ rpermute0(long n, long r, long *p, long index, VALUE values) /* * 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 * n of the elements of ary, 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 @@ rcombinate0(long n, long r, long *p, long index, long rest, VALUE values) /* * 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 n of elements from ary and then returns @@ -4161,7 +4219,7 @@ rcombinate0(long n, long r, long *p, long index, long rest, VALUE values) * 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 @@ rb_ary_repeated_combination(VALUE ary, VALUE num) /* * 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, product 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 @@ done: /* * call-seq: - * ary.take(n) => array + * ary.take(n) -> new_ary * * Returns first n elements from ary. * @@ -4339,11 +4397,14 @@ rb_ary_take(VALUE obj, VALUE n) /* * 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 @@ rb_ary_take_while(VALUE ary) /* * call-seq: - * ary.drop(n) => array + * ary.drop(n) -> new_ary * * Drops first n elements from ary, and returns rest elements * in an array. @@ -4389,12 +4450,15 @@ rb_ary_drop(VALUE ary, VALUE n) /* * 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] * diff --git a/dir.c b/dir.c index c709b9446f..adefbdac55 100644 --- a/dir.c +++ b/dir.c @@ -592,10 +592,13 @@ dir_read(VALUE dir) /* * 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 @@ dir_open_dir(int argc, VALUE *argv) /* * 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}" } * * produces: diff --git a/enum.c b/enum.c index b69d8c9b6f..026fe937e3 100644 --- a/enum.c +++ b/enum.c @@ -181,11 +181,15 @@ find_i(VALUE i, VALUE *memo, int argc, VALUE *argv) * 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 enum to block. Returns the - * first for which block is not false. If no + * first for which block is not false. If no * object matches, calls ifnone and returns its result when it - * is specified, or returns nil + * is specified, or returns nil 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 @@ find_index_iter_i(VALUE i, VALUE memop, int argc, VALUE *argv) * 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 enum with value or passes * to block. Returns the index for the first for which the * evaluated value is non-false. If no object matches, returns * nil * + * 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 @@ find_all_i(VALUE i, VALUE ary, int argc, VALUE *argv) * 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 enum for which * block is not false (see also * Enumerable#reject). * + * 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 @@ reject_i(VALUE i, VALUE ary, int argc, VALUE *argv) /* * call-seq: * enum.reject {| obj | block } => array + * enum.reject => an_enumerator * * Returns an array for all elements of enum for which * block is false (see also Enumerable#find_all). * + * 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 @@ collect_all(VALUE i, VALUE ary, int argc, VALUE *argv) * 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 block once * for every element in enum. * + * 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 @@ flat_map_i(VALUE i, VALUE ary, int argc, VALUE *argv) * 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 * block once for every element in enum. * + * 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 @@ partition_i(VALUE i, VALUE *ary, int argc, VALUE *argv) /* * call-seq: * enum.partition {| obj | block } => [ true_array, false_array ] + * enum.partition => an_enumerator * * Returns two arrays, the first containing the elements of * enum 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 @@ group_by_i(VALUE i, VALUE hash, int argc, VALUE *argv) /* * 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 enum * 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 @@ sort_by_cmp(const void *ap, const void *bp, void *data) /* * call-seq: * enum.sort_by {| obj | block } => array + * enum.sort_by => an_enumerator * * Sorts enum using a set of keys generated by mapping the * values in enum 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 @@ sort_by_cmp(const void *ap, const void *bp, void *data) * 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 @@ min_by_i(VALUE i, VALUE *memo, int argc, VALUE *argv) /* * call-seq: * enum.min_by {|obj| block } => obj + * enum.min_by => an_enumerator * * Returns the object in enum 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 @@ max_by_i(VALUE i, VALUE *memo, int argc, VALUE *argv) /* * call-seq: * enum.max_by {|obj| block } => obj + * enum.max_by => an_enumerator * * Returns the object in enum 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 @@ minmax_by_i(VALUE i, VALUE _memo, int argc, VALUE *argv) /* * call-seq: * enum.minmax_by {|obj| block } => [min, max] + * enum.minmax_by => an_enumerator * * Returns two elements array array containing the objects in * enum 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 @@ each_with_index_i(VALUE i, VALUE memo, int argc, VALUE *argv) /* * 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 block with two arguments, the item and its index, * for each item in enum. 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 @@ enum_each_with_index(int argc, VALUE *argv, VALUE obj) /* * call-seq: - * enum.reverse_each {|item| block } + * enum.reverse_each(*args) {|item| block } -> enum + * enum.reverse_each(*args) -> an_enumerator + * + * Builds a temporary array and traverses that array in reverse order. + * + * If no block is given, an enumerator is returned instead. * - * Traverses enum in reverse order. */ static VALUE @@ -1607,11 +1654,14 @@ each_val_i(VALUE i, VALUE p, int argc, VALUE *argv) /* * call-seq: * enum.each_entry {|obj| block} => enum + * enum.each_entry => an_enumerator * - * Calls block once for each element in self, passing that + * Calls block 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 @@ each_slice_i(VALUE i, VALUE *memo, int argc, VALUE *argv) /* * 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 elements. If no * block is given, returns an enumerator. @@ -1708,8 +1758,8 @@ each_cons_i(VALUE i, VALUE *memo, int argc, VALUE *argv) /* * 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 * elements. If no block is given, returns an enumerator. @@ -1752,8 +1802,8 @@ each_with_object_i(VALUE i, VALUE memo, int argc, VALUE *argv) /* * 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 @@ zip_i(VALUE val, NODE *memo, int argc, VALUE *argv) /* * call-seq: - * enum.zip(arg, ...) => enumerator + * enum.zip(arg, ...) => an_enumerator * enum.zip(arg, ...) {|arr| block } => nil * * Takes one element from enum and merges corresponding @@ -1958,10 +2008,13 @@ take_while_i(VALUE i, VALUE *ary, int argc, VALUE *argv) /* * 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 @@ drop_while_i(VALUE i, VALUE *args, int argc, VALUE *argv) /* * 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 @@ cycle_i(VALUE i, VALUE ary, int argc, VALUE *argv) /* * 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 block for each element of enum 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 enum 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 @@ enum_cycle(int argc, VALUE *argv, VALUE obj) rb_yield(RARRAY_PTR(ary)[i]); } } - return Qnil; /* not reached */ + return Qnil; } struct chunk_arg { @@ -2199,8 +2257,8 @@ chunk_i(VALUE yielder, VALUE enumerator, int argc, VALUE *argv) /* * 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 @@ slicebefore_i(VALUE yielder, VALUE enumerator, int argc, VALUE *argv) /* * 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. diff --git a/error.c b/error.c index cfa5d57ce2..39bec9ede4 100644 --- a/error.c +++ b/error.c @@ -1058,7 +1058,7 @@ syserr_errno(VALUE self) * 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 diff --git a/gc.c b/gc.c index b88450d0e6..3698db6424 100644 --- a/gc.c +++ b/gc.c @@ -2424,6 +2424,7 @@ os_obj_of(VALUE of) /* * 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 module is specified, calls the block @@ -2435,6 +2436,8 @@ os_obj_of(VALUE of) * returns both the numbers we defined and several constants defined in * the Math module. * + * If no block is given, an enumerator is returned instead. + * * a = 102.7 * b = 95 # Won't be returned * c = 12345678987654321 diff --git a/hash.c b/hash.c index 354593457d..55809e3375 100644 --- a/hash.c +++ b/hash.c @@ -882,10 +882,13 @@ delete_if_i(VALUE key, VALUE value, VALUE hash) /* * call-seq: * hsh.delete_if {| key, value | block } -> hsh + * hsh.delete_if -> an_enumerator * * Deletes every key-value pair from hsh for which block * evaluates to true. * + * 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 @@ rb_hash_delete_if(VALUE hash) /* * call-seq: * hsh.reject! {| key, value | block } -> hsh or nil + * hsh.reject! -> an_enumerator * * Equivalent to Hash#delete_if, but returns * nil if no changes were made. @@ -974,9 +978,12 @@ select_i(VALUE key, VALUE value, VALUE result) /* * 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 @@ keep_if_i(VALUE key, VALUE value, VALUE hash) /* * call-seq: * hsh.select! {| key, value | block } -> hsh or nil + * hsh.select! -> an_enumerator * * Equivalent to Hash#keep_if, but returns * nil if no changes were made. @@ -1029,9 +1037,12 @@ rb_hash_select_bang(VALUE hash) /* * call-seq: * hsh.keep_if {| key, value | block } -> hsh + * hsh.keep_if -> an_enumerator * * Deletes every key-value pair from hsh for which block - * evaluates to false. + * evaluates to false. + * + * If no block is given, an enumerator is returned instead. * */ @@ -1203,10 +1214,13 @@ each_value_i(VALUE key, VALUE value) /* * call-seq: * hsh.each_value {| value | block } -> hsh + * hsh.each_value -> an_enumerator * * Calls block once for each key in hsh, 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 @@ each_key_i(VALUE key, VALUE value) /* * call-seq: * hsh.each_key {| key | block } -> hsh + * hsh.each_key -> an_enumerator * * Calls block once for each key in hsh, 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 @@ each_pair_i(VALUE key, VALUE value) /* * 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 block once for each key in hsh, 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 @@ rb_hash_inspect(VALUE hash) * call-seq: * hsh.to_hash => hsh * - * Returns self. + * Returns +self+. */ static VALUE diff --git a/io.c b/io.c index a3b32d9111..4c481e59a6 100644 --- a/io.c +++ b/io.c @@ -2703,17 +2703,17 @@ rb_io_readlines(int argc, VALUE *argv, VALUE io) * 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 ios, where lines are * separated by sep. ios must be opened for @@ -2749,10 +2749,10 @@ rb_io_each_line(int argc, VALUE *argv, VALUE io) /* * 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 ios, * passing the byte as an argument. The stream must be opened for @@ -2898,10 +2898,10 @@ io_getc(rb_io_t *fptr, rb_encoding *enc) /* * 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 ios, * passing the character as an argument. The stream must be opened for @@ -2933,23 +2933,19 @@ rb_io_each_char(VALUE io) } - -/* - * call-seq: - * ios.codepoints => anEnumerator - * - * Returns an enumerator that gives each codepoint in ios. - * The stream must be opened for reading or an IOError - * 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 Integer ordinal of each character in ios, * passing the codepoint as an argument. The stream must be opened for * reading or an IOError will be raised. + * + * If no block is given, an enumerator is returned instead. + * */ static VALUE @@ -7833,10 +7829,13 @@ io_s_foreach(struct foreach_arg *arg) * 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 sep. * + * If no block is given, an enumerator is returned instead. + * * IO.foreach("testfile") {|x| print "GOT ", x } * * produces: @@ -9222,15 +9221,15 @@ argf_readbyte(VALUE argf) * 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 @@ argf_each_line(int argc, VALUE *argv, VALUE argf) /* * 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 @@ argf_each_byte(VALUE argf) /* * 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 @@ ruby_set_inplace_mode(const char *suffix) /* * 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: diff --git a/numeric.c b/numeric.c index 31b3756d25..808c364528 100644 --- a/numeric.c +++ b/numeric.c @@ -494,7 +494,7 @@ num_zero_p(VALUE num) * call-seq: * num.nonzero? -> self or nil * - * Returns self if num is not zero, nil + * Returns +self+ if num is not zero, nil * otherwise. This behavior is useful when chaining comparisons: * * a = %w( z Bb bB bb BB a aA Aa AA A ) @@ -1234,7 +1234,7 @@ flo_eql(VALUE x, VALUE y) * call-seq: * flt.to_f -> self * - * As flt is already a float, returns self. + * As flt is already a float, returns +self+. */ static VALUE @@ -1596,7 +1596,7 @@ ruby_float_step(VALUE from, VALUE to, VALUE step, int excl) /* * call-seq: * num.step(limit[, step]) {|i| block } -> self - * num.step(limit[, step]) -> enumerator + * num.step(limit[, step]) -> an_enumerator * * Invokes block with the sequence of numbers starting at * num, incremented by step (default 1) on each @@ -1612,6 +1612,8 @@ ruby_float_step(VALUE from, VALUE to, VALUE step, int excl) * the counter against limit, and increments itself using the * + 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, " " } * @@ -3018,11 +3020,13 @@ fix_size(VALUE fix) /* * call-seq: * int.upto(limit) {|i| block } -> self - * int.upto(limit) -> enumerator + * int.upto(limit) -> an_enumerator * * Iterates block, passing in integer values from int * up to and including limit. * + * If no block is given, an enumerator is returned instead. + * * 5.upto(10) { |i| print i, " " } * * produces: @@ -3057,11 +3061,13 @@ int_upto(VALUE from, VALUE to) /* * call-seq: * int.downto(limit) {|i| block } -> self - * int.downto(limit) -> enumerator + * int.downto(limit) -> an_enumerator * * Iterates block, passing decreasing values from int * down to and including limit. * + * If no block is given, an enumerator is returned instead. + * * 5.downto(1) { |n| print n, ".. " } * print " Liftoff!\n" * @@ -3097,11 +3103,13 @@ int_downto(VALUE from, VALUE to) /* * call-seq: * int.times {|i| block } -> self - * int.times -> enumerator + * int.times -> an_enumerator * * Iterates block int times, passing in values from zero to * int - 1. * + * If no block is given, an enumerator is returned instead. + * * 5.times do |i| * print i, " " * end diff --git a/range.c b/range.c index 60ad3939eb..ca9052e621 100644 --- a/range.c +++ b/range.c @@ -319,6 +319,7 @@ discrete_object_p(VALUE obj) /* * call-seq: * rng.step(n=1) {| obj | block } => rng + * rng.step(n=1) => an_enumerator * * Iterates over rng, passing each nth element to the block. If * the range contains numbers, n is added for each iteration. Otherwise @@ -326,6 +327,8 @@ discrete_object_p(VALUE obj) * elements. The following code uses class Xs, 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 @@ sym_each_i(VALUE v, void *arg) /* * call-seq: * rng.each {| i | block } => rng + * rng.each => an_enumerator * * Iterates over the elements rng, 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 diff --git a/string.c b/string.c index ca27db6963..f3fd78631c 100644 --- a/string.c +++ b/string.c @@ -2859,13 +2859,16 @@ rb_str_succ_bang(VALUE str) /* * 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 str and * ending at other_str inclusive, passing each value in turn to * the block. The String#succ method is used to generate - * each value. If optional second argument exclusive is omitted or is false, + * 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 @@ rb_str_sub_bang(int argc, VALUE *argv, VALUE str) * call-seq: * str.sub(pattern, replacement) => new_str * str.sub(pattern) {|match| block } => new_str + * str.sub(pattern) => an_enumerator * * Returns a copy of str with the first occurrence of * pattern replaced with either replacement or the value of the @@ -3566,6 +3570,8 @@ rb_str_sub_bang(int argc, VALUE *argv, VALUE str) * $&, and $' will be set appropriately. The value * returned by the block will be substituted for the match on each call. * + * If no block and no replacement 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 @@ rb_str_split(VALUE str, const char *sep0) /* * 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 str using the supplied parameter as the record separator * ($/ by default), passing each substring in turn to the supplied @@ -5794,10 +5800,10 @@ rb_str_each_line(int argc, VALUE *argv, VALUE str) /* * 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 str to the given block, or returns * an enumerator if no block is given. @@ -5825,10 +5831,10 @@ rb_str_each_byte(VALUE str) /* * 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 str to the given block, or returns * an enumerator if no block is given. @@ -5873,10 +5879,10 @@ rb_str_each_char(VALUE str) /* * 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 Integer ordinal of each character in str, * also known as a codepoint when applied to Unicode strings to the diff --git a/struct.c b/struct.c index fe3885f7a6..83c63a8b47 100644 --- a/struct.c +++ b/struct.c @@ -442,10 +442,13 @@ rb_struct_new(VALUE klass, ...) /* * call-seq: * struct.each {|obj| block } => struct + * struct.each => an_enumerator * * Calls block 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 @@ rb_struct_each(VALUE s) /* * call-seq: * struct.each_pair {|sym, obj| block } => struct + * struct.each_pair => an_enumerator * * Calls block 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_entry(VALUE s, long n) * 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 .select. * @@ -754,6 +760,7 @@ rb_struct_values_at(int argc, VALUE *argv, VALUE s) /* * call-seq: * struct.select {|i| block } => array + * struct.select => an_enumerator * * Invokes the block passing in successive elements from * struct, returning an array containing those elements diff --git a/vm_eval.c b/vm_eval.c index 9806762d96..7a8fffedb9 100644 --- a/vm_eval.c +++ b/vm_eval.c @@ -792,10 +792,13 @@ loop_i(void) /* * 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 -- cgit v1.2.3