Uploaded image for project: 'JDK'
  1. JDK
  2. JDK-8245970

IntStream.html#reduce doc should not mention average

    Details

    • Type: CSR
    • Status: Closed
    • Priority: P4
    • Resolution: Withdrawn
    • Fix Version/s: 15
    • Component/s: core-libs
    • Labels:
      None
    • Subcomponent:
    • Compatibility Kind:
      behavioral
    • Compatibility Risk:
      minimal
    • Compatibility Risk Description:
      Java doc change only
    • Interface Kind:
      Java API
    • Scope:
      SE

      Description

      Summary

      The method-level 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 method-level documentation.

      Specification

      java.util.stream.IntStream

          /**
           * Performs a <a href="package-summary.html#Reduction">reduction</a> on the
           * elements of this stream, using the provided identity value and an
           * <a href="package-summary.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="package-summary.html#Associativity">associative</a> function.
           *
           * <p>This is a <a href="package-summary.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="package-summary.html#Associativity">associative</a>,
           *           <a href="package-summary.html#NonInterference">non-interfering</a>,
           *           <a href="package-summary.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

            Activity

              People

              • Assignee:
                jboes Julia Boes
                Reporter:
                webbuggrp Webbug Group
              • Votes:
                0 Vote for this issue
                Watchers:
                3 Start watching this issue

                Dates

                • Created:
                  Updated:
                  Resolved: