https://github.com/tginsberg/gatherers4j
A library of useful Stream Gatherers (custom intermediate operations) for Java.
https://github.com/tginsberg/gatherers4j
gatherer gatherers java java-24 java24
Last synced: 6 months ago
JSON representation
A library of useful Stream Gatherers (custom intermediate operations) for Java.
- Host: GitHub
- URL: https://github.com/tginsberg/gatherers4j
- Owner: tginsberg
- License: apache-2.0
- Created: 2024-05-09T19:22:52.000Z (about 2 years ago)
- Default Branch: main
- Last Pushed: 2025-04-02T23:22:27.000Z (over 1 year ago)
- Last Synced: 2025-04-10T01:13:15.508Z (about 1 year ago)
- Topics: gatherer, gatherers, java, java-24, java24
- Language: Java
- Homepage: https://tginsberg.github.io/gatherers4j/
- Size: 412 KB
- Stars: 81
- Watchers: 5
- Forks: 5
- Open Issues: 2
-
Metadata Files:
- Readme: README.md
- Changelog: CHANGELOG.md
- License: LICENSE
Awesome Lists containing this project
README
# Gatherers4j
A library of useful [Stream Gatherers](https://openjdk.org/jeps/485) (custom intermediate operations) for Java 25+.
See [the full set of documentation](https://tginsberg.github.io/gatherers4j/) 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](https://jspecify.dev/) set of annotations for static analysis tools.
**Maven**
Add the following dependency to `pom.xml`.
```xml
com.ginsberg
gatherers4j
0.13.0
```
**Gradle**
Add the following dependency to `build.gradle` or `build.gradle.kts`
```groovy
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](#sequence-operations)
2. [Filtering and Selection](#filtering-and-selection)
3. [Grouping and Windowing](#grouping-and-windowing)
4. [Validation and Constraints](#validation-and-constraints)
5. [Mathematical Operations](#mathematical-operations)
## Sequence Operations
Gatherers that reorder, combine, or manipulate the sequence of elements.
| Function | Purpose |
|-----------------------------------------------------------------------------------------------------------------|-----------------------------------------------------------------------------------------------------------------------------------------------------|
| [`crossWith()`](https://tginsberg.github.io/gatherers4j/gatherers/sequence-operations/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)`](https://tginsberg.github.io/gatherers4j/gatherers/sequence-operations/foldindexed/) | Perform a fold over the input stream where each element is included along with its zero-based index |
| [`interleaveWith()`](https://tginsberg.github.io/gatherers4j/gatherers/sequence-operations/interleavewith/) | Creates a stream of alternating objects from the input stream and the argument `iterable`, `iterator`, `stream`, or varargs |
| [`mapIndexed()`](https://tginsberg.github.io/gatherers4j/gatherers/sequence-operations/mapindexed/) | Perform a mapping operation given the element being mapped and its zero-based index. |
| [`orderByFrequency()`](https://tginsberg.github.io/gatherers4j/gatherers/sequence-operations/orderbyfrequency/) | Returns a stream where elements are ordered in either ascending or descending frequency contained in `WithCount` wrapper objects. |
| [`orderByFrequencyBy(fn)`](https://tginsberg.github.io/gatherers4j/gatherers/sequence-operations/orderbyfrequencyby/) | Returns a stream of mapped values ordered by frequency (ascending or descending) contained in `WithCount` wrapper objects. |
| [`peekIndexed()`](https://tginsberg.github.io/gatherers4j/gatherers/sequence-operations/peekindexed/) | Peek at each element of the stream along with its zero-based index |
| [`repeat(n)`](https://tginsberg.github.io/gatherers4j/gatherers/sequence-operations/repeat/) | Repeat the input stream `n` times to the output stream |
| [`repeatInfinitely()`](https://tginsberg.github.io/gatherers4j/gatherers/sequence-operations/repeatinfinitely/) | Repeat the input stream to the output stream forever (or until some downstream operation stops it) |
| [`reverse()`](https://tginsberg.github.io/gatherers4j/gatherers/sequence-operations/reverse/) | Reverse the order of the stream |
| [`rotate(direction, n)`](https://tginsberg.github.io/gatherers4j/gatherers/sequence-operations/rotate/) | Rotate the stream `n` elements to direction specified. Stores entire stream into memory. |
| [`scanIndexed(fn)`](https://tginsberg.github.io/gatherers4j/gatherers/sequence-operations/scanindexed/) | Performs a scan on the input stream using the given function, and includes the index of the elements |
| [`shuffle()`](https://tginsberg.github.io/gatherers4j/gatherers/sequence-operations/shuffle/) | Shuffle the stream into a random order, optionally taking a `RandomGenerator` |
| [`throttle(amount, duration)`](https://tginsberg.github.io/gatherers4j/gatherers/sequence-operations/throttle/) | Limit stream elements to `amount` elements over `duration`, pausing until a new `duration` period starts |
| [`withIndex()`](https://tginsberg.github.io/gatherers4j/gatherers/sequence-operations/withindex/) | Maps all elements of the stream as-is along with their 0-based index |
| [`zipWith()`](https://tginsberg.github.io/gatherers4j/gatherers/sequence-operations/zipwith/) | Creates a stream of `Pair` objects whose values come from the input stream and argument `iterable`, `iterator`, `stream`, or varargs |
| [`zipWithNext()`](https://tginsberg.github.io/gatherers4j/gatherers/sequence-operations/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)`](https://tginsberg.github.io/gatherers4j/gatherers/filtering-and-selection/debounce/) | Limit stream elements to `amount` elements over `duration`, dropping any elements over the limit until a new `duration` starts |
| [`dedupeConsecutive()`](https://tginsberg.github.io/gatherers4j/gatherers/filtering-and-selection/dedupeconsecutive/) | Remove consecutive duplicates from a stream |
| [`dedupeConsecutiveBy(fn)`](https://tginsberg.github.io/gatherers4j/gatherers/filtering-and-selection/dedupeconsecutiveby/) | Remove consecutive duplicates from a stream as returned by `fn` |
| [`distinctBy(fn)`](https://tginsberg.github.io/gatherers4j/gatherers/filtering-and-selection/distinctby/) | Emit only distinct elements from the stream, as measured by `fn` |
| [`dropEveryNth(n)`](https://tginsberg.github.io/gatherers4j/gatherers/filtering-and-selection/dropeverynth/) | Drop every`n`th element from the input stream |
| [`dropLast(n)`](https://tginsberg.github.io/gatherers4j/gatherers/filtering-and-selection/droplast/) | Keep all but the last `n` elements of the stream |
| [`filterIndexed()`](https://tginsberg.github.io/gatherers4j/gatherers/filtering-and-selection/filterindexed/) | Filter a stream according to a given predicate, which takes both the item being examined and its zero-based index. |
| [`filterInstanceOf`](https://tginsberg.github.io/gatherers4j/gatherers/filtering-and-selection/filterinstanceof/) | Filter the elements in the stream to only include elements of the given types. |
| [`filterOrdered(order)`](https://tginsberg.github.io/gatherers4j/gatherers/filtering-and-selection/filterordered/) | Filter the input stream of `Comparable` objects so that is strictly in the given `order` | |
| [`filterOrderedBy(order, comparator)`](https://tginsberg.github.io/gatherers4j/gatherers/filtering-and-selection/filterorderedby/) | Filter the input stream of objects so that it contains only elements in the given `order`, as measured by a given `Comparator` |
| [`sampleFixedSize(n)`](https://tginsberg.github.io/gatherers4j/gatherers/filtering-and-selection/samplefixedsize/) | Perform a fixed size sampling over the input stream. |
| [`samplePercentage(d)`](https://tginsberg.github.io/gatherers4j/gatherers/filtering-and-selection/samplepercentage/) | Perform a percentage-based sampling over the input stream. | |
| [`takeEveryNth(n)`](https://tginsberg.github.io/gatherers4j/gatherers/filtering-and-selection/takeeverynth/) | Keep every`n`th element from the input stream |
| [`takeLast(n)`](https://tginsberg.github.io/gatherers4j/gatherers/filtering-and-selection/takelast/) | Emit the last `n` values |
| [`takeUntil(predicate)`](https://tginsberg.github.io/gatherers4j/gatherers/filtering-and-selection/takeuntil/) | Take elements from the input stream until the `predicate` is met, including the first element that matches the `preciate` |
| [`uniquelyOccurring()`](https://tginsberg.github.io/gatherers4j/gatherers/filtering-and-selection/uniquelyoccurring/) | Emit elements that occur a single time, dropping all others |
| [`uniquelyOccurringBy(fn)`](https://tginsberg.github.io/gatherers4j/gatherers/filtering-and-selection/uniquelyoccurringby/) | Emit elements that occur a single time, as measured by `fn`, dropping all others |
## Grouping and Windowing
Functions that group input elements by varying criteria.
| Function | Purpose |
|---------------------------------------------------------------------------------------------------------------------------------|-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
| [`group()`](https://tginsberg.github.io/gatherers4j/gatherers/grouping-and-windowing/group/) | Group adjacent equal elements into lists |
| [`groupBy(fn)`](https://tginsberg.github.io/gatherers4j/gatherers/grouping-and-windowing/groupby/) | Group adjacent elements that are equal according to `fn` into lists |
| [`groupOrdered(order)`](https://tginsberg.github.io/gatherers4j/gatherers/grouping-and-windowing/groupordered/) | Group `Comparable` elements in the input stream to lists in the given order |
| [`groupOrderedBy(order, comparator)`](https://tginsberg.github.io/gatherers4j/gatherers/grouping-and-windowing/grouporderedby/) | Group elements in the given `order` as measured by a `Comparator` to lists |
| [`window()`](https://tginsberg.github.io/gatherers4j/gatherers/grouping-and-windowing/window/) | Create windows over the elements of the input stream that are `windowSize` in length, sliding over `stepping` number of elements and optionally including partial windows at the end of ths stream. |
## Validation and Constraints
Functions that enforce conditions on the stream.
| Function | Purpose |
|-------------------------------------------------------------------------------------------------------------------------------|----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
| [`ensureOrdered(orderType)`](https://tginsberg.github.io/gatherers4j/gatherers/validation-and-constraints/ensureordered/) | Ensure that the input stream of `Comparable` objects is ordered according to the `orderType` (increasing, decreasing, non-increasing, non-decreasing), and fail otherwise. | |
| [`ensureOrderedBy(orderType)`](https://tginsberg.github.io/gatherers4j/gatherers/validation-and-constraints/ensureorderedby/) | Ensure that the input stream of objects is ordered according to the `orderType` (increasing, decreasing, non-increasing, non-decreasing), as measured by a given `Comparator`, and fail otherwise. |
| [`ensureSize(sizeType, n)`](https://tginsberg.github.io/gatherers4j/gatherers/validation-and-constraints/ensuresize/) | Ensure the stream is `n` elements long with reference to `sizeType` (equals, less/greater than, less/greater than or equal to), and fail otherwise. |
## Mathematical Operations
Functions performing calculations over the stream.
| Function | Purpose |
|-------------------------------------------------------------------------------------------------------------------------------------------------------------|------------------------------------------------------------------------------------------------------------------------------------------------------------------|
| [`exponentialMovingAverageWithAlpha(alpha)`](https://tginsberg.github.io/gatherers4j/gatherers/mathematical/exponentialmovingaveragewithalpha/) | Create an exponential average of `BigDecimal` values, with the given `alpha`. |
| [`exponentialMovingAverageWithAlphaBy(alpha, fn)`](https://tginsberg.github.io/gatherers4j/gatherers/mathematical/exponentialmovingaveragewithalphaby/) | Create an exponential average of `BigDecimal` values with the given `alpha`, as mapped via `fn`. |
| [`exponentialMovingAverageWithPeriod(periods)`](https://tginsberg.github.io/gatherers4j/gatherers/mathematical/exponentialmovingaveragewithperiod/) | Create an exponential average of `BigDecimal` values, with the given number of `periods`. |
| [`exponentialMovingAverageWithPeriodBy(periods, fn)`](https://tginsberg.github.io/gatherers4j/gatherers/mathematical/exponentialmovingaveragewithperiodby/) | Create an exponential average of `BigDecimal` values with the given number of `periods`, as mapped via `fn`. |
| [`movingMax(window)`](https://tginsberg.github.io/gatherers4j/gatherers/mathematical/movingmax/) | Create a `Stream` representing the moving maximum over the previous `window` elements, where `T` implements `Comparable`. |
| [`movingMaxBy(window, comparator)`](https://tginsberg.github.io/gatherers4j/gatherers/mathematical/movingmaxby/) | Create a `Stream` representing the moving maximum over the previous `window` elements, according to the given `Comparator`. |
| [`movingMedian(window)`](https://tginsberg.github.io/gatherers4j/gatherers/mathematical/movingmedian/) | Create a Stream that represents the moving median of a `Stream` looking back `window` number of elements. |
| [`movingMedianBy(window, fn)`](https://tginsberg.github.io/gatherers4j/gatherers/mathematical/movingmedianby/) | Create a Stream that represents the moving median of `BigDecimal` objects mapped from a `Stream` via a `fn` and looking back `window` number of elements. |
| [`movingMin(window)`](https://tginsberg.github.io/gatherers4j/gatherers/mathematical/movingmin/) | Create a `Stream` representing the moving minimum over the previous `window` elements, where `T` implements `Comparable`. |
| [`movingMinBy(window, comparator)`](https://tginsberg.github.io/gatherers4j/gatherers/mathematical/movingminby/) | Create a `Stream` representing the moving minimum over the previous `window` elements, according to the given `Comparator`. |
| [`movingProduct(window)`](https://tginsberg.github.io/gatherers4j/gatherers/mathematical/movingproduct/) | Create a moving product of `BigDecimal` objects over the previous `window` values. |
| [`movingProductBy(window, fn)`](https://tginsberg.github.io/gatherers4j/gatherers/mathematical/movingproductby/) | Create a moving product of `BigDecimal` objects over the previous `window` values, as mapped via `fn`. |
| [`movingSum(window)`](https://tginsberg.github.io/gatherers4j/gatherers/mathematical/movingsum/) | Create a moving sum of `BigDecimal` objects over the previous `window` values. |
| [`movingSumBy(window, fn)`](https://tginsberg.github.io/gatherers4j/gatherers/mathematical/movingsumby/) | Create a moving sum of `BigDecimal` objects over the previous `window` values, as mapped via `fn`. |
| [`runningMax()`](https://tginsberg.github.io/gatherers4j/gatherers/mathematical/runningmax/) | Create a `Stream` representing the running maximum of the input stream, where `T` implements `Comparable`. |
| [`runningMaxBy(comparator)`](https://tginsberg.github.io/gatherers4j/gatherers/mathematical/runningmaxby/) | Create a `Stream` representing the running maximum of the input stream, according to the given `Comparator`. |
| [`runningMedian()`](https://tginsberg.github.io/gatherers4j/gatherers/mathematical/runningmedian/) | Create a `Stream` that represents the running median of a `Stream`. |
| [`runningMedianBy(fn)`](https://tginsberg.github.io/gatherers4j/gatherers/mathematical/runningmedianby/) | Create a `Stream` that represents the running median of `BigDecimal` objects mapped from a `Stream` via a `fn`. |
| [`runningMin()`](https://tginsberg.github.io/gatherers4j/gatherers/mathematical/runningmin/) | Create a `Stream` representing the running minimum of the input stream, where `T` implements `Comparable`. |
| [`runningMinBy(comparator)`](https://tginsberg.github.io/gatherers4j/gatherers/mathematical/runningminby/) | Create a `Stream` representing the running minimum of the input stream, according to the given `Comparator`. |
| [`runningPopulationStandardDeviation()`](https://tginsberg.github.io/gatherers4j/gatherers/mathematical/runningpopulationstandarddeviation/) | Create a stream of `BigDecimal` objects representing the running population standard deviation. |
| [`runningPopulationStandardDeviationBy(fn)`](https://tginsberg.github.io/gatherers4j/gatherers/mathematical/runningpopulationstandarddeviationby/) | Create a stream of `BigDecimal` objects as mapped from the input via `fn`, representing the running population standard deviation. |
| [`runningProduct()`](https://tginsberg.github.io/gatherers4j/gatherers/mathematical/runningproduct/) | Create a stream of `BigDecimal` objects representing the running product. | |
| [`runningProductBy(fn)`](https://tginsberg.github.io/gatherers4j/gatherers/mathematical/runningproductby/) | Create a stream of `BigDecimal` objects as mapped from the input via `fn`, representing the running product. |
| [`runningSampleStandardDeviation()`](https://tginsberg.github.io/gatherers4j/gatherers/mathematical/runningsamplestandarddeviation/) | Create a stream of `BigDecimal` objects representing the running sample standard deviation. |
| [`runningSampleStandardDeviationBy(fn)`](https://tginsberg.github.io/gatherers4j/gatherers/mathematical/runningsamplestandarddeviationby/) | Create a stream of `BigDecimal` objects as mapped from the input via `fn`, representing the running sample standard deviation. |
| [`runningSum()`](https://tginsberg.github.io/gatherers4j/gatherers/mathematical/runningsum/) | Create a stream of `BigDecimal` objects representing the running sum. |
| [`runningSumBy(fn)`](https://tginsberg.github.io/gatherers4j/gatherers/mathematical/runningsumby/) | Create a stream of `BigDecimal` objects as mapped from the input via `fn`, representing the running sum. |
| [`simpleMovingAverage(window)`](https://tginsberg.github.io/gatherers4j/gatherers/mathematical/simplemovingaverage/) | Create a moving average of `BigDecimal` values over the previous `window` values. |
| [`simpleMovingAverageBy(window, fn)`](https://tginsberg.github.io/gatherers4j/gatherers/mathematical/simplemovingaverageby/) | Create a moving average of `BigDecimal` values over the previous `window` values, as mapped via `fn`. |
| [`simpleRunningAverage()`](https://tginsberg.github.io/gatherers4j/gatherers/mathematical/simplerunningaverage/) | Create a running average of `BigDecimal` values. See below for options. |
| [`simpleRunningAverageBy(fn)`](https://tginsberg.github.io/gatherers4j/gatherers/mathematical/simplerunningaverageby/) | Create a running average of `BigDecimal` values as mapped via `fn`. |
# Contributing
Please feel free to file issues for change requests or bugs. If you would like to contribute new functionality, please
contact me before starting work!
Copyright © 2024-2025 by Todd Ginsberg