From abd473928ec54e2ee990d178e42f2f544f21b041 Mon Sep 17 00:00:00 2001 From: Burdette Lamar Date: Tue, 5 Oct 2021 18:57:06 -0500 Subject: Enhanced RDoc for Enumerable (#4938) Treats: #slice_after #slice_when #chunk_while --- enum.c | 167 ++++++++++++++++++++++------------------------------------------- 1 file changed, 57 insertions(+), 110 deletions(-) (limited to 'enum.c') diff --git a/enum.c b/enum.c index 05c2201992..460a7642ec 100644 --- a/enum.c +++ b/enum.c @@ -3624,8 +3624,7 @@ chunk_i(RB_BLOCK_CALL_FUNC_ARGLIST(yielder, enumerator)) * call-seq: * chunk {|array| ... } -> enumerator * - * Returns an Enumerator; - * each element in the enumerator is a 2-element array consisting of: + * Each element in the returned enumerator is a 2-element array consisting of: * * - A value returned by the block. * - An array ("chunk") containing the element for which that value was returned, @@ -3800,7 +3799,7 @@ slicebefore_i(RB_BLOCK_CALL_FUNC_ARGLIST(yielder, enumerator)) * slice_before {|array| ... } -> enumerator * * With argument +pattern+, returns an enumerator that uses the pattern - * to partition elements into arrays. + * to partition elements into arrays ("slices"). * An element begins a new slice if element === pattern * (or if it is the first element). * @@ -4042,24 +4041,39 @@ sliceafter_i(RB_BLOCK_CALL_FUNC_ARGLIST(yielder, enumerator)) /* * call-seq: - * enum.slice_after(pattern) -> an_enumerator - * enum.slice_after { |elt| bool } -> an_enumerator + * slice_after(pattern) -> enumerator + * slice_after {|array| ... } -> enumerator + * + * With argument +pattern+, returns an enumerator that uses the pattern + * to partition elements into arrays ("slices"). + * An element ends the current slice if element === pattern: + * + * a = %w[foo bar fop for baz fob fog bam foy] + * e = a.slice_after(/ba/) # => # + * e.each {|array| p array } + * + * Output: * - * Creates an enumerator for each chunked elements. - * The ends of chunks are defined by _pattern_ and the block. + * ["foo", "bar"] + * ["fop", "for", "baz"] + * ["fob", "fog", "bam"] + * ["foy"] * - * If _pattern_ === _elt_ returns true or the block - * returns true for the element, the element is end of a - * chunk. + * With a block, returns an enumerator that uses the block + * to partition elements into arrays. + * An element ends the current slice if its block return is a truthy value: * - * The === and _block_ is called from the first element to the last - * element of _enum_. + * e = (1..20).slice_after {|i| i % 4 == 2 } # => # + * e.each {|array| p array } * - * The result enumerator yields the chunked elements as an array. - * So +each+ method can be called as follows: + * Output: * - * enum.slice_after(pattern).each { |ary| ... } - * enum.slice_after { |elt| bool }.each { |ary| ... } + * [1, 2] + * [3, 4, 5, 6] + * [7, 8, 9, 10] + * [11, 12, 13, 14] + * [15, 16, 17, 18] + * [19, 20] * * Other methods of the Enumerator class and Enumerable module, * such as +map+, etc., are also usable. @@ -4173,65 +4187,23 @@ slicewhen_i(RB_BLOCK_CALL_FUNC_ARGLIST(yielder, enumerator)) /* * call-seq: - * enum.slice_when {|elt_before, elt_after| bool } -> an_enumerator - * - * Creates an enumerator for each chunked elements. - * The beginnings of chunks are defined by the block. - * - * This method splits each chunk using adjacent elements, - * _elt_before_ and _elt_after_, - * in the receiver enumerator. - * This method split chunks between _elt_before_ and _elt_after_ where - * the block returns true. - * - * The block is called the length of the receiver enumerator minus one. - * - * The result enumerator yields the chunked elements as an array. - * So +each+ method can be called as follows: - * - * enum.slice_when { |elt_before, elt_after| bool }.each { |ary| ... } - * - * Other methods of the Enumerator class and Enumerable module, - * such as +to_a+, +map+, etc., are also usable. + * slice_when {|element, next_element| ... } -> enumerator * - * For example, one-by-one increasing subsequence can be chunked as follows: + * The returned enumerator uses the block + * to partition elements into arrays ("slices"); + * it calls the block with each element and its successor; + * begins a new slice if and only if the block returns a truthy value: * - * a = [1,2,4,9,10,11,12,15,16,19,20,21] - * b = a.slice_when {|i, j| i+1 != j } - * p b.to_a #=> [[1, 2], [4], [9, 10, 11, 12], [15, 16], [19, 20, 21]] - * c = b.map {|a| a.length < 3 ? a : "#{a.first}-#{a.last}" } - * p c #=> [[1, 2], [4], "9-12", [15, 16], "19-21"] - * d = c.join(",") - * p d #=> "1,2,4,9-12,15,16,19-21" - * - * Near elements (threshold: 6) in sorted array can be chunked as follows: - * - * a = [3, 11, 14, 25, 28, 29, 29, 41, 55, 57] - * p a.slice_when {|i, j| 6 < j - i }.to_a - * #=> [[3], [11, 14], [25, 28, 29, 29], [41], [55, 57]] - * - * Increasing (non-decreasing) subsequence can be chunked as follows: - * - * a = [0, 9, 2, 2, 3, 2, 7, 5, 9, 5] - * p a.slice_when {|i, j| i > j }.to_a - * #=> [[0, 9], [2, 2, 3], [2, 7], [5, 9], [5]] - * - * Adjacent evens and odds can be chunked as follows: - * (Enumerable#chunk is another way to do it.) - * - * a = [7, 5, 9, 2, 0, 7, 9, 4, 2, 0] - * p a.slice_when {|i, j| i.even? != j.even? }.to_a - * #=> [[7, 5, 9], [2, 0], [7, 9], [4, 2, 0]] + * a = [0, 1, 2, 4, 5, 6, 8, 9] + * e = a.slice_when {|i, j| j != i + 1 } + * e.each {|array| p array } * - * Paragraphs (non-empty lines with trailing empty lines) can be chunked as follows: - * (See Enumerable#chunk to ignore empty lines.) + * Output: * - * lines = ["foo\n", "bar\n", "\n", "baz\n", "qux\n"] - * p lines.slice_when {|l1, l2| /\A\s*\z/ =~ l1 && /\S/ =~ l2 }.to_a - * #=> [["foo\n", "bar\n", "\n"], ["baz\n", "qux\n"]] + * [0, 1, 2] + * [4, 5, 6] + * [8, 9] * - * Enumerable#chunk_while does the same, except splitting when the block - * returns false instead of true. */ static VALUE enum_slice_when(VALUE enumerable) @@ -4252,52 +4224,27 @@ enum_slice_when(VALUE enumerable) /* * call-seq: - * enum.chunk_while {|elt_before, elt_after| bool } -> an_enumerator - * - * Creates an enumerator for each chunked elements. - * The beginnings of chunks are defined by the block. - * - * This method splits each chunk using adjacent elements, - * _elt_before_ and _elt_after_, - * in the receiver enumerator. - * This method split chunks between _elt_before_ and _elt_after_ where - * the block returns false. + * chunk_while {|element, next_element| ... } -> enumerator * - * The block is called the length of the receiver enumerator minus one. + * The returned Enumerator uses the block to partition elements + * into arrays ("chunks"); + * it calls the block with each element and its successor; + * begins a new chunk if and only if the block returns a truthy value: * - * The result enumerator yields the chunked elements as an array. - * So +each+ method can be called as follows: - * - * enum.chunk_while { |elt_before, elt_after| bool }.each { |ary| ... } - * - * Other methods of the Enumerator class and Enumerable module, - * such as +to_a+, +map+, etc., are also usable. - * - * For example, one-by-one increasing subsequence can be chunked as follows: - * - * a = [1,2,4,9,10,11,12,15,16,19,20,21] - * b = a.chunk_while {|i, j| i+1 == j } - * p b.to_a #=> [[1, 2], [4], [9, 10, 11, 12], [15, 16], [19, 20, 21]] - * c = b.map {|a| a.length < 3 ? a : "#{a.first}-#{a.last}" } - * p c #=> [[1, 2], [4], "9-12", [15, 16], "19-21"] - * d = c.join(",") - * p d #=> "1,2,4,9-12,15,16,19-21" - * - * Increasing (non-decreasing) subsequence can be chunked as follows: + * Example: * - * a = [0, 9, 2, 2, 3, 2, 7, 5, 9, 5] - * p a.chunk_while {|i, j| i <= j }.to_a - * #=> [[0, 9], [2, 2, 3], [2, 7], [5, 9], [5]] + * a = [1, 2, 4, 9, 10, 11, 12, 15, 16, 19, 20, 21] + * e = a.chunk_while {|i, j| j == i + 1 } + * e.each {|array| p array } * - * Adjacent evens and odds can be chunked as follows: - * (Enumerable#chunk is another way to do it.) + * Output: * - * a = [7, 5, 9, 2, 0, 7, 9, 4, 2, 0] - * p a.chunk_while {|i, j| i.even? == j.even? }.to_a - * #=> [[7, 5, 9], [2, 0], [7, 9], [4, 2, 0]] + * [1, 2] + * [4] + * [9, 10, 11, 12] + * [15, 16] + * [19, 20, 21] * - * Enumerable#slice_when does the same, except splitting when the block - * returns true instead of false. */ static VALUE enum_chunk_while(VALUE enumerable) -- cgit v1.2.1