Details
Description
Summary
The methodlevel documentation of Intstream::reduce(int, IntBinaryOperator)
mentions the average function as a case of reduction even though the function cannot be used with the reduce method. This might cause confusion.
Problem
The @apiNote
of Intstream::reduce(int, IntBinaryOperator)
lists the average function as a special case of reduction and a @see
link points to the average function. However, it is not possible to use the average function with the reduce method as only an int
is allowed as intermediate result.
Solution
Remove the mentions of the average function in the @apiNote
and the @see
link of the methodlevel documentation.
Specification
java.util.stream.IntStream
/**
* Performs a <a href="packagesummary.html#Reduction">reduction</a> on the
* elements of this stream, using the provided identity value and an
* <a href="packagesummary.html#Associativity">associative</a>
* accumulation function, and returns the reduced value. This is equivalent
* to:
* <pre>{@code
* int result = identity;
* for (int element : this stream)
* result = accumulator.applyAsInt(result, element)
* return result;
* }</pre>
*
* but is not constrained to execute sequentially.
*
* <p>The {@code identity} value must be an identity for the accumulator
* function. This means that for all {@code x},
* {@code accumulator.apply(identity, x)} is equal to {@code x}.
* The {@code accumulator} function must be an
* <a href="packagesummary.html#Associativity">associative</a> function.
*
* <p>This is a <a href="packagesummary.html#StreamOps">terminal
* operation</a>.
*
 * @apiNote Sum, min, max, and average are all special cases of reduction.
+ * @apiNote Sum, min and max are all special cases of reduction.
* Summing a stream of numbers can be expressed as:
*
* <pre>{@code
* int sum = integers.reduce(0, (a, b) > a+b);
* }</pre>
*
* or more compactly:
*
* <pre>{@code
* int sum = integers.reduce(0, Integer::sum);
* }</pre>
*
* <p>While this may seem a more roundabout way to perform an aggregation
* compared to simply mutating a running total in a loop, reduction
* operations parallelize more gracefully, without needing additional
* synchronization and with greatly reduced risk of data races.
*
* @param identity the identity value for the accumulating function
* @param op an <a href="packagesummary.html#Associativity">associative</a>,
* <a href="packagesummary.html#NonInterference">noninterfering</a>,
* <a href="packagesummary.html#Statelessness">stateless</a>
* function for combining two values
* @return the result of the reduction
* @see #sum()
* @see #min()
* @see #max()
 * @see #average()
*/
int reduce(int identity, IntBinaryOperator op);
Attachments
Issue Links
 csr of

JDK8242281 IntStream.html#reduce doc should not mention average
 Closed