(groovy-website) branch asf-site updated: improve "collection extension method" section

[paulk]

This is an automated email from the ASF dual-hosted git repository.

paulk pushed a commit to branch asf-site
in repository https://gitbox.apache.org/repos/asf/groovy-website.git


The following commit(s) were added to refs/heads/asf-site by this push:
     new fc92ce9  improve "collection extension method" section
fc92ce9 is described below

commit fc92ce9215204180be324a6dbe28937e1b7c0fa4
Author: Paul King <pa...@asert.com.au>
AuthorDate: Tue May 13 16:27:48 2025 +1000

    improve "collection extension method" section
---
 site/src/site/releasenotes/groovy-5.0.adoc | 87 ++++++++++++++++++++++++++++--
 1 file changed, 83 insertions(+), 4 deletions(-)

diff --git a/site/src/site/releasenotes/groovy-5.0.adoc 
b/site/src/site/releasenotes/groovy-5.0.adoc
index b8695b0..5ef2e52 100644
--- a/site/src/site/releasenotes/groovy-5.0.adoc
+++ b/site/src/site/releasenotes/groovy-5.0.adoc
@@ -67,7 +67,7 @@ Groovy supports such methods on JDK11+ and supports some 
slight simplifications:
 
 [source,groovy]
 ----
-void main() {
+def main() {
     println 'Hello, World!'
 }
 ----
@@ -76,7 +76,7 @@ Finally, Groovy also provides an "instance run" method as an 
alternative form:
 
 [source,groovy]
 ----
-void run() {
+def run() {
     println 'Hello, World!'
 }
 ----
@@ -252,8 +252,56 @@ Groovy provides over 2000 extension methods to 150+ JDK 
classes to enhance JDK f
 
 === Additional Collection extensions
 
-We have added a `flattenMany` method which is a close cousin to the
-`collectMany` method. These are Groovy's `flatMap` like methods.
+The `repeat` method repeats the elements in a collection a certain number of 
times, or infinitely.
+The finite variant is an alias for `multiply`, the '*' operator.
+
+[source,groovy]
+----
+def words = ['row'].repeat(3) + ['your', 'boat']
+assert words.join(' ') == 'row row row your boat'
+
+def batman = ['na'].repeat().take(13).join('-') + '...Batman'
+assert batman == 'na-na-na-na-na-na-na-na-na-na-na-na-na...Batman'
+----
+
+The `zip` method creates tuples from elements of two collections, grouping 
elements with the same index.
+In the case of differing size collections, the number of tuples created will be
+equal to the size of the shorter of the two collections.
+
+The `zipAll` method provides a way to handle collections of different sizes, 
giving
+default values in that case.
+The number of tuples created will be
+equal to the size of the longer of the two collections.
+
+[source,groovy]
+----
+def one = ['🍎'].repeat(4)
+def two = ['🍏'].repeat(3)
+assert one.zip(two).toString() == '[[🍎, 🍏], [🍎, 🍏], [🍎, 🍏]]'
+assert two.zip(one).toString() == '[[🍏, 🍎], [🍏, 🍎], [🍏, 🍎]]'
+assert one.zipAll(two, '_', '🍌')*.join() == ['🍎🍏', '🍎🍏', '🍎🍏', '🍎🍌']
+assert two.zipAll(one, '🍊', '_')*.join() == ['🍏🍎', '🍏🍎', '🍏🍎', '🍊🍎']
+----
+
+The `interleave` method interleaves the elements from two collections.
+If the collections are of different sizes, interleaving will stop once one
+of the collections has no more elements. An optional boolean parameter allows 
the remaining
+elements of the longer collection to be appended to the end of the result.
+
+When the collections are the same size, the same result could be achieved by 
zipping
+the collections and then flattening the result, but `interleave` is more 
efficient
+and provides options for handling the case when the collections are different 
sizes.
+
+[source,groovy]
+----
+def gs = ['🅶'].repeat(4)
+def hs = ['💚'].repeat(3)
+assert gs.interleave(hs).join() == '🅶💚🅶💚🅶💚'
+assert gs.interleave(hs, true).join() == '🅶💚🅶💚🅶💚🅶'
+----
+
+The `flattenMany` method is a close cousin to the
+`collectMany` method. These are Groovy's `flatMap`-like methods.
 
 [source,groovy]
 ----
@@ -331,6 +379,37 @@ assert d.and(e, String.CASE_INSENSITIVE_ORDER) == ['a', 
'B'] as Set
 assert e.union(d, String.CASE_INSENSITIVE_ORDER) == ['A', 'b', 'D', 'c'] as Set
 ----
 
+The `injectAll` method is like `inject` but collects intermediate results.
+This is like the `scan` gatherer in JDK24 or the prefix scan operation in 
`Arrays#parallelPrefix`.
+
+[source,groovy]
+----
+def letters = 'a'..'d'
+assert ['a', 'ab', 'abc', 'abcd'] == letters.injectAll('', String::plus)
+assert ['a', 'ab', 'abc', 'abcd'] == 
letters.stream().gather(Gatherers.scan(()->'', String::plus)).toList() // JDK24+
+
+Integer[] nums = 1..4
+Arrays.parallelPrefix(nums, Integer::plus)
+assert [1, 3, 6, 10] == nums
+assert [1, 3, 6, 10] == (1..4).injectAll(0, Integer::plus)
+----
+
+The `partitionPoint` method is used when processing partitioned (often sorted) 
collections.
+You can use it to find the first and last index of a partition in a collection.
+For a sorted collection, this would tell you where you could insert a new 
element and maintain
+sorted ordering.
+
+[source,groovy]
+----
+def nums = [0, 1, 1, 3, 4, 4, 4, 5, 7, 9]
+def lower = nums.partitionPoint{ it < 4 }
+def upper = nums.partitionPoint{ it <= 4 }
+assert [lower, upper] == [4, 7]
+nums.indices.every {
+    it in lower..<upper ==> nums[it] == 4
+}
+----
+
 ==== Checked collections
 
 Java, being statically typed, tries hard to ensure type safety at compile time