Gatherers4j

A library of useful Stream Gatherers (custom intermediate operations) for Java 25+.

See the full set of documentation for information on how to use Gatherers4j.

Installing

To use this library, add it as a dependency to your build. This library has one transitive dependency - the JSpecify set of annotations for static analysis tools.

Maven

Add the following dependency to pom.xml.

<dependency>
    <groupId>com.ginsberg</groupId>
    <artifactId>gatherers4j</artifactId>
    <version>0.13.0</version>
</dependency>

Gradle

Add the following dependency to build.gradle or build.gradle.kts

implementation("com.ginsberg:gatherers4j:0.13.0")

Gatherers In This Library

For convenience, the full list of gatherers in this library are broken into five categories:

1. Sequence Operations
2. Filtering and Selection
3. Grouping and Windowing
4. Validation and Constraints
5. Mathematical Operations

Sequence Operations

Gatherers that reorder, combine, or manipulate the sequence of elements.

| Function | Purpose | |-----------------------------------------------------------------------------------------------------------------|-----------------------------------------------------------------------------------------------------------------------------------------------------| | crossWith() | Emit each element of the source stream with each element of the given iterable, iterator, stream, or varargs as a Pair to the output stream | | foldIndexed(fn) | Perform a fold over the input stream where each element is included along with its zero-based index | | interleaveWith() | Creates a stream of alternating objects from the input stream and the argument iterable, iterator, stream, or varargs | | mapIndexed() | Perform a mapping operation given the element being mapped and its zero-based index. | | orderByFrequency() | Returns a stream where elements are ordered in either ascending or descending frequency contained in WithCount<T> wrapper objects. | | orderByFrequencyBy(fn) | Returns a stream of mapped values ordered by frequency (ascending or descending) contained in WithCount<MAPPED> wrapper objects. | | peekIndexed() | Peek at each element of the stream along with its zero-based index | | repeat(n) | Repeat the input stream n times to the output stream | | repeatInfinitely() | Repeat the input stream to the output stream forever (or until some downstream operation stops it) | | reverse() | Reverse the order of the stream | | rotate(direction, n) | Rotate the stream n elements to direction specified. Stores entire stream into memory. | | scanIndexed(fn) | Performs a scan on the input stream using the given function, and includes the index of the elements | | shuffle() | Shuffle the stream into a random order, optionally taking a RandomGenerator | | throttle(amount, duration) | Limit stream elements to amount elements over duration, pausing until a new duration period starts | | withIndex() | Maps all elements of the stream as-is along with their 0-based index | | zipWith() | Creates a stream of Pair objects whose values come from the input stream and argument iterable, iterator, stream, or varargs | | zipWithNext() | Creates a stream of List objects via a sliding window of width 2 and stepping 1 |

Filtering and Selection

Gatherers that select or remove elements based on some criteria.

| Function | Purpose | |------------------------------------------------------------------------------------------------------------------------------------|--------------------------------------------------------------------------------------------------------------------------------| | debounce(amount, duration) | Limit stream elements to amount elements over duration, dropping any elements over the limit until a new duration starts | | dedupeConsecutive() | Remove consecutive duplicates from a stream | | dedupeConsecutiveBy(fn) | Remove consecutive duplicates from a stream as returned by fn | | distinctBy(fn) | Emit only distinct elements from the stream, as measured by fn | | dropEveryNth(n) | Drop everyn^th element from the input stream | | dropLast(n) | Keep all but the last n elements of the stream | | filterIndexed() | Filter a stream according to a given predicate, which takes both the item being examined and its zero-based index. | | filterInstanceOf | Filter the elements in the stream to only include elements of the given types. | | filterOrdered(order) | Filter the input stream of Comparable objects so that is strictly in the given order | | | filterOrderedBy(order, comparator) | Filter the input stream of objects so that it contains only elements in the given order, as measured by a given Comparator | | sampleFixedSize(n) | Perform a fixed size sampling over the input stream. | | [`samplePercent