diff options
author | Marc-Andre Lafortune <github@marc-andre.ca> | 2020-05-05 17:02:59 -0400 |
---|---|---|
committer | Marc-Andre Lafortune <github@marc-andre.ca> | 2020-05-05 17:04:11 -0400 |
commit | 7bde98125e7f99cab6fe80b59189561bf66fcd0e (patch) | |
tree | 59ed2119852bac9277d9401bccb6ddc714711ddc /enumerator.c | |
parent | 77f19d26b9abde74ec03a6d2a51688c49cad20f4 (diff) |
Improve documentation for Enumerator#next, next_values, peek and peek_values.
[DOC] [#16829]
Diffstat (limited to 'enumerator.c')
-rw-r--r-- | enumerator.c | 22 |
1 files changed, 15 insertions, 7 deletions
diff --git a/enumerator.c b/enumerator.c index 9632b02698..cc0cce8fae 100644 --- a/enumerator.c +++ b/enumerator.c @@ -81,6 +81,14 @@ * puts e.next # => 3 * puts e.next # raises StopIteration * + * Note that enumeration sequence by +next+, +next_values+, +peek+ and + * +peek_values+ do not affect other non-external + * enumeration methods, unless the underlying iteration method itself has + * side-effect, e.g. IO#each_line. + * + * Moreover, implementation typically uses fibers so performance could be + * slower and exception stacktraces different than expected. + * * You can use this to implement an internal iterator as follows: * * def ext_each(e) @@ -804,6 +812,8 @@ get_next_values(VALUE obj, struct enumerator *e) * internal position forward. When the position reached at the end, * StopIteration is raised. * + * See class-level notes about external iterators. + * * This method can be used to distinguish <code>yield</code> and <code>yield * nil</code>. * @@ -837,10 +847,6 @@ get_next_values(VALUE obj, struct enumerator *e) * # yield nil [nil] nil * # yield [1, 2] [[1, 2]] [1, 2] * - * Note that +next_values+ does not affect other non-external enumeration - * methods unless underlying iteration method itself has side-effect, e.g. - * IO#each_line. - * */ static VALUE @@ -894,9 +900,7 @@ ary2sv(VALUE args, int dup) * p e.next #=> 3 * p e.next #raises StopIteration * - * Note that enumeration sequence by +next+ does not affect other non-external - * enumeration methods, unless the underlying iteration methods itself has - * side-effect, e.g. IO#each_line. + * See class-level notes about external iterators. * */ @@ -926,6 +930,8 @@ enumerator_peek_values(VALUE obj) * doesn't move the internal position forward. If the position is already at * the end, StopIteration is raised. * + * See class-level notes about external iterators. + * * === Example * * o = Object.new @@ -960,6 +966,8 @@ enumerator_peek_values_m(VALUE obj) * position forward. If the position is already at the end, StopIteration * is raised. * + * See class-level notes about external iterators. + * * === Example * * a = [1,2,3] |