Added in [version 36.1](https://developer.android.com/topic/libraries/support-library/revisions) Summary: [Methods](https://developer.android.com/reference/java/util/stream/Gatherers#pubmethods) \| [Inherited Methods](https://developer.android.com/reference/java/util/stream/Gatherers#inhmethods)
# Gatherers
`
public
final
class
Gatherers
`
`
extends https://developer.android.com/reference/java/lang/Object
`
`
`
|---|---|
| [java.lang.Object](https://developer.android.com/reference/java/lang/Object) ||
| ↳ | java.util.stream.Gatherers |
*** ** * ** ***
Implementations of `https://developer.android.com/reference/java/util/stream/Gatherer` that provide useful intermediate
operations, such as windowing functions, folding functions,
transforming elements concurrently, etc.
## Summary
| ### Public methods ||
|---|---|
| ` static https://developer.android.com/reference/java/util/stream/Gatherer` | ` https://developer.android.com/reference/java/util/stream/Gatherers#fold(java.util.function.Supplier,%20java.util.function.BiFunction)(https://developer.android.com/reference/java/util/function/Supplier initial, https://developer.android.com/reference/java/util/function/BiFunction folder) ` Returns a Gatherer that performs an ordered, *reduction-like*, transformation for scenarios where no combiner-function can be implemented, or for reductions which are intrinsically order-dependent. |
| ` static https://developer.android.com/reference/java/util/stream/Gatherer` | ` https://developer.android.com/reference/java/util/stream/Gatherers#scan(java.util.function.Supplier,%20java.util.function.BiFunction)(https://developer.android.com/reference/java/util/function/Supplier initial, https://developer.android.com/reference/java/util/function/BiFunction scanner) ` Returns a Gatherer that performs a Prefix Scan -- an incremental accumulation -- using the provided functions. |
| ` static https://developer.android.com/reference/java/util/stream/Gatherer>` | ` https://developer.android.com/reference/java/util/stream/Gatherers#windowFixed(int)(int windowSize) ` Returns a Gatherer that gathers elements into windows -- encounter-ordered groups of elements -- of a fixed size. |
| ` static https://developer.android.com/reference/java/util/stream/Gatherer>` | ` https://developer.android.com/reference/java/util/stream/Gatherers#windowSliding(int)(int windowSize) ` Returns a Gatherer that gathers elements into windows -- encounter-ordered groups of elements -- of a given size, where each subsequent window includes all elements of the previous window except for the least recent, and adds the next element in the stream. |
| ### Inherited methods |
|---|---|
| From class ` https://developer.android.com/reference/java/lang/Object ` |---|---| | ` https://developer.android.com/reference/java/lang/Object` | ` https://developer.android.com/reference/java/lang/Object#clone()() ` Creates and returns a copy of this object. | | ` boolean` | ` https://developer.android.com/reference/java/lang/Object#equals(java.lang.Object)(https://developer.android.com/reference/java/lang/Object obj) ` Indicates whether some other object is "equal to" this one. | | ` void` | ` https://developer.android.com/reference/java/lang/Object#finalize()() ` Called by the garbage collector on an object when garbage collection determines that there are no more references to the object. | | ` final https://developer.android.com/reference/java/lang/Class` | ` https://developer.android.com/reference/java/lang/Object#getClass()() ` Returns the runtime class of this `Object`. | | ` int` | ` https://developer.android.com/reference/java/lang/Object#hashCode()() ` Returns a hash code value for the object. | | ` final void` | ` https://developer.android.com/reference/java/lang/Object#notify()() ` Wakes up a single thread that is waiting on this object's monitor. | | ` final void` | ` https://developer.android.com/reference/java/lang/Object#notifyAll()() ` Wakes up all threads that are waiting on this object's monitor. | | ` https://developer.android.com/reference/java/lang/String` | ` https://developer.android.com/reference/java/lang/Object#toString()() ` Returns a string representation of the object. | | ` final void` | ` https://developer.android.com/reference/java/lang/Object#wait(long,%20int)(long timeoutMillis, int nanos) ` Causes the current thread to wait until it is awakened, typically by being *notified* or *interrupted*, or until a certain amount of real time has elapsed. | | ` final void` | ` https://developer.android.com/reference/java/lang/Object#wait(long)(long timeoutMillis) ` Causes the current thread to wait until it is awakened, typically by being *notified* or *interrupted*, or until a certain amount of real time has elapsed. | | ` final void` | ` https://developer.android.com/reference/java/lang/Object#wait()() ` Causes the current thread to wait until it is awakened, typically by being *notified* or *interrupted*. | ||
## Public methods
### fold
Added in [version 36.1](https://developer.android.com/topic/libraries/support-library/revisions)
```
public static Gatherer fold (Supplier initial,
BiFunction folder)
```
Returns a Gatherer that performs an ordered, *reduction-like*,
transformation for scenarios where no combiner-function can be
implemented, or for reductions which are intrinsically
order-dependent.
##### Implementation Requirements:
- If no exceptions are thrown during processing, then this operation only ever produces a single element. Example:
`lang=java :
// will contain: Optional["123456789"]
Optional numberString =
Stream.of(1,2,3,4,5,6,7,8,9)
.gather(
Gatherers.fold(() -> "", (string, number) -> string + number)
)
.findFirst();
`
| Parameters ||
|---|---|
| `initial` | `Supplier`: the identity value for the fold operation
|
| `folder` | `BiFunction`: the folding function
|
| Returns ||
|---|---|
| `https://developer.android.com/reference/java/util/stream/Gatherer` | a new Gatherer
|
| Throws ||
|---|---|
| `https://developer.android.com/reference/java/lang/NullPointerException` | if any of the parameters are `null` |
**See also:**
- `https://developer.android.com/reference/java/util/stream/Stream#reduce(T,%20java.util.function.BinaryOperator)`
### scan
Added in [version 36.1](https://developer.android.com/topic/libraries/support-library/revisions)
```
public static Gatherer scan (Supplier initial,
BiFunction scanner)
```
Returns a Gatherer that performs a Prefix Scan -- an incremental
accumulation -- using the provided functions. Starting with an
initial value obtained from the `Supplier`, each subsequent
value is obtained by applying the `BiFunction` to the current
value and the next input element, after which the resulting value is
produced downstream.
Example:
`lang=java :
// will contain: ["1", "12", "123", "1234", "12345", "123456", "1234567", "12345678", "123456789"]
List numberStrings =
Stream.of(1,2,3,4,5,6,7,8,9)
.gather(
Gatherers.scan(() -> "", (string, number) -> string + number)
)
.toList();
`
| Parameters ||
|---|---|
| `initial` | `Supplier`: the supplier of the initial value for the scanner
|
| `scanner` | `BiFunction`: the function to apply for each element
|
| Returns ||
|---|---|
| `https://developer.android.com/reference/java/util/stream/Gatherer` | a new Gatherer which performs a prefix scan
|
| Throws ||
|---|---|
| `https://developer.android.com/reference/java/lang/NullPointerException` | if any of the parameters are `null` |
### windowFixed
Added in [version 36.1](https://developer.android.com/topic/libraries/support-library/revisions)
```
public static Gatherer> windowFixed (int windowSize)
```
Returns a Gatherer that gathers elements into windows
-- encounter-ordered groups of elements -- of a fixed size.
If the stream is empty then no window will be produced.
The last window may contain fewer elements than the supplied window size.
Example:
`lang=java :
// will contain: [[1, 2, 3], [4, 5, 6], [7, 8]]
List> windows =
Stream.of(1,2,3,4,5,6,7,8).gather(Gatherers.windowFixed(3)).toList();
`
##### API Note:
- For efficiency reasons, windows may be allocated contiguously and eagerly. This means that choosing large window sizes for small streams may use excessive memory for the duration of evaluation of this operation.
##### Implementation Requirements:
- Each window produced is an unmodifiable List; calls to any mutator method will always cause `UnsupportedOperationException` to be thrown. There are no guarantees on the implementation type or serializability of the produced Lists.
| Parameters ||
|---|---|
| `windowSize` | `int`: the size of the windows
|
| Returns ||
|---|---|
| `https://developer.android.com/reference/java/util/stream/Gatherer>` | a new gatherer which groups elements into fixed-size windows
|
| Throws ||
|---|---|
| `https://developer.android.com/reference/java/lang/IllegalArgumentException` | when `windowSize` is less than 1 |
### windowSliding
Added in [version 36.1](https://developer.android.com/topic/libraries/support-library/revisions)
```
public static Gatherer> windowSliding (int windowSize)
```
Returns a Gatherer that gathers elements into windows --
encounter-ordered groups of elements -- of a given size, where each
subsequent window includes all elements of the previous window except
for the least recent, and adds the next element in the stream.
If the stream is empty then no window will be produced. If the size of
the stream is smaller than the window size then only one window will
be produced, containing all elements in the stream.
Example:
`lang=java :
// will contain: [[1, 2], [2, 3], [3, 4], [4, 5], [5, 6], [6, 7], [7, 8]]
List> windows2 =
Stream.of(1,2,3,4,5,6,7,8).gather(Gatherers.windowSliding(2)).toList();
// will contain: [[1, 2, 3, 4, 5, 6], [2, 3, 4, 5, 6, 7], [3, 4, 5, 6, 7, 8]]
List> windows6 =
Stream.of(1,2,3,4,5,6,7,8).gather(Gatherers.windowSliding(6)).toList();
`
##### API Note:
- For efficiency reasons, windows may be allocated contiguously and eagerly. This means that choosing large window sizes for small streams may use excessive memory for the duration of evaluation of this operation.
##### Implementation Requirements:
- Each window produced is an unmodifiable List; calls to any mutator method will always cause `UnsupportedOperationException` to be thrown. There are no guarantees on the implementation type or serializability of the produced Lists.
| Parameters ||
|---|---|
| `windowSize` | `int`: the size of the windows
|
| Returns ||
|---|---|
| `https://developer.android.com/reference/java/util/stream/Gatherer>` | a new gatherer which groups elements into sliding windows
|
| Throws ||
|---|---|
| `https://developer.android.com/reference/java/lang/IllegalArgumentException` | when windowSize is less than 1 |