From 8038d5e40a079d60dfcf7cab1155528959760c28 Mon Sep 17 00:00:00 2001 From: Burdette Lamar Date: Sat, 28 May 2022 14:20:00 -0500 Subject: Revert flawed doc for slice_after, slice_when, and chunk_while (#5952) Restores doc for the methods that were cited in https://bugs.ruby-lang.org/issues/18765. --- enum.c | 162 +++++++++++++++++++++++++++++++++++++++++++---------------------- 1 file changed, 107 insertions(+), 55 deletions(-) diff --git a/enum.c b/enum.c index 403ce45dca..205ea6a451 100644 --- a/enum.c +++ b/enum.c @@ -4079,39 +4079,24 @@ sliceafter_i(RB_BLOCK_CALL_FUNC_ARGLIST(yielder, enumerator)) /* * call-seq: - * slice_after(pattern) -> enumerator - * slice_after {|array| ... } -> enumerator + * enum.slice_after(pattern) -> an_enumerator + * enum.slice_after { |elt| bool } -> an_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: + * Creates an enumerator for each chunked elements. + * The ends of chunks are defined by _pattern_ and the block. * - * a = %w[foo bar fop for baz fob fog bam foy] - * e = a.slice_after(/ba/) # => # - * e.each {|array| p array } + * If _pattern_ === _elt_ returns true or the block + * returns true for the element, the element is end of a + * chunk. * - * Output: + * The === and _block_ is called from the first element to the last + * element of _enum_. * - * ["foo", "bar"] - * ["fop", "for", "baz"] - * ["fob", "fog", "bam"] - * ["foy"] + * The result enumerator yields the chunked elements as an array. + * So +each+ method can be called as follows: * - * 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: - * - * e = (1..20).slice_after {|i| i % 4 == 2 } # => # - * e.each {|array| p array } - * - * Output: - * - * [1, 2] - * [3, 4, 5, 6] - * [7, 8, 9, 10] - * [11, 12, 13, 14] - * [15, 16, 17, 18] - * [19, 20] + * enum.slice_after(pattern).each { |ary| ... } + * enum.slice_after { |elt| bool }.each { |ary| ... } * * Other methods of the Enumerator class and Enumerable module, * such as +map+, etc., are also usable. @@ -4225,23 +4210,65 @@ slicewhen_i(RB_BLOCK_CALL_FUNC_ARGLIST(yielder, enumerator)) /* * call-seq: - * slice_when {|element, next_element| ... } -> enumerator + * enum.slice_when {|elt_before, elt_after| bool } -> an_enumerator * - * 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: + * Creates an enumerator for each chunked elements. + * The beginnings of chunks are defined by the block. * - * a = [0, 1, 2, 4, 5, 6, 8, 9] - * e = a.slice_when {|i, j| j != i + 1 } - * e.each {|array| p array } + * 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. * - * Output: + * 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. + * + * For example, one-by-one increasing subsequence can be chunked as follows: * - * [0, 1, 2] - * [4, 5, 6] - * [8, 9] + * 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]] + * + * Paragraphs (non-empty lines with trailing empty lines) can be chunked as follows: + * (See Enumerable#chunk to ignore empty lines.) + * + * 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"]] + * + * Enumerable#chunk_while does the same, except splitting when the block + * returns false instead of true. */ static VALUE enum_slice_when(VALUE enumerable) @@ -4262,27 +4289,52 @@ enum_slice_when(VALUE enumerable) /* * call-seq: - * chunk_while {|element, next_element| ... } -> enumerator + * enum.chunk_while {|elt_before, elt_after| bool } -> an_enumerator * - * 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: + * Creates an enumerator for each chunked elements. + * The beginnings of chunks are defined by the block. * - * Example: + * 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. * - * 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 } + * The block is called the length of the receiver enumerator minus one. * - * Output: + * The result enumerator yields the chunked elements as an array. + * So +each+ method can be called as follows: * - * [1, 2] - * [4] - * [9, 10, 11, 12] - * [15, 16] - * [19, 20, 21] + * 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: + * + * 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]] + * + * 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.chunk_while {|i, j| i.even? == j.even? }.to_a + * #=> [[7, 5, 9], [2, 0], [7, 9], [4, 2, 0]] * + * 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.3