@@ -4069,39 +4069,24 @@ sliceafter_i(RB_BLOCK_CALL_FUNC_ARGLIST(yielder, enumerator))
40694069
40704070/*
40714071 * call-seq:
4072- * slice_after(pattern) -> enumerator
4073- * slice_after {|array| ... } -> enumerator
4072+ * enum. slice_after(pattern) -> an_enumerator
4073+ * enum. slice_after { |elt| bool } -> an_enumerator
40744074 *
4075- * With argument +pattern+, returns an enumerator that uses the pattern
4076- * to partition elements into arrays ("slices").
4077- * An element ends the current slice if <tt>element === pattern</tt>:
4075+ * Creates an enumerator for each chunked elements.
4076+ * The ends of chunks are defined by _pattern_ and the block.
40784077 *
4079- * a = %w[foo bar fop for baz fob fog bam foy]
4080- * e = a.slice_after(/ba/) # => #<Enumerator: ...>
4081- * e.each {|array| p array }
4078+ * If <code>_pattern_ === _elt_</code> returns <code>true</code> or the block
4079+ * returns <code>true</code> for the element, the element is end of a
4080+ * chunk.
40824081 *
4083- * Output:
4082+ * The <code>===</code> and _block_ is called from the first element to the last
4083+ * element of _enum_.
40844084 *
4085- * ["foo", "bar"]
4086- * ["fop", "for", "baz"]
4087- * ["fob", "fog", "bam"]
4088- * ["foy"]
4085+ * The result enumerator yields the chunked elements as an array.
4086+ * So +each+ method can be called as follows:
40894087 *
4090- * With a block, returns an enumerator that uses the block
4091- * to partition elements into arrays.
4092- * An element ends the current slice if its block return is a truthy value:
4093- *
4094- * e = (1..20).slice_after {|i| i % 4 == 2 } # => #<Enumerator: ...>
4095- * e.each {|array| p array }
4096- *
4097- * Output:
4098- *
4099- * [1, 2]
4100- * [3, 4, 5, 6]
4101- * [7, 8, 9, 10]
4102- * [11, 12, 13, 14]
4103- * [15, 16, 17, 18]
4104- * [19, 20]
4088+ * enum.slice_after(pattern).each { |ary| ... }
4089+ * enum.slice_after { |elt| bool }.each { |ary| ... }
41054090 *
41064091 * Other methods of the Enumerator class and Enumerable module,
41074092 * such as +map+, etc., are also usable.
@@ -4215,23 +4200,65 @@ slicewhen_i(RB_BLOCK_CALL_FUNC_ARGLIST(yielder, enumerator))
42154200
42164201/*
42174202 * call-seq:
4218- * slice_when {|element, next_element| ... } -> enumerator
4203+ * enum. slice_when {|elt_before, elt_after| bool } -> an_enumerator
42194204 *
4220- * The returned enumerator uses the block
4221- * to partition elements into arrays ("slices");
4222- * it calls the block with each element and its successor;
4223- * begins a new slice if and only if the block returns a truthy value:
4205+ * Creates an enumerator for each chunked elements.
4206+ * The beginnings of chunks are defined by the block.
42244207 *
4225- * a = [0, 1, 2, 4, 5, 6, 8, 9]
4226- * e = a.slice_when {|i, j| j != i + 1 }
4227- * e.each {|array| p array }
4208+ * This method splits each chunk using adjacent elements,
4209+ * _elt_before_ and _elt_after_,
4210+ * in the receiver enumerator.
4211+ * This method split chunks between _elt_before_ and _elt_after_ where
4212+ * the block returns <code>true</code>.
42284213 *
4229- * Output:
4214+ * The block is called the length of the receiver enumerator minus one.
4215+ *
4216+ * The result enumerator yields the chunked elements as an array.
4217+ * So +each+ method can be called as follows:
4218+ *
4219+ * enum.slice_when { |elt_before, elt_after| bool }.each { |ary| ... }
4220+ *
4221+ * Other methods of the Enumerator class and Enumerable module,
4222+ * such as +to_a+, +map+, etc., are also usable.
4223+ *
4224+ * For example, one-by-one increasing subsequence can be chunked as follows:
42304225 *
4231- * [0, 1, 2]
4232- * [4, 5, 6]
4233- * [8, 9]
4226+ * a = [1,2,4,9,10,11,12,15,16,19,20,21]
4227+ * b = a.slice_when {|i, j| i+1 != j }
4228+ * p b.to_a #=> [[1, 2], [4], [9, 10, 11, 12], [15, 16], [19, 20, 21]]
4229+ * c = b.map {|a| a.length < 3 ? a : "#{a.first}-#{a.last}" }
4230+ * p c #=> [[1, 2], [4], "9-12", [15, 16], "19-21"]
4231+ * d = c.join(",")
4232+ * p d #=> "1,2,4,9-12,15,16,19-21"
42344233 *
4234+ * Near elements (threshold: 6) in sorted array can be chunked as follows:
4235+ *
4236+ * a = [3, 11, 14, 25, 28, 29, 29, 41, 55, 57]
4237+ * p a.slice_when {|i, j| 6 < j - i }.to_a
4238+ * #=> [[3], [11, 14], [25, 28, 29, 29], [41], [55, 57]]
4239+ *
4240+ * Increasing (non-decreasing) subsequence can be chunked as follows:
4241+ *
4242+ * a = [0, 9, 2, 2, 3, 2, 7, 5, 9, 5]
4243+ * p a.slice_when {|i, j| i > j }.to_a
4244+ * #=> [[0, 9], [2, 2, 3], [2, 7], [5, 9], [5]]
4245+ *
4246+ * Adjacent evens and odds can be chunked as follows:
4247+ * (Enumerable#chunk is another way to do it.)
4248+ *
4249+ * a = [7, 5, 9, 2, 0, 7, 9, 4, 2, 0]
4250+ * p a.slice_when {|i, j| i.even? != j.even? }.to_a
4251+ * #=> [[7, 5, 9], [2, 0], [7, 9], [4, 2, 0]]
4252+ *
4253+ * Paragraphs (non-empty lines with trailing empty lines) can be chunked as follows:
4254+ * (See Enumerable#chunk to ignore empty lines.)
4255+ *
4256+ * lines = ["foo\n", "bar\n", "\n", "baz\n", "qux\n"]
4257+ * p lines.slice_when {|l1, l2| /\A\s*\z/ =~ l1 && /\S/ =~ l2 }.to_a
4258+ * #=> [["foo\n", "bar\n", "\n"], ["baz\n", "qux\n"]]
4259+ *
4260+ * Enumerable#chunk_while does the same, except splitting when the block
4261+ * returns <code>false</code> instead of <code>true</code>.
42354262 */
42364263static VALUE
42374264enum_slice_when (VALUE enumerable )
@@ -4252,27 +4279,52 @@ enum_slice_when(VALUE enumerable)
42524279
42534280/*
42544281 * call-seq:
4255- * chunk_while {|element, next_element| ... } -> enumerator
4282+ * enum. chunk_while {|elt_before, elt_after| bool } -> an_enumerator
42564283 *
4257- * The returned Enumerator uses the block to partition elements
4258- * into arrays ("chunks");
4259- * it calls the block with each element and its successor;
4260- * begins a new chunk if and only if the block returns a truthy value:
4284+ * Creates an enumerator for each chunked elements.
4285+ * The beginnings of chunks are defined by the block.
42614286 *
4262- * Example:
4287+ * This method splits each chunk using adjacent elements,
4288+ * _elt_before_ and _elt_after_,
4289+ * in the receiver enumerator.
4290+ * This method split chunks between _elt_before_ and _elt_after_ where
4291+ * the block returns <code>false</code>.
42634292 *
4264- * a = [1, 2, 4, 9, 10, 11, 12, 15, 16, 19, 20, 21]
4265- * e = a.chunk_while {|i, j| j == i + 1 }
4266- * e.each {|array| p array }
4293+ * The block is called the length of the receiver enumerator minus one.
42674294 *
4268- * Output:
4295+ * The result enumerator yields the chunked elements as an array.
4296+ * So +each+ method can be called as follows:
42694297 *
4270- * [1, 2]
4271- * [4]
4272- * [9, 10, 11, 12]
4273- * [15, 16]
4274- * [19, 20, 21]
4298+ * enum.chunk_while { |elt_before, elt_after| bool }.each { |ary| ... }
4299+ *
4300+ * Other methods of the Enumerator class and Enumerable module,
4301+ * such as +to_a+, +map+, etc., are also usable.
4302+ *
4303+ * For example, one-by-one increasing subsequence can be chunked as follows:
4304+ *
4305+ * a = [1,2,4,9,10,11,12,15,16,19,20,21]
4306+ * b = a.chunk_while {|i, j| i+1 == j }
4307+ * p b.to_a #=> [[1, 2], [4], [9, 10, 11, 12], [15, 16], [19, 20, 21]]
4308+ * c = b.map {|a| a.length < 3 ? a : "#{a.first}-#{a.last}" }
4309+ * p c #=> [[1, 2], [4], "9-12", [15, 16], "19-21"]
4310+ * d = c.join(",")
4311+ * p d #=> "1,2,4,9-12,15,16,19-21"
4312+ *
4313+ * Increasing (non-decreasing) subsequence can be chunked as follows:
4314+ *
4315+ * a = [0, 9, 2, 2, 3, 2, 7, 5, 9, 5]
4316+ * p a.chunk_while {|i, j| i <= j }.to_a
4317+ * #=> [[0, 9], [2, 2, 3], [2, 7], [5, 9], [5]]
4318+ *
4319+ * Adjacent evens and odds can be chunked as follows:
4320+ * (Enumerable#chunk is another way to do it.)
4321+ *
4322+ * a = [7, 5, 9, 2, 0, 7, 9, 4, 2, 0]
4323+ * p a.chunk_while {|i, j| i.even? == j.even? }.to_a
4324+ * #=> [[7, 5, 9], [2, 0], [7, 9], [4, 2, 0]]
42754325 *
4326+ * Enumerable#slice_when does the same, except splitting when the block
4327+ * returns <code>true</code> instead of <code>false</code>.
42764328 */
42774329static VALUE
42784330enum_chunk_while (VALUE enumerable )
0 commit comments