# Collector

public interface **Collector** A [mutable reduction operation](https://developers.google.com/j2objc/javadoc/jre/reference/java/util/stream/package-summary#Reduction) that
accumulates input elements into a mutable result container, optionally transforming
the accumulated result into a final representation after all input elements
have been processed. Reduction operations can be performed either sequentially
or in parallel.

Examples of mutable reduction operations include:
accumulating elements into a `Collection`; concatenating
strings using a `StringBuilder`; computing summary information about
elements such as sum, min, max, or average; computing "pivot table" summaries
such as "maximum valued transaction by seller", etc. The class `https://developers.google.com/j2objc/javadoc/jre/reference/java/util/stream/Collectors.html`
provides implementations of many common mutable reductions.

A `Collector` is specified by four functions that work together to
accumulate entries into a mutable result container, and optionally perform
a final transform on the result. They are:

- creation of a new result container (`https://developers.google.com/j2objc/javadoc/jre/reference/java/util/stream/Collector.html#supplier()`)
- incorporating a new data element into a result container (`https://developers.google.com/j2objc/javadoc/jre/reference/java/util/stream/Collector.html#accumulator()`)
- combining two result containers into one (`https://developers.google.com/j2objc/javadoc/jre/reference/java/util/stream/Collector.html#combiner()`)
- performing an optional final transform on the container (`https://developers.google.com/j2objc/javadoc/jre/reference/java/util/stream/Collector.html#finisher()`)

Collectors also have a set of characteristics, such as
`https://developers.google.com/j2objc/javadoc/jre/reference/java/util/stream/Collector.Characteristics.html#CONCURRENT`, that provide hints that can be used by a
reduction implementation to provide better performance.

A sequential implementation of a reduction using a collector would
create a single result container using the supplier function, and invoke the
accumulator function once for each input element. A parallel implementation
would partition the input, create a result container for each partition,
accumulate the contents of each partition into a subresult for that partition,
and then use the combiner function to merge the subresults into a combined
result.

To ensure that sequential and parallel executions produce equivalent
results, the collector functions must satisfy an *identity* and an
[associativity](https://developers.google.com/j2objc/javadoc/jre/reference/java/util/stream/package-summary#Associativity) constraints.

The identity constraint says that for any partially accumulated result,
combining it with an empty result container must produce an equivalent
result. That is, for a partially accumulated result `a` that is the
result of any series of accumulator and combiner invocations, `a` must
be equivalent to `combiner.apply(a, supplier.get())`.

The associativity constraint says that splitting the computation must
produce an equivalent result. That is, for any input elements `t1`
and `t2`, the results `r1` and `r2` in the computation
below must be equivalent:

    A a1 = supplier.get();
         accumulator.accept(a1, t1);
         accumulator.accept(a1, t2);
         R r1 = finisher.apply(a1);  // result without splitting

         A a2 = supplier.get();
         accumulator.accept(a2, t1);
         A a3 = supplier.get();
         accumulator.accept(a3, t2);
         R r2 = finisher.apply(combiner.apply(a2, a3));  // result with splitting
      
For collectors that do not have the `UNORDERED` characteristic,
two accumulated results `a1` and `a2` are equivalent if
`finisher.apply(a1).equals(finisher.apply(a2))`. For unordered
collectors, equivalence is relaxed to allow for non-equality related to
differences in order. (For example, an unordered collector that accumulated
elements to a `List` would consider two lists equivalent if they
contained the same elements, ignoring order.)

Libraries that implement reduction based on `Collector`, such as
`https://developers.google.com/j2objc/javadoc/jre/reference/java/util/stream/Stream.html#collect(java.util.stream.Collector<?%20super%20T,%20A,%20R>)`, must adhere to the following constraints:

- The first argument passed to the accumulator function, both arguments passed to the combiner function, and the argument passed to the finisher function must be the result of a previous invocation of the result supplier, accumulator, or combiner functions.
- The implementation should not do anything with the result of any of the result supplier, accumulator, or combiner functions other than to pass them again to the accumulator, combiner, or finisher functions, or return them to the caller of the reduction operation.
- If a result is passed to the combiner or finisher function, and the same object is not returned from that function, it is never used again.
- Once a result is passed to the combiner or finisher function, it is never passed to the accumulator function again.
- For non-concurrent collectors, any result returned from the result supplier, accumulator, or combiner functions must be serially thread-confined. This enables collection to occur in parallel without the `Collector` needing to implement any additional synchronization. The reduction implementation must manage that the input is properly partitioned, that partitions are processed in isolation, and combining happens only after accumulation is complete.
- For concurrent collectors, an implementation is free to (but not required to) implement reduction concurrently. A concurrent reduction is one where the accumulator function is called concurrently from multiple threads, using the same concurrently-modifiable result container, rather than keeping the result isolated during accumulation. A concurrent reduction should only be applied if the collector has the `https://developers.google.com/j2objc/javadoc/jre/reference/java/util/stream/Collector.Characteristics.html#UNORDERED` characteristics or if the originating data is unordered.

In addition to the predefined implementations in `https://developers.google.com/j2objc/javadoc/jre/reference/java/util/stream/Collectors.html`, the
static factory methods `https://developers.google.com/j2objc/javadoc/jre/reference/java/util/stream/Collector.html#of(java.util.function.Supplier<R>,%20java.util.function.BiConsumer<R,%20T>,%20java.util.function.BinaryOperator<R>,%20java.util.stream.Collector.Characteristics...)`
can be used to construct collectors. For example, you could create a collector
that accumulates widgets into a `TreeSet` with:

    Collector<Widget, ?, TreeSet<Widget>> intoSet =
             Collector.of(TreeSet::new, TreeSet::add,
                          (left, right) -> { left.addAll(right); return left; });
     
(This behavior is also implemented by the predefined collector `https://developers.google.com/j2objc/javadoc/jre/reference/java/util/stream/Collectors.html#toCollection(java.util.function.Supplier<C>)`).

<br />

##### See Also

- `https://developers.google.com/j2objc/javadoc/jre/reference/java/util/stream/Stream.html#collect(java.util.stream.Collector<?%20super%20T,%20A,%20R>)`
- `https://developers.google.com/j2objc/javadoc/jre/reference/java/util/stream/Collectors.html`

### Nested Class Summary

|---|---|---|---|
| enum | [Collector.Characteristics](https://developers.google.com/j2objc/javadoc/jre/reference/java/util/stream/Collector.Characteristics.html) || Characteristics indicating properties of a `Collector`, which can be used to optimize reduction implementations. |

### Public Method Summary

|---|---|
| abstract [BiConsumer](https://developers.google.com/j2objc/javadoc/jre/reference/java/util/function/BiConsumer.html)\<A, T\> | [accumulator](https://developers.google.com/j2objc/javadoc/jre/reference/java/util/stream/Collector.html#accumulator())() A function that folds a value into a mutable result container. |
| abstract [Set](https://developers.google.com/j2objc/javadoc/jre/reference/java/util/Set.html)\<[Collector.Characteristics](https://developers.google.com/j2objc/javadoc/jre/reference/java/util/stream/Collector.Characteristics.html)\> | [characteristics](https://developers.google.com/j2objc/javadoc/jre/reference/java/util/stream/Collector.html#characteristics())() Returns a `Set` of `Collector.Characteristics` indicating the characteristics of this Collector. |
| abstract [BinaryOperator](https://developers.google.com/j2objc/javadoc/jre/reference/java/util/function/BinaryOperator.html)\<A\> | [combiner](https://developers.google.com/j2objc/javadoc/jre/reference/java/util/stream/Collector.html#combiner())() A function that accepts two partial results and merges them. |
| abstract [Function](https://developers.google.com/j2objc/javadoc/jre/reference/java/util/function/Function.html)\<A, R\> | [finisher](https://developers.google.com/j2objc/javadoc/jre/reference/java/util/stream/Collector.html#finisher())() Perform the final transformation from the intermediate accumulation type `A` to the final result type `R`. |
| static \<T, A, R\> [Collector](https://developers.google.com/j2objc/javadoc/jre/reference/java/util/stream/Collector.html)\<T, A, R\> | [of](https://developers.google.com/j2objc/javadoc/jre/reference/java/util/stream/Collector.html#of(java.util.function.Supplier<A>,%20java.util.function.BiConsumer<A,%20T>,%20java.util.function.BinaryOperator<A>,%20java.util.function.Function<A,%20R>,%20java.util.stream.Collector.Characteristics...))([Supplier](https://developers.google.com/j2objc/javadoc/jre/reference/java/util/function/Supplier.html)\<A\> supplier, [BiConsumer](https://developers.google.com/j2objc/javadoc/jre/reference/java/util/function/BiConsumer.html)\<A, T\> accumulator, [BinaryOperator](https://developers.google.com/j2objc/javadoc/jre/reference/java/util/function/BinaryOperator.html)\<A\> combiner, [Function](https://developers.google.com/j2objc/javadoc/jre/reference/java/util/function/Function.html)\<A, R\> finisher, [Characteristics...](https://developers.google.com/j2objc/javadoc/jre/reference/java/util/stream/Collector.Characteristics.html) characteristics) Returns a new `Collector` described by the given `supplier`, `accumulator`, `combiner`, and `finisher` functions. |
| static \<T, R\> [Collector](https://developers.google.com/j2objc/javadoc/jre/reference/java/util/stream/Collector.html)\<T, R, R\> | [of](https://developers.google.com/j2objc/javadoc/jre/reference/java/util/stream/Collector.html#of(java.util.function.Supplier<R>,%20java.util.function.BiConsumer<R,%20T>,%20java.util.function.BinaryOperator<R>,%20java.util.stream.Collector.Characteristics...))([Supplier](https://developers.google.com/j2objc/javadoc/jre/reference/java/util/function/Supplier.html)\<R\> supplier, [BiConsumer](https://developers.google.com/j2objc/javadoc/jre/reference/java/util/function/BiConsumer.html)\<R, T\> accumulator, [BinaryOperator](https://developers.google.com/j2objc/javadoc/jre/reference/java/util/function/BinaryOperator.html)\<R\> combiner, [Characteristics...](https://developers.google.com/j2objc/javadoc/jre/reference/java/util/stream/Collector.Characteristics.html) characteristics) Returns a new `Collector` described by the given `supplier`, `accumulator`, and `combiner` functions. |
| abstract [Supplier](https://developers.google.com/j2objc/javadoc/jre/reference/java/util/function/Supplier.html)\<A\> | [supplier](https://developers.google.com/j2objc/javadoc/jre/reference/java/util/stream/Collector.html#supplier())() A function that creates and returns a new mutable result container. |

## Public Methods

#### public abstract [BiConsumer](https://developers.google.com/j2objc/javadoc/jre/reference/java/util/function/BiConsumer.html)\<A, T\>
**accumulator**
()

A function that folds a value into a mutable result container.

##### Returns

- a function which folds a value into a mutable result container

#### public abstract [Set](https://developers.google.com/j2objc/javadoc/jre/reference/java/util/Set.html)\<[Collector.Characteristics](https://developers.google.com/j2objc/javadoc/jre/reference/java/util/stream/Collector.Characteristics.html)\>
**characteristics**
()

Returns a `Set` of `Collector.Characteristics` indicating
the characteristics of this Collector. This set should be immutable.

##### Returns

- an immutable set of collector characteristics

#### public abstract [BinaryOperator](https://developers.google.com/j2objc/javadoc/jre/reference/java/util/function/BinaryOperator.html)\<A\>
**combiner**
()

A function that accepts two partial results and merges them. The
combiner function may fold state from one argument into the other and
return that, or may return a new result container.

##### Returns

- a function which combines two partial results into a combined result

#### public abstract [Function](https://developers.google.com/j2objc/javadoc/jre/reference/java/util/function/Function.html)\<A, R\>
**finisher**
()

Perform the final transformation from the intermediate accumulation type
`A` to the final result type `R`.

If the characteristic `IDENTITY_TRANSFORM` is
set, this function may be presumed to be an identity transform with an
unchecked cast from `A` to `R`.

##### Returns

- a function which transforms the intermediate result to the final result

#### public static [Collector](https://developers.google.com/j2objc/javadoc/jre/reference/java/util/stream/Collector.html)\<T, A, R\>
**of**
([Supplier](https://developers.google.com/j2objc/javadoc/jre/reference/java/util/function/Supplier.html)\<A\> supplier, [BiConsumer](https://developers.google.com/j2objc/javadoc/jre/reference/java/util/function/BiConsumer.html)\<A, T\> accumulator, [BinaryOperator](https://developers.google.com/j2objc/javadoc/jre/reference/java/util/function/BinaryOperator.html)\<A\> combiner, [Function](https://developers.google.com/j2objc/javadoc/jre/reference/java/util/function/Function.html)\<A, R\> finisher, [Characteristics...](https://developers.google.com/j2objc/javadoc/jre/reference/java/util/stream/Collector.Characteristics.html) characteristics)

Returns a new `Collector` described by the given `supplier`,
`accumulator`, `combiner`, and `finisher` functions.

##### Parameters

| supplier | The supplier function for the new collector |
| accumulator | The accumulator function for the new collector |
| combiner | The combiner function for the new collector |
| finisher | The finisher function for the new collector |
| characteristics | The collector characteristics for the new collector |
|---|---|

##### Returns

- the new `Collector`

##### Throws

| [NullPointerException](https://developers.google.com/j2objc/javadoc/jre/reference/java/lang/NullPointerException.html) | if any argument is null |
|---|---|

#### public static [Collector](https://developers.google.com/j2objc/javadoc/jre/reference/java/util/stream/Collector.html)\<T, R, R\>
**of**
([Supplier](https://developers.google.com/j2objc/javadoc/jre/reference/java/util/function/Supplier.html)\<R\> supplier, [BiConsumer](https://developers.google.com/j2objc/javadoc/jre/reference/java/util/function/BiConsumer.html)\<R, T\> accumulator, [BinaryOperator](https://developers.google.com/j2objc/javadoc/jre/reference/java/util/function/BinaryOperator.html)\<R\> combiner, [Characteristics...](https://developers.google.com/j2objc/javadoc/jre/reference/java/util/stream/Collector.Characteristics.html) characteristics)

Returns a new `Collector` described by the given `supplier`,
`accumulator`, and `combiner` functions. The resulting
`Collector` has the `Collector.Characteristics.IDENTITY_FINISH`
characteristic.

##### Parameters

| supplier | The supplier function for the new collector |
| accumulator | The accumulator function for the new collector |
| combiner | The combiner function for the new collector |
| characteristics | The collector characteristics for the new collector |
|---|---|

##### Returns

- the new `Collector`

##### Throws

| [NullPointerException](https://developers.google.com/j2objc/javadoc/jre/reference/java/lang/NullPointerException.html) | if any argument is null |
|---|---|

#### public abstract [Supplier](https://developers.google.com/j2objc/javadoc/jre/reference/java/util/function/Supplier.html)\<A\>
**supplier**
()

A function that creates and returns a new mutable result container.

##### Returns

- a function which returns a new, mutable result container