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 --- enum.c | 112 +++++++++++++++++++++++++++++++++++++++++++++++++---------------- 1 file changed, 85 insertions(+), 27 deletions(-) (limited to 'enum.c') 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. -- cgit v1.2.3