# HG changeset patch # User mduigou # Date 1374521752 25200 # Node ID 6ac8b7a3576b45e196e03691c6fb8157565be6dd # Parent a3a2889b1049acccf2972fbae032fca8478ded07 8019840: Spec updates for java.util.function Reviewed-by: mduigou Contributed-by: brian.goetz@oracle.com diff --git a/src/share/classes/java/util/function/BiConsumer.java b/src/share/classes/java/util/function/BiConsumer.java --- a/src/share/classes/java/util/function/BiConsumer.java +++ b/src/share/classes/java/util/function/BiConsumer.java @@ -27,13 +27,16 @@ import java.util.Objects; /** - * An operation which accepts two input arguments and returns no result. This is - * the two-arity specialization of {@link Consumer}. Unlike most other - * functional interfaces, {@code BiConsumer} is expected to operate via - * side-effects. + * Represents an operation that accepts two input arguments and returns no + * result. This is the two-arity specialization of {@link Consumer}. + * Unlike most other functional interfaces, {@code BiConsumer} is expected + * to operate via side-effects. * - * @param the type of the first argument to the {@code accept} operation - * @param the type of the second argument to the {@code accept} operation + *

This is a functional interface + * whose functional method is {@link #accept(Object, Object)}. + * + * @param the type of the first argument to the operation + * @param the type of the second argument to the operation * * @see Consumer * @since 1.8 @@ -42,35 +45,31 @@ public interface BiConsumer { /** - * Performs operations upon the provided objects which may modify those - * objects and/or external state. + * Performs this operation on the given arguments. * - * @param t an input object - * @param u an input object + * @param t the first input argument + * @param u the second input argument */ void accept(T t, U u); /** - * Returns a {@code BiConsumer} which performs, in sequence, the operation - * represented by this object followed by the operation represented by - * the other {@code BiConsumer}. + * Returns a composed {@code BiConsumer} that performs, in sequence, this + * operation followed by the {@code after} operation. If performing either + * operation throws an exception, it is relayed to the caller of the + * composed operation. If performing this operation throws an exception, + * the {@code after} operation will not be performed. * - *

Any exceptions thrown by either {@code accept} method are relayed - * to the caller; if performing this operation throws an exception, the - * other operation will not be performed. - * - * @param other a BiConsumer which will be chained after this BiConsumer - * @return a BiConsumer which performs in sequence the {@code accept} method - * of this BiConsumer and the {@code accept} method of the specified - * BiConsumer operation - * @throws NullPointerException if other is null + * @param after the operation to perform after this operation + * @return a composed {@code BiConsumer} that performs in sequence this + * operation followed by the {@code after} operation + * @throws NullPointerException if {@code after} is null */ - default BiConsumer chain(BiConsumer other) { - Objects.requireNonNull(other); + default BiConsumer andThen(BiConsumer after) { + Objects.requireNonNull(after); return (l, r) -> { accept(l, r); - other.accept(l, r); + after.accept(l, r); }; } } diff --git a/src/share/classes/java/util/function/BiFunction.java b/src/share/classes/java/util/function/BiFunction.java --- a/src/share/classes/java/util/function/BiFunction.java +++ b/src/share/classes/java/util/function/BiFunction.java @@ -27,14 +27,15 @@ import java.util.Objects; /** - * Apply a function to the input arguments, yielding an appropriate result. This - * is the two-arity specialization of {@link Function}. A function may - * variously provide a mapping between types, object instances or keys and - * values or any other form of transformation upon the input. + * Represents a function that accepts two arguments and produces a result. + * This is the two-arity specialization of {@link Function}. * - * @param the type of the first argument to the {@code apply} operation - * @param the type of the second argument to the {@code apply} operation - * @param the type of results returned by the {@code apply} operation + *

This is a functional interface + * whose functional method is {@link #apply(Object, Object)}. + * + * @param the type of the first argument to the function + * @param the type of the second argument to the function + * @param the type of the result of the function * * @see Function * @since 1.8 @@ -43,25 +44,25 @@ public interface BiFunction { /** - * Compute the result of applying the function to the input arguments + * Applies this function to the given arguments. * - * @param t an input object - * @param u an input object + * @param t the first function argument + * @param u the second function argument * @return the function result */ R apply(T t, U u); /** - * Returns a new function which applies this function followed by the - * provided function. If either function throws an exception, it is relayed - * to the caller. + * Returns a composed function that first applies this function to + * its input, and then applies the {@code after} function to the result. + * If evaluation of either function throws an exception, it is relayed to + * the caller of the composed function. * - * @param Type of output objects to the combined function. May be the - * same type as {@code }, {@code } or {@code } - * @param after An additional function to be applied after this function is - * applied - * @return A function which performs this function followed by the provided - * function + * @param the type of output of the {@code after} function, and of the + * composed function + * @param after the function to apply after this function is applied + * @return a composed function that first applies this function and then + * applies the {@code after} function * @throws NullPointerException if after is null */ default BiFunction andThen(Function after) { diff --git a/src/share/classes/java/util/function/BiPredicate.java b/src/share/classes/java/util/function/BiPredicate.java --- a/src/share/classes/java/util/function/BiPredicate.java +++ b/src/share/classes/java/util/function/BiPredicate.java @@ -27,11 +27,14 @@ import java.util.Objects; /** - * Determines if the input objects match some criteria. This is the two-arity - * specialization of {@link Predicate}. + * Represents a predicate (boolean-valued function) of two arguments. This is + * the two-arity specialization of {@link Predicate}. * - * @param the type of the first argument to {@code test} - * @param the type of the second argument to {@code test} + *

This is a functional interface + * whose functional method is {@link #test(Object, Object)}. + * + * @param the type of the first argument to the predicate + * @param the type of the second argument the predicate * * @see Predicate * @since 1.8 @@ -40,34 +43,41 @@ public interface BiPredicate { /** - * Return {@code true} if the inputs match some criteria. + * Evaluates this predicate on the given arguments. * - * @param t an input object - * @param u an input object - * @return {@code true} if the inputs match some criteria + * @param t the first input argument + * @param u the second input argument + * @return {@code true} if the input arguments match the predicate, + * otherwise {@code false} */ boolean test(T t, U u); /** - * Returns a predicate which evaluates to {@code true} only if this - * predicate and the provided predicate both evaluate to {@code true}. If - * this predicate returns {@code false} then the remaining predicate is not - * evaluated. + * Returns a composed predicate that represents a short-circuiting logical + * AND of this predicate and another. When evaluating the composed + * predicate, if this predicate is {@code false}, then the {@code other} + * predicate is not evaluated. * - * @param p a predicate which will be logically-ANDed with this predicate - * @return a new predicate which returns {@code true} only if both - * predicates return {@code true} - * @throws NullPointerException if p is null + *

Any exceptions thrown during evaluation of either predicate are relayed + * to the caller; if evaluation of this predicate throws an exception, the + * {@code other} predicate will not be evaluated. + * + * @param other a predicate that will be logically-ANDed with this + * predicate + * @return a composed predicate that represents the short-circuiting logical + * AND of this predicate and the {@code other} predicate + * @throws NullPointerException if other is null */ - default BiPredicate and(BiPredicate p) { - Objects.requireNonNull(p); - return (T t, U u) -> test(t, u) && p.test(t, u); + default BiPredicate and(BiPredicate other) { + Objects.requireNonNull(other); + return (T t, U u) -> test(t, u) && other.test(t, u); } /** - * Returns a predicate which negates the result of this predicate. + * Returns a predicate that represents the logical negation of this + * predicate. * - * @return a new predicate who's result is always the opposite of this + * @return a predicate that represents the logical negation of this * predicate */ default BiPredicate negate() { @@ -75,18 +85,23 @@ } /** - * Returns a predicate which evaluates to {@code true} if either this - * predicate or the provided predicate evaluates to {@code true}. If this - * predicate returns {@code true} then the remaining predicate is not - * evaluated. + * Returns a composed predicate that represents a short-circuiting logical + * OR of this predicate and another. When evaluating the composed + * predicate, if this predicate is {@code true}, then the {@code other} + * predicate is not evaluated. * - * @param p a predicate which will be logically-ORed with this predicate - * @return a new predicate which returns {@code true} if either predicate - * returns {@code true} - * @throws NullPointerException if p is null + *

Any exceptions thrown during evaluation of either predicate are relayed + * to the caller; if evaluation of this predicate throws an exception, the + * {@code other} predicate will not be evaluated. + * + * @param other a predicate that will be logically-ORed with this + * predicate + * @return a composed predicate that represents the short-circuiting logical + * OR of this predicate and the {@code other} predicate + * @throws NullPointerException if other is null */ - default BiPredicate or(BiPredicate p) { - Objects.requireNonNull(p); - return (T t, U u) -> test(t, u) || p.test(t, u); + default BiPredicate or(BiPredicate other) { + Objects.requireNonNull(other); + return (T t, U u) -> test(t, u) || other.test(t, u); } } diff --git a/src/share/classes/java/util/function/BinaryOperator.java b/src/share/classes/java/util/function/BinaryOperator.java --- a/src/share/classes/java/util/function/BinaryOperator.java +++ b/src/share/classes/java/util/function/BinaryOperator.java @@ -28,42 +28,48 @@ import java.util.Comparator; /** - * An operation upon two operands yielding a result. This is a specialization of - * {@code BiFunction} where the operands and the result are all of the same type. + * Represents an operation upon two operands of the same type, producing a result + * of the same type as the operands. This is a specialization of + * {@link BiFunction} for the case where the operands and the result are all of + * the same type. * - * @param the type of operands to {@code apply} and of the result + *

This is a functional interface + * whose functional method is {@link #apply(Object, Object)}. + * + * @param the type of the operands and result of the operator * * @see BiFunction + * @see UnaryOperator * @since 1.8 */ @FunctionalInterface public interface BinaryOperator extends BiFunction { /** * Returns a {@link BinaryOperator} which returns the lesser of two elements - * according to the specified {@code Comparator} + * according to the specified {@code Comparator}. * - * @param the type of values to be compared and returned - * @param comparator a {@code Comparator} for comparing the two values + * @param the type of the input arguments of the comparator + * @param comparator a {@code Comparator} for comparing the two values * @return a {@code BinaryOperator} which returns the lesser of its operands, * according to the supplied {@code Comparator} * @throws NullPointerException if the argument is null */ - public static BinaryOperator minBy(Comparator comparator) { + public static BinaryOperator minBy(Comparator comparator) { Objects.requireNonNull(comparator); return (a, b) -> comparator.compare(a, b) <= 0 ? a : b; } /** * Returns a {@link BinaryOperator} which returns the greater of two elements - * according to the specified {@code Comparator} + * according to the specified {@code Comparator}. * - * @param the type of values to be compared and returned - * @param comparator a {@code Comparator} for comparing the two values + * @param the type of the input arguments of the comparator + * @param comparator a {@code Comparator} for comparing the two values * @return a {@code BinaryOperator} which returns the greater of its operands, * according to the supplied {@code Comparator} * @throws NullPointerException if the argument is null */ - public static BinaryOperator maxBy(Comparator comparator) { + public static BinaryOperator maxBy(Comparator comparator) { Objects.requireNonNull(comparator); return (a, b) -> comparator.compare(a, b) >= 0 ? a : b; } diff --git a/src/share/classes/java/util/function/BooleanSupplier.java b/src/share/classes/java/util/function/BooleanSupplier.java --- a/src/share/classes/java/util/function/BooleanSupplier.java +++ b/src/share/classes/java/util/function/BooleanSupplier.java @@ -26,8 +26,14 @@ /** - * A supplier of {@code boolean} values. This is the {@code boolean}-providing - * primitive specialization of {@link Supplier}. + * Represents a supplier of {@code boolean}-valued results. This is the + * {@code boolean}-producing primitive specialization of {@link Supplier}. + * + *

There is no requirement that a new or distinct result be returned each + * time the supplier is invoked. + * + *

This is a functional interface + * whose functional method is {@link #getAsBoolean()}. * * @see Supplier * @since 1.8 @@ -36,9 +42,9 @@ public interface BooleanSupplier { /** - * Returns a {@code boolean} value. + * Gets a result. * - * @return a {@code boolean} value + * @return a result */ boolean getAsBoolean(); } diff --git a/src/share/classes/java/util/function/Consumer.java b/src/share/classes/java/util/function/Consumer.java --- a/src/share/classes/java/util/function/Consumer.java +++ b/src/share/classes/java/util/function/Consumer.java @@ -27,11 +27,14 @@ import java.util.Objects; /** - * An operation which accepts a single input argument and returns no result. - * Unlike most other functional interfaces, {@code Consumer} is expected to - * operate via side-effects. + * Represents an operation that accepts a single input argument and returns no + * result. Unlike most other functional interfaces, {@code Consumer} is expected + * to operate via side-effects. * - * @param The type of input objects to {@code accept} + *

This is a functional interface + * whose functional method is {@link #accept(Object)}. + * + * @param the type of the input to the operation * * @since 1.8 */ @@ -39,29 +42,26 @@ public interface Consumer { /** - * Accept an input value. + * Performs this operation on the given argument. * - * @param t the input object + * @param t the input argument */ void accept(T t); /** - * Returns a {@code Consumer} which performs, in sequence, the operation - * represented by this object followed by the operation represented by - * the other {@code Consumer}. + * Returns a composed {@code Consumer} that performs, in sequence, this + * operation followed by the {@code after} operation. If performing either + * operation throws an exception, it is relayed to the caller of the + * composed operation. If performing this operation throws an exception, + * the {@code after} operation will not be performed. * - *

Any exceptions thrown by either {@code accept} method are relayed - * to the caller; if performing this operation throws an exception, the - * other operation will not be performed. - * - * @param other a Consumer which will be chained after this Consumer - * @return a Consumer which performs in sequence the {@code accept} method - * of this Consumer and the {@code accept} method of the specified Consumer - * operation - * @throws NullPointerException if other is null + * @param after the operation to perform after this operation + * @return a composed {@code Consumer} that performs in sequence this + * operation followed by the {@code after} operation + * @throws NullPointerException if {@code after} is null */ - default Consumer chain(Consumer other) { - Objects.requireNonNull(other); - return (T t) -> { accept(t); other.accept(t); }; + default Consumer andThen(Consumer after) { + Objects.requireNonNull(after); + return (T t) -> { accept(t); after.accept(t); }; } } diff --git a/src/share/classes/java/util/function/DoubleBinaryOperator.java b/src/share/classes/java/util/function/DoubleBinaryOperator.java --- a/src/share/classes/java/util/function/DoubleBinaryOperator.java +++ b/src/share/classes/java/util/function/DoubleBinaryOperator.java @@ -25,23 +25,25 @@ package java.util.function; /** - * An operation on two {@code double} operands yielding a {@code double} result. - * This is the primitive type specialization of {@link BinaryOperator} for - * {@code double}. + * Represents an operation upon two {@code double}-valued operands and producing a + * {@code double}-valued result. This is the primitive type specialization of + * {@link BinaryOperator} for {@code double}. + * + *

This is a functional interface + * whose functional method is {@link #applyAsDouble(double, double)}. * * @see BinaryOperator + * @see DoubleUnaryOperator * @since 1.8 */ @FunctionalInterface public interface DoubleBinaryOperator { /** - * Returns the {@code double} result of the operation upon the - * {@code double} operands. The parameters are named {@code left} and - * {@code right} for operations where the order of parameters matters. + * Applies this operator to the given operands. * - * @param left the left operand value - * @param right the right operand value - * @return the result of the operation + * @param left the first operand + * @param right the second operand + * @return the operator result */ double applyAsDouble(double left, double right); } diff --git a/src/share/classes/java/util/function/DoubleConsumer.java b/src/share/classes/java/util/function/DoubleConsumer.java --- a/src/share/classes/java/util/function/DoubleConsumer.java +++ b/src/share/classes/java/util/function/DoubleConsumer.java @@ -27,11 +27,14 @@ import java.util.Objects; /** - * An operation which accepts a single double argument and returns no result. - * This is the primitive type specialization of {@link Consumer} for - * {@code double}. Unlike most other functional interfaces, + * Represents an operation that accepts a single {@code double}-valued argument and + * returns no result. This is the primitive type specialization of + * {@link Consumer} for {@code double}. Unlike most other functional interfaces, * {@code DoubleConsumer} is expected to operate via side-effects. * + *

This is a functional interface + * whose functional method is {@link #accept(double)}. + * * @see Consumer * @since 1.8 */ @@ -39,30 +42,26 @@ public interface DoubleConsumer { /** - * Accept an input value. + * Performs this operation on the given argument. * - * @param value the input value + * @param value the input argument */ void accept(double value); /** - * Returns a {@code DoubleConsumer} which performs, in sequence, the operation - * represented by this object followed by the operation represented by - * another {@code DoubleConsumer}. + * Returns a composed {@code DoubleConsumer} that performs, in sequence, this + * operation followed by the {@code after} operation. If performing either + * operation throws an exception, it is relayed to the caller of the + * composed operation. If performing this operation throws an exception, + * the {@code after} operation will not be performed. * - *

Any exceptions thrown by either {@code accept} method are relayed - * to the caller; if performing this operation throws an exception, the - * other operation will not be performed. - * - * @param other a DoubleConsumer which will be chained after this - * DoubleConsumer - * @return an DoubleConsumer which performs in sequence the {@code accept} method - * of this DoubleConsumer and the {@code accept} method of the specified IntConsumer - * operation - * @throws NullPointerException if other is null + * @param after the operation to perform after this operation + * @return a composed {@code DoubleConsumer} that performs in sequence this + * operation followed by the {@code after} operation + * @throws NullPointerException if {@code after} is null */ - default DoubleConsumer chain(DoubleConsumer other) { - Objects.requireNonNull(other); - return (double t) -> { accept(t); other.accept(t); }; + default DoubleConsumer andThen(DoubleConsumer after) { + Objects.requireNonNull(after); + return (double t) -> { accept(t); after.accept(t); }; } } diff --git a/src/share/classes/java/util/function/DoubleFunction.java b/src/share/classes/java/util/function/DoubleFunction.java --- a/src/share/classes/java/util/function/DoubleFunction.java +++ b/src/share/classes/java/util/function/DoubleFunction.java @@ -25,11 +25,14 @@ package java.util.function; /** - * Apply a function to the double-valued input argument, yielding an appropriate - * result. This is the {@code double}-consuming primitive specialization for + * Represents a function that accepts a double-valued argument and produces a + * result. This is the {@code double}-consuming primitive specialization for * {@link Function}. * - * @param the type of output objects from the function + *

This is a functional interface + * whose functional method is {@link #apply(double)}. + * + * @param the type of the result of the function * * @see Function * @since 1.8 @@ -38,9 +41,9 @@ public interface DoubleFunction { /** - * Compute the result of applying the function to the input argument + * Applies this function to the given argument. * - * @param value the input value + * @param value the function argument * @return the function result */ R apply(double value); diff --git a/src/share/classes/java/util/function/DoublePredicate.java b/src/share/classes/java/util/function/DoublePredicate.java --- a/src/share/classes/java/util/function/DoublePredicate.java +++ b/src/share/classes/java/util/function/DoublePredicate.java @@ -27,9 +27,12 @@ import java.util.Objects; /** - * Determines if the {@code double} input value matches some criteria. This is - * the {@code double}-consuming primitive type specialization of - * {@link Predicate}. + * Represents a predicate (boolean-valued function) of one {@code double}-valued + * argument. This is the {@code double}-consuming primitive type specialization + * of {@link Predicate}. + * + *

This is a functional interface + * whose functional method is {@link #test(double)}. * * @see Predicate * @since 1.8 @@ -38,38 +41,40 @@ public interface DoublePredicate { /** - * Returns {@code true} if the input value matches some criteria. + * Evaluates this predicate on the given argument. * - * @param value the value to be tested - * @return {@code true} if the input value matches some criteria, otherwise - * {@code false} + * @param value the input argument + * @return {@code true} if the input argument matches the predicate, + * otherwise {@code false} */ boolean test(double value); /** - * Returns a predicate which evaluates to {@code true} only if this - * predicate and the provided predicate both evaluate to {@code true}. If - * this predicate returns {@code false} then the remaining predicate is not - * evaluated. + * Returns a composed predicate that represents a short-circuiting logical + * AND of this predicate and another. When evaluating the composed + * predicate, if this predicate is {@code false}, then the {@code other} + * predicate is not evaluated. * - *

Any exceptions thrown by either {@code test} method are relayed - * to the caller; if performing first operation throws an exception, the - * second operation will not be performed. + *

Any exceptions thrown during evaluation of either predicate are relayed + * to the caller; if evaluation of this predicate throws an exception, the + * {@code other} predicate will not be evaluated. * - * @param p a predicate which will be logically-ANDed with this predicate - * @return a new predicate which returns {@code true} only if both - * predicates return {@code true} - * @throws NullPointerException if p is null + * @param other a predicate that will be logically-ANDed with this + * predicate + * @return a composed predicate that represents the short-circuiting logical + * AND of this predicate and the {@code other} predicate + * @throws NullPointerException if other is null */ - default DoublePredicate and(DoublePredicate p) { - Objects.requireNonNull(p); - return (value) -> test(value) && p.test(value); + default DoublePredicate and(DoublePredicate other) { + Objects.requireNonNull(other); + return (value) -> test(value) && other.test(value); } /** - * Returns a predicate which negates the result of this predicate. + * Returns a predicate that represents the logical negation of this + * predicate. * - * @return a new predicate who's result is always the opposite of this + * @return a predicate that represents the logical negation of this * predicate */ default DoublePredicate negate() { @@ -77,22 +82,23 @@ } /** - * Returns a predicate which evaluates to {@code true} if either this - * predicate or the provided predicate evaluates to {@code true}. If this - * predicate returns {@code true} then the remaining predicate is not - * evaluated. + * Returns a composed predicate that represents a short-circuiting logical + * OR of this predicate and another. When evaluating the composed + * predicate, if this predicate is {@code true}, then the {@code other} + * predicate is not evaluated. * - *

Any exceptions thrown by either {@code test} method are relayed - * to the caller; if performing first operation throws an exception, the - * second operation will not be performed. + *

Any exceptions thrown during evaluation of either predicate are relayed + * to the caller; if evaluation of this predicate throws an exception, the + * {@code other} predicate will not be evaluated. * - * @param p a predicate which will be logically-ANDed with this predicate - * @return a new predicate which returns {@code true} if either predicate - * returns {@code true} - * @throws NullPointerException if p is null + * @param other a predicate that will be logically-ORed with this + * predicate + * @return a composed predicate that represents the short-circuiting logical + * OR of this predicate and the {@code other} predicate + * @throws NullPointerException if other is null */ - default DoublePredicate or(DoublePredicate p) { - Objects.requireNonNull(p); - return (value) -> test(value) || p.test(value); + default DoublePredicate or(DoublePredicate other) { + Objects.requireNonNull(other); + return (value) -> test(value) || other.test(value); } } diff --git a/src/share/classes/java/util/function/DoubleSupplier.java b/src/share/classes/java/util/function/DoubleSupplier.java --- a/src/share/classes/java/util/function/DoubleSupplier.java +++ b/src/share/classes/java/util/function/DoubleSupplier.java @@ -25,8 +25,14 @@ package java.util.function; /** - * A supplier of {@code double} values. This is the {@code double}-providing - * primitive specialization of {@link Supplier}. + * Represents a supplier of {@code double}-valued results. This is the + * {@code double}-producing primitive specialization of {@link Supplier}. + * + *

There is no requirement that a distinct result be returned each + * time the supplier is invoked. + * + *

This is a functional interface + * whose functional method is {@link #getAsDouble()}. * * @see Supplier * @since 1.8 @@ -35,9 +41,9 @@ public interface DoubleSupplier { /** - * Returns a {@code double} value. + * Gets a result. * - * @return a {@code double} value + * @return a result */ double getAsDouble(); } diff --git a/src/share/classes/java/util/function/DoubleToIntFunction.java b/src/share/classes/java/util/function/DoubleToIntFunction.java --- a/src/share/classes/java/util/function/DoubleToIntFunction.java +++ b/src/share/classes/java/util/function/DoubleToIntFunction.java @@ -25,22 +25,24 @@ package java.util.function; /** - * Apply a function to the input argument, yielding an appropriate result. - * This is the {@code double}-to-{@code int} specialization for {@link Function}. + * Represents a function that accepts a double-valued argument and produces an + * int-valued result. This is the {@code double}-to-{@code int} primitive + * specialization for {@link Function}. + * + *

This is a functional interface + * whose functional method is {@link #applyAsInt(double)}. * * @see Function - * @see IntToDoubleFunction - * @see LongToIntFunction * @since 1.8 */ @FunctionalInterface public interface DoubleToIntFunction { /** - * Compute the result of applying the function to the input arguments. + * Applies this function to the given argument. * - * @param value the input value - * @return the function result value + * @param value the function argument + * @return the function result */ int applyAsInt(double value); } diff --git a/src/share/classes/java/util/function/DoubleToLongFunction.java b/src/share/classes/java/util/function/DoubleToLongFunction.java --- a/src/share/classes/java/util/function/DoubleToLongFunction.java +++ b/src/share/classes/java/util/function/DoubleToLongFunction.java @@ -25,22 +25,24 @@ package java.util.function; /** - * Apply a function to the input argument, yielding an appropriate result. - * This is the {@code double}-to-{@code long} specialization for {@link Function}. + * Represents a function that accepts a double-valued argument and produces a + * long-valued result. This is the {@code double}-to-{@code long} primitive + * specialization for {@link Function}. + * + *

This is a functional interface + * whose functional method is {@link #applyAsLong(double)}. * * @see Function - * @see LongToDoubleFunction - * @see IntToLongFunction * @since 1.8 */ @FunctionalInterface public interface DoubleToLongFunction { /** - * Compute the result of applying the function to the input arguments. + * Applies this function to the given argument. * - * @param value the input value - * @return the function result value + * @param value the function argument + * @return the function result */ long applyAsLong(double value); } diff --git a/src/share/classes/java/util/function/DoubleUnaryOperator.java b/src/share/classes/java/util/function/DoubleUnaryOperator.java --- a/src/share/classes/java/util/function/DoubleUnaryOperator.java +++ b/src/share/classes/java/util/function/DoubleUnaryOperator.java @@ -27,9 +27,12 @@ import java.util.Objects; /** - * An operation on a {@code double} operand yielding a {@code double} - * result. This is the primitive type specialization of {@link UnaryOperator} - * for {@code double}. + * Represents an operation on a single {@code double}-valued operand that produces + * a {@code double}-valued result. This is the primitive type specialization of + * {@link UnaryOperator} for {@code double}. + * + *

This is a functional interface + * whose functional method is {@link #applyAsDouble(double)}. * * @see UnaryOperator * @since 1.8 @@ -38,24 +41,25 @@ public interface DoubleUnaryOperator { /** - * Returns the {@code double} result of the operation upon the - * {@code double} operand. + * Applies this operator to the given operand. * - * @param operand the operand value - * @return the operation result value + * @param operand the operand + * @return the operator result */ double applyAsDouble(double operand); /** - * Compose a new function which applies the provided function followed by - * this function. If either function throws an exception, it is relayed - * to the caller. + * Returns a composed operator that first applies the {@code before} + * operator to its input, and then applies this operator to the result. + * If evaluation of either operator throws an exception, it is relayed to + * the caller of the composed operator. * - * @param before An additional function to be applied before this function - * is applied - * @return A function which performs the provided function followed by this - * function + * @param before the operator to apply before this operator is applied + * @return a composed operator that first applies the {@code before} + * operator and then applies this operator * @throws NullPointerException if before is null + * + * @see #andThen(DoubleUnaryOperator) */ default DoubleUnaryOperator compose(DoubleUnaryOperator before) { Objects.requireNonNull(before); @@ -63,15 +67,17 @@ } /** - * Compose a new function which applies this function followed by the - * provided function. If either function throws an exception, it is relayed - * to the caller. + * Returns a composed operator that first applies this operator to + * its input, and then applies the {@code after} operator to the result. + * If evaluation of either operator throws an exception, it is relayed to + * the caller of the composed operator. * - * @param after An additional function to be applied after this function is - * applied - * @return A function which performs this function followed by the provided - * function followed + * @param after the operator to apply after this operator is applied + * @return a composed operator that first applies this operator and then + * applies the {@code after} operator * @throws NullPointerException if after is null + * + * @see #compose(DoubleUnaryOperator) */ default DoubleUnaryOperator andThen(DoubleUnaryOperator after) { Objects.requireNonNull(after); @@ -79,9 +85,9 @@ } /** - * Returns a unary operator that provides its input value as the result. + * Returns a unary operator that always returns its input argument. * - * @return a unary operator that provides its input value as the result + * @return a unary operator that always returns its input argument */ static DoubleUnaryOperator identity() { return t -> t; diff --git a/src/share/classes/java/util/function/Function.java b/src/share/classes/java/util/function/Function.java --- a/src/share/classes/java/util/function/Function.java +++ b/src/share/classes/java/util/function/Function.java @@ -27,12 +27,13 @@ import java.util.Objects; /** - * Apply a function to the input argument, yielding an appropriate result. A - * function may variously provide a mapping between types, object instances or - * keys and values or any other form of transformation upon the input. + * Represents a function that accepts one argument and produces a result. * - * @param the type of the input to the {@code apply} operation - * @param the type of the result of the {@code apply} operation + *

This is a functional interface + * whose functional method is {@link #apply(Object)}. + * + * @param the type of the input to the function + * @param the type of the result of the function * * @since 1.8 */ @@ -40,25 +41,27 @@ public interface Function { /** - * Compute the result of applying the function to the input argument + * Applies this function to the given argument. * - * @param t the input object + * @param t the function argument * @return the function result */ R apply(T t); /** - * Returns a new function which applies the provided function followed by - * this function. If either function throws an exception, it is relayed - * to the caller. + * Returns a composed function that first applies the {@code before} + * function to its input, and then applies this function to the result. + * If evaluation of either function throws an exception, it is relayed to + * the caller of the composed function. * - * @param type of input objects to the combined function. May be the - * same type as {@code } or {@code } - * @param before an additional function to be applied before this function - * is applied - * @return a function which performs the provided function followed by this - * function + * @param the type of input to the {@code before} function, and to the + * composed function + * @param before the function to apply before this function is applied + * @return a composed function that first applies the {@code before} + * function and then applies this function * @throws NullPointerException if before is null + * + * @see #andThen(Function) */ default Function compose(Function before) { Objects.requireNonNull(before); @@ -66,17 +69,19 @@ } /** - * Returns a new function which applies this function followed by the - * provided function. If either function throws an exception, it is relayed - * to the caller. + * Returns a composed function that first applies this function to + * its input, and then applies the {@code after} function to the result. + * If evaluation of either function throws an exception, it is relayed to + * the caller of the composed function. * - * @param type of output objects to the combined function. May be the - * same type as {@code } or {@code } - * @param after an additional function to be applied after this function is - * applied - * @return a function which performs this function followed by the provided - * function + * @param the type of output of the {@code after} function, and of the + * composed function + * @param after the function to apply after this function is applied + * @return a composed function that first applies this function and then + * applies the {@code after} function * @throws NullPointerException if after is null + * + * @see #compose(Function) */ default Function andThen(Function after) { Objects.requireNonNull(after); @@ -84,10 +89,10 @@ } /** - * Returns a {@code Function} whose {@code apply} method returns its input. + * Returns a function that always returns its input argument. * * @param the type of the input and output objects to the function - * @return a {@code Function} whose {@code apply} method returns its input + * @return a function that always returns its input argument */ static Function identity() { return t -> t; diff --git a/src/share/classes/java/util/function/IntBinaryOperator.java b/src/share/classes/java/util/function/IntBinaryOperator.java --- a/src/share/classes/java/util/function/IntBinaryOperator.java +++ b/src/share/classes/java/util/function/IntBinaryOperator.java @@ -25,24 +25,26 @@ package java.util.function; /** - * An operation on two {@code int} operands yielding an {@code int} result. - * This is the primitive type specialization of {@link BinaryOperator} for - * {@code int}. + * Represents an operation upon two {@code int}-valued operands and producing an + * {@code int}-valued result. This is the primitive type specialization of + * {@link BinaryOperator} for {@code int}. + * + *

This is a functional interface + * whose functional method is {@link #applyAsInt(int, int)}. * * @see BinaryOperator + * @see IntUnaryOperator * @since 1.8 */ @FunctionalInterface public interface IntBinaryOperator { /** - * Returns the {@code int} result of the operation upon the {@code int} - * operands. The parameters are named {@code left} and {@code right} for - * operations where the order of parameters matters. + * Applies this operator to the given operands. * - * @param left the left operand value - * @param right the right operand value - * @return the result of the operation + * @param left the first operand + * @param right the second operand + * @return the operator result */ int applyAsInt(int left, int right); } diff --git a/src/share/classes/java/util/function/IntConsumer.java b/src/share/classes/java/util/function/IntConsumer.java --- a/src/share/classes/java/util/function/IntConsumer.java +++ b/src/share/classes/java/util/function/IntConsumer.java @@ -27,10 +27,13 @@ import java.util.Objects; /** - * An operation which accepts a single integer argument and returns no result. - * This is the primitive type specialization of {@link Consumer} for {@code int}. - * Unlike most other functional interfaces, {@code IntConsumer} is expected to - * operate via side-effects. + * Represents an operation that accepts a single {@code int}-valued argument and + * returns no result. This is the primitive type specialization of + * {@link Consumer} for {@code int}. Unlike most other functional interfaces, + * {@code IntConsumer} is expected to operate via side-effects. + * + *

This is a functional interface + * whose functional method is {@link #accept(int)}. * * @see Consumer * @since 1.8 @@ -39,30 +42,26 @@ public interface IntConsumer { /** - * Accept an input value. + * Performs this operation on the given argument. * - * @param value the input value + * @param value the input argument */ void accept(int value); /** - * Returns an {@code IntConsumer} which performs, in sequence, the operation - * represented by this object followed by the operation represented by - * another {@code IntConsumer}. + * Returns a composed {@code IntConsumer} that performs, in sequence, this + * operation followed by the {@code after} operation. If performing either + * operation throws an exception, it is relayed to the caller of the + * composed operation. If performing this operation throws an exception, + * the {@code after} operation will not be performed. * - *

Any exceptions thrown by either {@code accept} method are relayed - * to the caller; if performing this operation throws an exception, the - * other operation will not be performed. - * - * @param other an IntConsumer which will be chained after this - * IntConsumer - * @return an IntConsumer which performs in sequence the {@code accept} method - * of this IntConsumer and the {@code accept} method of the specified IntConsumer - * operation - * @throws NullPointerException if other is null + * @param after the operation to perform after this operation + * @return a composed {@code IntConsumer} that performs in sequence this + * operation followed by the {@code after} operation + * @throws NullPointerException if {@code after} is null */ - default IntConsumer chain(IntConsumer other) { - Objects.requireNonNull(other); - return (int t) -> { accept(t); other.accept(t); }; + default IntConsumer andThen(IntConsumer after) { + Objects.requireNonNull(after); + return (int t) -> { accept(t); after.accept(t); }; } } diff --git a/src/share/classes/java/util/function/IntFunction.java b/src/share/classes/java/util/function/IntFunction.java --- a/src/share/classes/java/util/function/IntFunction.java +++ b/src/share/classes/java/util/function/IntFunction.java @@ -25,11 +25,14 @@ package java.util.function; /** - * Apply a function to the integer-valued input argument, yielding an - * appropriate result. This is the {@code int}-consuming primitive - * specialization for {@link Function}. + * Represents a function that accepts an int-valued argument and produces a + * result. This is the {@code int}-consuming primitive specialization for + * {@link Function}. * - * @param the type of output objects from the function + *

This is a functional interface + * whose functional method is {@link #apply(int)}. + * + * @param the type of the result of the function * * @see Function * @since 1.8 @@ -38,9 +41,9 @@ public interface IntFunction { /** - * Compute the result of applying the function to the input argument + * Applies this function to the given argument. * - * @param value the input value + * @param value the function argument * @return the function result */ R apply(int value); diff --git a/src/share/classes/java/util/function/IntPredicate.java b/src/share/classes/java/util/function/IntPredicate.java --- a/src/share/classes/java/util/function/IntPredicate.java +++ b/src/share/classes/java/util/function/IntPredicate.java @@ -27,8 +27,12 @@ import java.util.Objects; /** - * Determines if the {@code int} input value matches some criteria. This is the - * {@code int}-consuming primitive type specialization of {@link Predicate}. + * Represents a predicate (boolean-valued function) of one {@code int}-valued + * argument. This is the {@code int}-consuming primitive type specialization of + * {@link Predicate}. + * + *

This is a functional interface + * whose functional method is {@link #test(int)}. * * @see Predicate * @since 1.8 @@ -37,38 +41,40 @@ public interface IntPredicate { /** - * Returns {@code true} if the input value matches some criteria. + * Evaluates this predicate on the given argument. * - * @param value the value to be tested - * @return {@code true} if the input value matches some criteria, otherwise - * {@code false} + * @param value the input argument + * @return {@code true} if the input argument matches the predicate, + * otherwise {@code false} */ boolean test(int value); /** - * Returns a predicate which evaluates to {@code true} only if this - * predicate and the provided predicate both evaluate to {@code true}. If - * this predicate returns {@code false} then the remaining predicate is not - * evaluated. + * Returns a composed predicate that represents a short-circuiting logical + * AND of this predicate and another. When evaluating the composed + * predicate, if this predicate is {@code false}, then the {@code other} + * predicate is not evaluated. * - *

Any exceptions thrown by either {@code test} method are relayed - * to the caller; if performing first operation throws an exception, the - * second operation will not be performed. + *

Any exceptions thrown during evaluation of either predicate are relayed + * to the caller; if evaluation of this predicate throws an exception, the + * {@code other} predicate will not be evaluated. * - * @param p a predicate which will be logically-ANDed with this predicate - * @return a new predicate which returns {@code true} only if both - * predicates return {@code true} - * @throws NullPointerException if p is null + * @param other a predicate that will be logically-ANDed with this + * predicate + * @return a composed predicate that represents the short-circuiting logical + * AND of this predicate and the {@code other} predicate + * @throws NullPointerException if other is null */ - default IntPredicate and(IntPredicate p) { - Objects.requireNonNull(p); - return (value) -> test(value) && p.test(value); + default IntPredicate and(IntPredicate other) { + Objects.requireNonNull(other); + return (value) -> test(value) && other.test(value); } /** - * Returns a predicate which negates the result of this predicate. + * Returns a predicate that represents the logical negation of this + * predicate. * - * @return a new predicate who's result is always the opposite of this + * @return a predicate that represents the logical negation of this * predicate */ default IntPredicate negate() { @@ -76,22 +82,23 @@ } /** - * Returns a predicate which evaluates to {@code true} if either this - * predicate or the provided predicate evaluates to {@code true}. If this - * predicate returns {@code true} then the remaining predicate is not - * evaluated. + * Returns a composed predicate that represents a short-circuiting logical + * OR of this predicate and another. When evaluating the composed + * predicate, if this predicate is {@code true}, then the {@code other} + * predicate is not evaluated. * - *

Any exceptions thrown by either {@code test} method are relayed - * to the caller; if performing first operation throws an exception, the - * second operation will not be performed. + *

Any exceptions thrown during evaluation of either predicate are relayed + * to the caller; if evaluation of this predicate throws an exception, the + * {@code other} predicate will not be evaluated. * - * @param p a predicate which will be logically-ORed with this predicate - * @return a new predicate which returns {@code true} if either predicate - * returns {@code true} - * @throws NullPointerException if p is null + * @param other a predicate that will be logically-ORed with this + * predicate + * @return a composed predicate that represents the short-circuiting logical + * OR of this predicate and the {@code other} predicate + * @throws NullPointerException if other is null */ - default IntPredicate or(IntPredicate p) { - Objects.requireNonNull(p); - return (value) -> test(value) || p.test(value); + default IntPredicate or(IntPredicate other) { + Objects.requireNonNull(other); + return (value) -> test(value) || other.test(value); } } diff --git a/src/share/classes/java/util/function/IntSupplier.java b/src/share/classes/java/util/function/IntSupplier.java --- a/src/share/classes/java/util/function/IntSupplier.java +++ b/src/share/classes/java/util/function/IntSupplier.java @@ -25,8 +25,14 @@ package java.util.function; /** - * A supplier of {@code int} values. This is the {@code int}-providing - * primitive specialization of {@link Supplier}. + * Represents a supplier of {@code int}-valued results. This is the + * {@code int}-producing primitive specialization of {@link Supplier}. + * + *

There is no requirement that a distinct result be returned each + * time the supplier is invoked. + * + *

This is a functional interface + * whose functional method is {@link #getAsInt()}. * * @see Supplier * @since 1.8 @@ -35,9 +41,9 @@ public interface IntSupplier { /** - * Returns an {@code int} value. + * Gets a result. * - * @return an {@code int} value + * @return a result */ int getAsInt(); } diff --git a/src/share/classes/java/util/function/IntToDoubleFunction.java b/src/share/classes/java/util/function/IntToDoubleFunction.java --- a/src/share/classes/java/util/function/IntToDoubleFunction.java +++ b/src/share/classes/java/util/function/IntToDoubleFunction.java @@ -25,22 +25,24 @@ package java.util.function; /** - * Apply a function to the input argument, yielding an appropriate result. - * This is the {@code int}-to-{@code double} specialization for {@link Function}. + * Represents a function that accepts an int-valued argument and produces a + * double-valued result. This is the {@code int}-to-{@code double} primitive + * specialization for {@link Function}. + * + *

This is a functional interface + * whose functional method is {@link #applyAsDouble(int)}. * * @see Function - * @see DoubleToIntFunction - * @see LongToDoubleFunction * @since 1.8 */ @FunctionalInterface public interface IntToDoubleFunction { /** - * Compute the result of applying the function to the input arguments. + * Applies this function to the given argument. * - * @param value the input value - * @return the function result value + * @param value the function argument + * @return the function result */ double applyAsDouble(int value); } diff --git a/src/share/classes/java/util/function/IntToLongFunction.java b/src/share/classes/java/util/function/IntToLongFunction.java --- a/src/share/classes/java/util/function/IntToLongFunction.java +++ b/src/share/classes/java/util/function/IntToLongFunction.java @@ -25,22 +25,24 @@ package java.util.function; /** - * Apply a function to the input argument, yielding an appropriate result. - * This is the {@code int}-to-{@code long} specialization for {@link Function}. + * Represents a function that accepts an int-valued argument and produces a + * long-valued result. This is the {@code int}-to-{@code long} primitive + * specialization for {@link Function}. + * + *

This is a functional interface + * whose functional method is {@link #applyAsLong(int)}. * * @see Function - * @see LongToIntFunction - * @see DoubleToLongFunction * @since 1.8 */ @FunctionalInterface public interface IntToLongFunction { /** - * Compute the result of applying the function to the input arguments. + * Applies this function to the given argument. * - * @param value the input value - * @return the function result value + * @param value the function argument + * @return the function result */ long applyAsLong(int value); } diff --git a/src/share/classes/java/util/function/IntUnaryOperator.java b/src/share/classes/java/util/function/IntUnaryOperator.java --- a/src/share/classes/java/util/function/IntUnaryOperator.java +++ b/src/share/classes/java/util/function/IntUnaryOperator.java @@ -27,9 +27,12 @@ import java.util.Objects; /** - * An operation on a single {@code int} operand yielding an {@code int} result. - * This is the primitive type specialization of {@link UnaryOperator} for - * {@code int}. + * Represents an operation on a single {@code int}-valued operand that produces + * an {@code int}-valued result. This is the primitive type specialization of + * {@link UnaryOperator} for {@code int}. + * + *

This is a functional interface + * whose functional method is {@link #applyAsInt(int)}. * * @see UnaryOperator * @since 1.8 @@ -38,24 +41,25 @@ public interface IntUnaryOperator { /** - * Returns the {@code int} value result of the operation upon the - * {@code int} operand. + * Applies this operator to the given operand. * - * @param operand the operand value - * @return the operation result value + * @param operand the operand + * @return the operator result */ int applyAsInt(int operand); /** - * Compose a new function which applies the provided function followed by - * this function. If either function throws an exception, it is relayed - * to the caller. + * Returns a composed operator that first applies the {@code before} + * operator to its input, and then applies this operator to the result. + * If evaluation of either operator throws an exception, it is relayed to + * the caller of the composed operator. * - * @param before an additional function to be applied before this function - * is applied - * @return a function which performs the provided function followed by this - * function + * @param before the operator to apply before this operator is applied + * @return a composed operator that first applies the {@code before} + * operator and then applies this operator * @throws NullPointerException if before is null + * + * @see #andThen(IntUnaryOperator) */ default IntUnaryOperator compose(IntUnaryOperator before) { Objects.requireNonNull(before); @@ -63,15 +67,17 @@ } /** - * Compose a new function which applies this function followed by the - * provided function. If either function throws an exception, it is relayed - * to the caller. + * Returns a composed operator that first applies this operator to + * its input, and then applies the {@code after} operator to the result. + * If evaluation of either operator throws an exception, it is relayed to + * the caller of the composed operator. * - * @param after an additional function to be applied after this function is - * applied - * @return a function which performs this function followed by the provided - * function followed + * @param after the operator to apply after this operator is applied + * @return a composed operator that first applies this operator and then + * applies the {@code after} operator * @throws NullPointerException if after is null + * + * @see #compose(IntUnaryOperator) */ default IntUnaryOperator andThen(IntUnaryOperator after) { Objects.requireNonNull(after); @@ -79,9 +85,9 @@ } /** - * Returns a unary operator that provides its input value as the result. + * Returns a unary operator that always returns its input argument. * - * @return a unary operator that provides its input value as the result + * @return a unary operator that always returns its input argument */ static IntUnaryOperator identity() { return t -> t; diff --git a/src/share/classes/java/util/function/LongBinaryOperator.java b/src/share/classes/java/util/function/LongBinaryOperator.java --- a/src/share/classes/java/util/function/LongBinaryOperator.java +++ b/src/share/classes/java/util/function/LongBinaryOperator.java @@ -25,24 +25,26 @@ package java.util.function; /** - * An operation on two {@code long} operands yielding a {@code long} result. - * This is the primitive type specialization of {@link BinaryOperator} for - * {@code long}. + * Represents an operation upon two {@code long}-valued operands and producing a + * {@code long}-valued result. This is the primitive type specialization of + * {@link BinaryOperator} for {@code long}. + * + *

This is a functional interface + * whose functional method is {@link #applyAsLong(long, long)}. * * @see BinaryOperator + * @see LongUnaryOperator * @since 1.8 */ @FunctionalInterface public interface LongBinaryOperator { /** - * Returns the {@code long} result of the operation upon the {@code long} - * operands. The parameters are named {@code left} and {@code right} for - * operations where the order of parameters matters. + * Applies this operator to the given operands. * - * @param left the left operand value - * @param right the right operand value - * @return the result of the operation + * @param left the first operand + * @param right the second operand + * @return the operator result */ long applyAsLong(long left, long right); } diff --git a/src/share/classes/java/util/function/LongConsumer.java b/src/share/classes/java/util/function/LongConsumer.java --- a/src/share/classes/java/util/function/LongConsumer.java +++ b/src/share/classes/java/util/function/LongConsumer.java @@ -27,10 +27,13 @@ import java.util.Objects; /** - * An operation which accepts a single long argument and returns no result. - * This is the {@code long}-consuming primitive type specialization of - * {@link Consumer}. Unlike most other functional interfaces, {@code LongConsumer} - * is expected to operate via side-effects. + * Represents an operation that accepts a single {@code long}-valued argument and + * returns no result. This is the primitive type specialization of + * {@link Consumer} for {@code long}. Unlike most other functional interfaces, + * {@code LongConsumer} is expected to operate via side-effects. + * + *

This is a functional interface + * whose functional method is {@link #accept(long)}. * * @see Consumer * @since 1.8 @@ -39,30 +42,26 @@ public interface LongConsumer { /** - * Accept an input value. + * Performs this operation on the given argument. * - * @param value the input value + * @param value the input argument */ void accept(long value); /** - * Returns a {@code LongConsumer} which performs, in sequence, the operation - * represented by this object followed by the operation represented by - * another {@code LongConsumer}. + * Returns a composed {@code LongConsumer} that performs, in sequence, this + * operation followed by the {@code after} operation. If performing either + * operation throws an exception, it is relayed to the caller of the + * composed operation. If performing this operation throws an exception, + * the {@code after} operation will not be performed. * - *

Any exceptions thrown by either {@code accept} method are relayed - * to the caller; if performing this operation throws an exception, the - * other operation will not be performed. - * - * @param other a LongConsumer which will be chained after this - * LongConsumer - * @return a LongConsumer which performs in sequence the {@code accept} method - * of this LongConsumer and the {@code accept} method of the specified LongConsumer - * operation - * @throws NullPointerException if other is null + * @param after the operation to perform after this operation + * @return a composed {@code LongConsumer} that performs in sequence this + * operation followed by the {@code after} operation + * @throws NullPointerException if {@code after} is null */ - default LongConsumer chain(LongConsumer other) { - Objects.requireNonNull(other); - return (long t) -> { accept(t); other.accept(t); }; + default LongConsumer andThen(LongConsumer after) { + Objects.requireNonNull(after); + return (long t) -> { accept(t); after.accept(t); }; } } diff --git a/src/share/classes/java/util/function/LongFunction.java b/src/share/classes/java/util/function/LongFunction.java --- a/src/share/classes/java/util/function/LongFunction.java +++ b/src/share/classes/java/util/function/LongFunction.java @@ -25,11 +25,14 @@ package java.util.function; /** - * Apply a function to the long-valued input argument, yielding an appropriate - * result. This is the {@code long}-consuming primitive specialization for + * Represents a function that accepts a long-valued argument and produces a + * result. This is the {@code long}-consuming primitive specialization for * {@link Function}. * - * @param the type of output objects from the function + *

This is a functional interface + * whose functional method is {@link #apply(long)}. + * + * @param the type of the result of the function * * @see Function * @since 1.8 @@ -38,9 +41,9 @@ public interface LongFunction { /** - * Compute the result of applying the function to the input argument + * Applies this function to the given argument. * - * @param value the input value + * @param value the function argument * @return the function result */ R apply(long value); diff --git a/src/share/classes/java/util/function/LongPredicate.java b/src/share/classes/java/util/function/LongPredicate.java --- a/src/share/classes/java/util/function/LongPredicate.java +++ b/src/share/classes/java/util/function/LongPredicate.java @@ -27,8 +27,12 @@ import java.util.Objects; /** - * Determines if the {@code long} input value matches some criteria. This is the - * {@code long}-consuming primitive type specialization of {@link Predicate}. + * Represents a predicate (boolean-valued function) of one {@code long}-valued + * argument. This is the {@code long}-consuming primitive type specialization of + * {@link Predicate}. + * + *

This is a functional interface + * whose functional method is {@link #test(long)}. * * @see Predicate * @since 1.8 @@ -37,37 +41,40 @@ public interface LongPredicate { /** - * Returns {@code true} if the input value matches some criteria. + * Evaluates this predicate on the given argument. * - * @param value the value to be tested - * @return {@code true} if the input value matches some criteria, otherwise - * {@code false} + * @param value the input argument + * @return {@code true} if the input argument matches the predicate, + * otherwise {@code false} */ boolean test(long value); /** - * Returns a predicate which evaluates to {@code true} only if this - * predicate and the provided predicate both evaluate to {@code true}. If - * this predicate returns {@code false} then the remaining predicate is not - * evaluated. + * Returns a composed predicate that represents a short-circuiting logical + * AND of this predicate and another. When evaluating the composed + * predicate, if this predicate is {@code false}, then the {@code other} + * predicate is not evaluated. * - *

Any exceptions thrown by either {@code test} method are relayed - * to the caller; if performing first operation throws an exception, the - * second operation will not be performed. + *

Any exceptions thrown during evaluation of either predicate are relayed + * to the caller; if evaluation of this predicate throws an exception, the + * {@code other} predicate will not be evaluated. * - * @param p a predicate which will be logically-ANDed with this predicate - * @return a new predicate which returns {@code true} only if both - * predicates return {@code true} + * @param other a predicate that will be logically-ANDed with this + * predicate + * @return a composed predicate that represents the short-circuiting logical + * AND of this predicate and the {@code other} predicate + * @throws NullPointerException if other is null */ - default LongPredicate and(LongPredicate p) { - Objects.requireNonNull(p); - return (value) -> test(value) && p.test(value); + default LongPredicate and(LongPredicate other) { + Objects.requireNonNull(other); + return (value) -> test(value) && other.test(value); } /** - * Returns a predicate which negates the result of this predicate. + * Returns a predicate that represents the logical negation of this + * predicate. * - * @return a new predicate who's result is always the opposite of this + * @return a predicate that represents the logical negation of this * predicate */ default LongPredicate negate() { @@ -75,22 +82,23 @@ } /** - * Returns a predicate which evaluates to {@code true} if either this - * predicate or the provided predicate evaluates to {@code true}. If this - * predicate returns {@code true} then the remaining predicate is not - * evaluated. + * Returns a composed predicate that represents a short-circuiting logical + * OR of this predicate and another. When evaluating the composed + * predicate, if this predicate is {@code true}, then the {@code other} + * predicate is not evaluated. * - *

Any exceptions thrown by either {@code test} method are relayed - * to the caller; if performing first operation throws an exception, the - * second operation will not be performed. + *

Any exceptions thrown during evaluation of either predicate are relayed + * to the caller; if evaluation of this predicate throws an exception, the + * {@code other} predicate will not be evaluated. * - * @param p a predicate which will be logically-ORed with this predicate - * @return a new predicate which returns {@code true} if either predicate - * returns {@code true} - * @throws NullPointerException if p is null + * @param other a predicate that will be logically-ORed with this + * predicate + * @return a composed predicate that represents the short-circuiting logical + * OR of this predicate and the {@code other} predicate + * @throws NullPointerException if other is null */ - default LongPredicate or(LongPredicate p) { - Objects.requireNonNull(p); - return (value) -> test(value) || p.test(value); + default LongPredicate or(LongPredicate other) { + Objects.requireNonNull(other); + return (value) -> test(value) || other.test(value); } } diff --git a/src/share/classes/java/util/function/LongSupplier.java b/src/share/classes/java/util/function/LongSupplier.java --- a/src/share/classes/java/util/function/LongSupplier.java +++ b/src/share/classes/java/util/function/LongSupplier.java @@ -25,8 +25,14 @@ package java.util.function; /** - * A supplier of {@code long} values. This is the {@code long}-providing - * primitive specialization of {@link Supplier}. + * Represents a supplier of {@code long}-valued results. This is the + * {@code long}-producing primitive specialization of {@link Supplier}. + * + *

There is no requirement that a distinct result be returned each + * time the supplier is invoked. + * + *

This is a functional interface + * whose functional method is {@link #getAsLong()}. * * @see Supplier * @since 1.8 @@ -35,9 +41,9 @@ public interface LongSupplier { /** - * Returns a {@code long} value. + * Gets a result. * - * @return a {@code long} value + * @return a result */ long getAsLong(); } diff --git a/src/share/classes/java/util/function/LongToDoubleFunction.java b/src/share/classes/java/util/function/LongToDoubleFunction.java --- a/src/share/classes/java/util/function/LongToDoubleFunction.java +++ b/src/share/classes/java/util/function/LongToDoubleFunction.java @@ -25,22 +25,24 @@ package java.util.function; /** - * Apply a function to the input argument, yielding an appropriate result. - * This is the {@code long}-to-{@code double} specialization for {@link Function}. + * Represents a function that accepts a long-valued argument and produces a + * double-valued result. This is the {@code long}-to-{@code double} primitive + * specialization for {@link Function}. + * + *

This is a functional interface + * whose functional method is {@link #applyAsDouble(long)}. * * @see Function - * @see DoubleToLongFunction - * @see IntToDoubleFunction * @since 1.8 */ @FunctionalInterface public interface LongToDoubleFunction { /** - * Compute the result of applying the function to the input arguments. + * Applies this function to the given argument. * - * @param value the input value - * @return the function result value + * @param value the function argument + * @return the function result */ double applyAsDouble(long value); } diff --git a/src/share/classes/java/util/function/LongToIntFunction.java b/src/share/classes/java/util/function/LongToIntFunction.java --- a/src/share/classes/java/util/function/LongToIntFunction.java +++ b/src/share/classes/java/util/function/LongToIntFunction.java @@ -25,22 +25,24 @@ package java.util.function; /** - * Apply a function to the input argument, yielding an appropriate result. - * This is the {@code long}-to-{@code int} specialization for {@link Function}. + * Represents a function that accepts a long-valued argument and produces an + * int-valued result. This is the {@code long}-to-{@code int} primitive + * specialization for {@link Function}. + * + *

This is a functional interface + * whose functional method is {@link #applyAsInt(long)}. * * @see Function - * @see IntToLongFunction - * @see DoubleToIntFunction * @since 1.8 */ @FunctionalInterface public interface LongToIntFunction { /** - * Compute the result of applying the function to the input arguments. + * Applies this function to the given argument. * - * @param value the input value - * @return the function result value + * @param value the function argument + * @return the function result */ int applyAsInt(long value); } diff --git a/src/share/classes/java/util/function/LongUnaryOperator.java b/src/share/classes/java/util/function/LongUnaryOperator.java --- a/src/share/classes/java/util/function/LongUnaryOperator.java +++ b/src/share/classes/java/util/function/LongUnaryOperator.java @@ -27,9 +27,12 @@ import java.util.Objects; /** - * An operation on a single {@code long} operand yielding a {@code long} result. - * This is the primitive type specialization of {@link UnaryOperator} for - * {@code long}. + * Represents an operation on a single {@code long}-valued operand that produces + * a {@code long}-valued result. This is the primitive type specialization of + * {@link UnaryOperator} for {@code long}. + * + *

This is a functional interface + * whose functional method is {@link #applyAsLong(long)}. * * @see UnaryOperator * @since 1.8 @@ -38,24 +41,25 @@ public interface LongUnaryOperator { /** - * Returns the {@code long} result of the operation upon the {@code long} - * operand. + * Applies this operator to the given operand. * - * @param operand the operand value - * @return the operation result value + * @param operand the operand + * @return the operator result */ long applyAsLong(long operand); /** - * Compose a new function which applies the provided function followed by - * this function. If either function throws an exception, it is relayed - * to the caller. + * Returns a composed operator that first applies the {@code before} + * operator to its input, and then applies this operator to the result. + * If evaluation of either operator throws an exception, it is relayed to + * the caller of the composed operator. * - * @param before An additional function to be applied before this function - * is applied - * @return A function which performs the provided function followed by this - * function + * @param before the operator to apply before this operator is applied + * @return a composed operator that first applies the {@code before} + * operator and then applies this operator * @throws NullPointerException if before is null + * + * @see #andThen(LongUnaryOperator) */ default LongUnaryOperator compose(LongUnaryOperator before) { Objects.requireNonNull(before); @@ -63,15 +67,17 @@ } /** - * Compose a new function which applies this function followed by the - * provided function. If either function throws an exception, it is relayed - * to the caller. + * Returns a composed operator that first applies this operator to + * its input, and then applies the {@code after} operator to the result. + * If evaluation of either operator throws an exception, it is relayed to + * the caller of the composed operator. * - * @param after An additional function to be applied after this function is - * applied - * @return A function which performs this function followed by the provided - * function followed + * @param after the operator to apply after this operator is applied + * @return a composed operator that first applies this operator and then + * applies the {@code after} operator * @throws NullPointerException if after is null + * + * @see #compose(LongUnaryOperator) */ default LongUnaryOperator andThen(LongUnaryOperator after) { Objects.requireNonNull(after); @@ -79,9 +85,9 @@ } /** - * Returns a unary operator that provides its input value as the result. + * Returns a unary operator that always returns its input argument. * - * @return a unary operator that provides its input value as the result + * @return a unary operator that always returns its input argument */ static LongUnaryOperator identity() { return t -> t; diff --git a/src/share/classes/java/util/function/ObjDoubleConsumer.java b/src/share/classes/java/util/function/ObjDoubleConsumer.java --- a/src/share/classes/java/util/function/ObjDoubleConsumer.java +++ b/src/share/classes/java/util/function/ObjDoubleConsumer.java @@ -25,12 +25,16 @@ package java.util.function; /** - * An operation which accepts an object reference and a double, and returns no - * result. This is the {@code (reference, double)} specialization of - * {@link BiConsumer}. Unlike most other functional interfaces, - * {@code ObjDoubleConsumer} is expected to operate via side-effects. + * Represents an operation that accepts an object-valued and a + * {@code double}-valued argument, and returns no result. This is the + * {@code (reference, double)} specialization of {@link BiConsumer}. + * Unlike most other functional interfaces, {@code ObjDoubleConsumer} is + * expected to operate via side-effects. * - * @param Type of reference argument to {@code accept()}. + *

This is a functional interface + * whose functional method is {@link #accept(Object, double)}. + * + * @param the type of the object argument to the operation * * @see BiConsumer * @since 1.8 @@ -39,10 +43,10 @@ public interface ObjDoubleConsumer { /** - * Accept a set of input values. + * Performs this operation on the given arguments. * - * @param t an input object - * @param value an input value + * @param t the first input argument + * @param value the second input argument */ void accept(T t, double value); } diff --git a/src/share/classes/java/util/function/ObjIntConsumer.java b/src/share/classes/java/util/function/ObjIntConsumer.java --- a/src/share/classes/java/util/function/ObjIntConsumer.java +++ b/src/share/classes/java/util/function/ObjIntConsumer.java @@ -25,12 +25,16 @@ package java.util.function; /** - * An operation which accepts an object reference and an int, and returns no - * result. This is the {@code (reference, int)} specialization of - * {@link BiConsumer}. Unlike most other functional interfaces, - * {@code ObjIntConsumer} is expected to operate via side-effects. + * Represents an operation that accepts an object-valued and a + * {@code int}-valued argument, and returns no result. This is the + * {@code (reference, int)} specialization of {@link BiConsumer}. + * Unlike most other functional interfaces, {@code ObjIntConsumer} is + * expected to operate via side-effects. * - * @param Type of reference argument to {@code accept()} + *

This is a functional interface + * whose functional method is {@link #accept(Object, int)}. + * + * @param the type of the object argument to the operation * * @see BiConsumer * @since 1.8 @@ -39,10 +43,10 @@ public interface ObjIntConsumer { /** - * Accept a set of input values. + * Performs this operation on the given arguments. * - * @param t an input object - * @param value an input value + * @param t the first input argument + * @param value the second input argument */ void accept(T t, int value); } diff --git a/src/share/classes/java/util/function/ObjLongConsumer.java b/src/share/classes/java/util/function/ObjLongConsumer.java --- a/src/share/classes/java/util/function/ObjLongConsumer.java +++ b/src/share/classes/java/util/function/ObjLongConsumer.java @@ -25,12 +25,16 @@ package java.util.function; /** - * An operation which accepts an object reference and a long, and returns no - * result. This is the {@code (reference, long)} specialization of - * {@link BiConsumer}. Unlike most other functional interfaces, - * {@code ObjLongConsumer} is expected to operate via side-effects. + * Represents an operation that accepts an object-valued and a + * {@code long}-valued argument, and returns no result. This is the + * {@code (reference, long)} specialization of {@link BiConsumer}. + * Unlike most other functional interfaces, {@code ObjLongConsumer} is + * expected to operate via side-effects. * - * @param Type of reference argument to {@code accept()} + *

This is a functional interface + * whose functional method is {@link #accept(Object, long)}. + * + * @param the type of the object argument to the operation * * @see BiConsumer * @since 1.8 @@ -39,10 +43,10 @@ public interface ObjLongConsumer { /** - * Accept a set of input values. + * Performs this operation on the given arguments. * - * @param t an input object - * @param value an input value + * @param t the first input argument + * @param value the second input argument */ void accept(T t, long value); } diff --git a/src/share/classes/java/util/function/Predicate.java b/src/share/classes/java/util/function/Predicate.java --- a/src/share/classes/java/util/function/Predicate.java +++ b/src/share/classes/java/util/function/Predicate.java @@ -27,9 +27,12 @@ import java.util.Objects; /** - * Determines if the input object matches some criteria. + * Represents a predicate (boolean-valued function) of one argument. * - * @param the type of argument to {@code test} + *

This is a functional interface + * whose functional method is {@link #test(Object)}. + * + * @param the type of the input to the predicate * * @since 1.8 */ @@ -37,76 +40,80 @@ public interface Predicate { /** - * Returns {@code true} if the input object matches some criteria. + * Evaluates this predicate on the given argument. * - * @param t the input object - * @return {@code true} if the input object matches some criteria, otherwise - * {@code false} + * @param t the input argument + * @return {@code true} if the input argument matches the predicate, + * otherwise {@code false} */ boolean test(T t); /** - * Returns a predicate which evaluates to {@code true} only if this - * predicate and the provided predicate both evaluate to {@code true}. If - * this predicate returns {@code false} then the remaining predicate is not - * evaluated. + * Returns a composed predicate that represents a short-circuiting logical + * AND of this predicate and another. When evaluating the composed + * predicate, if this predicate is {@code false}, then the {@code other} + * predicate is not evaluated. * - *

Any exceptions thrown by either {@code test} method are relayed - * to the caller; if performing first operation throws an exception, the - * second operation will not be performed. + *

Any exceptions thrown during evaluation of either predicate are relayed + * to the caller; if evaluation of this predicate throws an exception, the + * {@code other} predicate will not be evaluated. * - * @param p a predicate which will be logically-ANDed with this predicate - * @return a new predicate which returns {@code true} only if both - * predicates return {@code true} - * @throws NullPointerException if p is null + * @param other a predicate that will be logically-ANDed with this + * predicate + * @return a composed predicate that represents the short-circuiting logical + * AND of this predicate and the {@code other} predicate + * @throws NullPointerException if other is null */ - default Predicate and(Predicate p) { - Objects.requireNonNull(p); - return (t) -> test(t) && p.test(t); + default Predicate and(Predicate other) { + Objects.requireNonNull(other); + return (t) -> test(t) && other.test(t); } /** - * Returns a predicate which negates the result of this predicate. + * Returns a predicate that represents the logical negation of this + * predicate. * - * @return a new predicate who's result is always the opposite of this - * predicate. + * @return a predicate that represents the logical negation of this + * predicate */ default Predicate negate() { return (t) -> !test(t); } /** - * Returns a predicate which evaluates to {@code true} if either this - * predicate or the provided predicate evaluates to {@code true}. If this - * predicate returns {@code true} then the remaining predicate is not - * evaluated. + * Returns a composed predicate that represents a short-circuiting logical + * OR of this predicate and another. When evaluating the composed + * predicate, if this predicate is {@code true}, then the {@code other} + * predicate is not evaluated. * - *

Any exceptions thrown by either {@code test} method are relayed - * to the caller; if performing first operation throws an exception, the - * second operation will not be performed. + *

Any exceptions thrown during evaluation of either predicate are relayed + * to the caller; if evaluation of this predicate throws an exception, the + * {@code other} predicate will not be evaluated. * - * @param p a predicate which will be logically-ORed with this predicate - * @return a new predicate which returns {@code true} if either predicate - * returns {@code true} - * @throws NullPointerException if p is null + * @param other a predicate that will be logically-ORed with this + * predicate + * @return a composed predicate that represents the short-circuiting logical + * OR of this predicate and the {@code other} predicate + * @throws NullPointerException if other is null */ - default Predicate or(Predicate p) { - Objects.requireNonNull(p); - return (t) -> test(t) || p.test(t); + default Predicate or(Predicate other) { + Objects.requireNonNull(other); + return (t) -> test(t) || other.test(t); } /** - * Returns a predicate who's result matches - * {@code Objects.equals(target, t)}. + * Returns a predicate that tests if two arguments are equal according + * to {@link Objects#equals(Object, Object)}. * - * @param the type of values evaluated by the predicate - * @param target the target value to be compared for equality - * @return a predicate who's result matches - * {@code Objects.equals(target, t)} + * @param the type of arguments to the predicate + * @param targetRef the object reference with which to compare for equality, + * which may be {@code null} + * @return a predicate that tests if two arguments are equal according + * to {@link Objects#equals(Object, Object)} */ - static Predicate isEqual(Object target) { - return (null == target) + static Predicate isEqual(Object targetRef) { + return (null == targetRef) ? Objects::isNull - : object -> target.equals(object); + : object -> targetRef.equals(object); } } diff --git a/src/share/classes/java/util/function/Supplier.java b/src/share/classes/java/util/function/Supplier.java --- a/src/share/classes/java/util/function/Supplier.java +++ b/src/share/classes/java/util/function/Supplier.java @@ -25,10 +25,15 @@ package java.util.function; /** - * A supplier of objects. The result objects are either created during the - * invocation of {@link #get} or by some prior action. + * Represents a supplier of results. * - * @param The type of objects returned by {@code get} + *

There is no requirement that a new or distinct result be returned each + * time the supplier is invoked. + * + *

This is a functional interface + * whose functional method is {@link #get()}. + * + * @param the type of results supplied by this supplier * * @since 1.8 */ @@ -36,9 +41,9 @@ public interface Supplier { /** - * Returns an object. + * Gets a result. * - * @return an object + * @return a result */ T get(); } diff --git a/src/share/classes/java/util/function/ToDoubleBiFunction.java b/src/share/classes/java/util/function/ToDoubleBiFunction.java --- a/src/share/classes/java/util/function/ToDoubleBiFunction.java +++ b/src/share/classes/java/util/function/ToDoubleBiFunction.java @@ -25,13 +25,15 @@ package java.util.function; /** - * Apply a function to the input arguments, yielding an appropriate result. - * This is the {@code double}-bearing specialization for {@link BiFunction}. + * Represents a function that accepts two arguments and produces a double-valued + * result. This is the {@code double}-producing primitive specialization for + * {@link BiFunction}. * - * @param the type of the first argument to the {@code applyAsDouble} - * operation. - * @param the type of the second argument to the {@code applyAsDouble} - * operation. + *

This is a functional interface + * whose functional method is {@link #applyAsDouble(Object, Object)}. + * + * @param the type of the first argument to the function + * @param the type of the second argument to the function * * @see BiFunction * @since 1.8 @@ -40,11 +42,11 @@ public interface ToDoubleBiFunction { /** - * Compute the result of applying the function to the input arguments + * Applies this function to the given arguments. * - * @param t an input object - * @param u an input object - * @return the function result value + * @param t the first function argument + * @param u the second function argument + * @return the function result */ double applyAsDouble(T t, U u); } diff --git a/src/share/classes/java/util/function/ToDoubleFunction.java b/src/share/classes/java/util/function/ToDoubleFunction.java --- a/src/share/classes/java/util/function/ToDoubleFunction.java +++ b/src/share/classes/java/util/function/ToDoubleFunction.java @@ -25,10 +25,13 @@ package java.util.function; /** - * Apply a function to the input argument, yielding an appropriate result. - * This is the {@code double}-bearing specialization for {@link Function}. + * Represents a function that produces a double-valued result. This is the + * {@code double}-producing primitive specialization for {@link Function}. * - * @param the type of input objects to the function + *

This is a functional interface + * whose functional method is {@link #applyAsDouble(Object)}. + * + * @param the type of the input to the function * * @see Function * @since 1.8 @@ -37,10 +40,10 @@ public interface ToDoubleFunction { /** - * Compute the result of applying the function to the input argument + * Applies this function to the given argument. * - * @param t the input object - * @return the function result value + * @param value the function argument + * @return the function result */ - double applyAsDouble(T t); + double applyAsDouble(T value); } diff --git a/src/share/classes/java/util/function/ToIntBiFunction.java b/src/share/classes/java/util/function/ToIntBiFunction.java --- a/src/share/classes/java/util/function/ToIntBiFunction.java +++ b/src/share/classes/java/util/function/ToIntBiFunction.java @@ -25,13 +25,15 @@ package java.util.function; /** - * Apply a function to the input arguments, yielding an appropriate result. - * This is the {@code int}-bearing specialization for {@link BiFunction}. + * Represents a function that accepts two arguments and produces an int-valued + * result. This is the {@code int}-producing primitive specialization for + * {@link BiFunction}. * - * @param the type of the first argument to the {@code applyAsInt} - * operation - * @param the type of the second argument to the {@code applyAsInt} - * operation + *

This is a functional interface + * whose functional method is {@link #applyAsInt(Object, Object)}. + * + * @param the type of the first argument to the function + * @param the type of the second argument to the function * * @see BiFunction * @since 1.8 @@ -40,11 +42,11 @@ public interface ToIntBiFunction { /** - * Compute the result of applying the function to the input arguments + * Applies this function to the given arguments. * - * @param t an input object - * @param u an input object - * @return the function result value + * @param t the first function argument + * @param u the second function argument + * @return the function result */ int applyAsInt(T t, U u); } diff --git a/src/share/classes/java/util/function/ToIntFunction.java b/src/share/classes/java/util/function/ToIntFunction.java --- a/src/share/classes/java/util/function/ToIntFunction.java +++ b/src/share/classes/java/util/function/ToIntFunction.java @@ -25,10 +25,13 @@ package java.util.function; /** - * Apply a function to the input argument, yielding an appropriate result. - * This is the {@code int}-bearing specialization for {@link Function}. + * Represents a function that produces an int-valued result. This is the + * {@code int}-producing primitive specialization for {@link Function}. * - * @param the type of input objects to the function + *

This is a functional interface + * whose functional method is {@link #applyAsInt(Object)}. + * + * @param the type of the input to the function * * @see Function * @since 1.8 @@ -37,10 +40,10 @@ public interface ToIntFunction { /** - * Compute the result of applying the function to the input arguments + * Applies this function to the given argument. * - * @param t the input object - * @return the function result value + * @param value the function argument + * @return the function result */ - int applyAsInt(T t); + int applyAsInt(T value); } diff --git a/src/share/classes/java/util/function/ToLongBiFunction.java b/src/share/classes/java/util/function/ToLongBiFunction.java --- a/src/share/classes/java/util/function/ToLongBiFunction.java +++ b/src/share/classes/java/util/function/ToLongBiFunction.java @@ -25,13 +25,15 @@ package java.util.function; /** - * Apply a function to the input arguments, yielding an appropriate result. - * This is the {@code long}-bearing specialization for {@link BiFunction}. + * Represents a function that accepts two arguments and produces a long-valued + * result. This is the {@code long}-producing primitive specialization for + * {@link BiFunction}. * - * @param the type of the first argument to the {@code applyAsLong} - * operation. - * @param the type of the second argument to the {@code applyAsLong} - * operation. + *

This is a functional interface + * whose functional method is {@link #applyAsLong(Object, Object)}. + * + * @param the type of the first argument to the function + * @param the type of the second argument to the function * * @see BiFunction * @since 1.8 @@ -40,11 +42,11 @@ public interface ToLongBiFunction { /** - * Compute the result of applying the function to the input arguments. + * Applies this function to the given arguments. * - * @param t an input object - * @param u an input object - * @return the function result value + * @param t the first function argument + * @param u the second function argument + * @return the function result */ long applyAsLong(T t, U u); } diff --git a/src/share/classes/java/util/function/ToLongFunction.java b/src/share/classes/java/util/function/ToLongFunction.java --- a/src/share/classes/java/util/function/ToLongFunction.java +++ b/src/share/classes/java/util/function/ToLongFunction.java @@ -25,10 +25,13 @@ package java.util.function; /** - * Apply a function to the input argument, yielding an appropriate result. - * This is the {@code long}-bearing specialization for {@link Function}. + * Represents a function that produces a long-valued result. This is the + * {@code long}-producing primitive specialization for {@link Function}. * - * @param the type of input objects to the function + *

This is a functional interface + * whose functional method is {@link #applyAsLong(Object)}. + * + * @param the type of the input to the function * * @see Function * @since 1.8 @@ -37,10 +40,10 @@ public interface ToLongFunction { /** - * Compute the result of applying the function to the input arguments. + * Applies this function to the given argument. * - * @param t the input object - * @return the function result value + * @param value the function argument + * @return the function result */ - long applyAsLong(T t); + long applyAsLong(T value); } diff --git a/src/share/classes/java/util/function/UnaryOperator.java b/src/share/classes/java/util/function/UnaryOperator.java --- a/src/share/classes/java/util/function/UnaryOperator.java +++ b/src/share/classes/java/util/function/UnaryOperator.java @@ -25,11 +25,14 @@ package java.util.function; /** - * An operation upon a single operand yielding a result. The operand and the - * result are of the same type. This is a specialization of {@code Function} for + * Represents an operation on a single operand that produces a result of the + * same type as its operand. This is a specialization of {@code Function} for * the case where the operand and result are of the same type. * - * @param the type of operand to {@code apply} and of the result + *

This is a functional interface + * whose functional method is {@link #apply(Object)}. + * + * @param the type of the operand and result of the operator * * @see Function * @since 1.8 @@ -38,10 +41,10 @@ public interface UnaryOperator extends Function { /** - * Returns a unary operator that provides its input value as the result. + * Returns a unary operator that always returns its input argument. * - * @param the type of the input and output objects to the function - * @return a unary operator that provides its input value as the result + * @param the type of the input and output of the operator + * @return a unary operator that always returns its input argument */ static UnaryOperator identity() { return t -> t; diff --git a/src/share/classes/java/util/function/package-info.java b/src/share/classes/java/util/function/package-info.java --- a/src/share/classes/java/util/function/package-info.java +++ b/src/share/classes/java/util/function/package-info.java @@ -1,5 +1,5 @@ /* - * Copyright (c) 2011, 2013, Oracle and/or its affiliates. All rights reserved. + * Copyright (c) 2011, 2012, Oracle and/or its affiliates. All rights reserved. * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER. * * This code is free software; you can redistribute it and/or modify it @@ -25,56 +25,82 @@ /** * Functional interfaces provide target types for lambda expressions - * and method references. Each functional interface has a single abstract method + * and method references. Each functional interface has a single abstract + * method, called the functional method for that functional interface, * to which the lambda expression's parameter and return types are matched or - * adapted. Functional interfaces can provide a target type in multiple contexts, - * such as assignment context, method invocation, or cast context: + * adapted. Functional interfaces can provide a target type in multiple + * contexts, such as assignment context, method invocation, or cast context: * * 

{@code
+ *     // Assignment context
  *     Predicate p = String::isEmpty;
  *
+ *     // Method invocation context
  *     stream.filter(e -> e.getSize() > 10)...
  *
+ *     // Cast context
  *     stream.map((ToIntFunction) e -> e.getSize())...
  * }
* - *

The interfaces in this package are functional interfaces used by the JDK, - * and are available to be used by user code as well. While they do not identify - * a complete set of function shapes to which lambda expressions might be adapted, - * they provide enough to cover common requirements. + *

The interfaces in this package are general purpose functional interfaces + * used by the JDK, and are available to be used by user code as well. While + * they do not identify a complete set of function shapes to which lambda + * expressions might be adapted, they provide enough to cover common + * requirements. Other functional interfaces provided for specific purposes, + * such as {@link java.io.FileFilter}, are defined in the packages where they + * are used. * - *

The interfaces in this package are annotated with @{link FunctionalInterface}. - * This annotation is not a requirement for the compiler to recognize an interface - * as a functional interface, but merely an aid to capture design intent and enlist the - * help of the compiler in identifying accidental violations of design intent. + *

The interfaces in this package are annotated with + * {@link java.lang.FunctionalInterface}. This annotation is not a requirement + * for the compiler to recognize an interface as a functional interface, but + * merely an aid to capture design intent and enlist the help of the compiler in + * identifying accidental violations of design intent. * - *

The functional interfaces in this package follow an extensible naming convention, - * as follows: + *

Functional interfaces often represent abstract concepts like functions, + * actions, or predicates. In documenting functional interfaces, or referring + * to variables typed as functional interfaces, it is common to refer directly + * to those abstract concepts, for example using "this function" instead of + * "the function represented by this object". + * + *

The functional interfaces in this package follow an extensible naming + * convention, as follows: * *

    - *
  • There are several basic function shapes, including {@link java.util.function.Function} ({@code T -> R}), - * {@link java.util.function.Consumer} ({@code T -> void}), - * {@link java.util.function.Predicate} ({@code T -> boolean}), - * and {@link java.util.function.Supplier} ({@code () -> T}). + *
  • There are several basic function shapes, including + * {@link java.util.function.Function} (unary function from {@code T} to {@code R}), + * {@link java.util.function.Consumer} (unary function from {@code T} to {@code void}), + * {@link java.util.function.Predicate} (unary function from {@code T} to {@code boolean}), + * and {@link java.util.function.Supplier} (nilary function to {@code R}). *
    • - *
  • Function shapes have a natural arity based on how they are most commonly used. - * The basic shapes can be modified by an arity prefix to indicate a different arity, - * such as {@link java.util.function.BiFunction} ({@code (T, U) -> R}). + * + *
  • Function shapes have a natural arity based on how they are most + * commonly used. The basic shapes can be modified by an arity prefix to + * indicate a different arity, such as + * {@link java.util.function.BiFunction} (binary function from {@code T} and + * {@code U} to {@code R}). *
    • - *
  • There are additional derived function shapes which extend the basic function - * shapes, including {@link java.util.function.UnaryOperator} (extends {@code Function}) and - * {@link java.util.function.BinaryOperator} (extends {@code BiFunction}). + * + *
  • There are additional derived function shapes which extend the basic + * function shapes, including {@link java.util.function.UnaryOperator} + * (extends {@code Function}) and {@link java.util.function.BinaryOperator} + * (extends {@code BiFunction}). *
    • - *
  • Type parameters of functional interfaces can be specialized to primitives with - * additional type prefixes. To specialize the return type for a type that has both - * generic return type and generic arguments, we prefix {@code ToXxx}, as in - * {@link java.util.function.ToIntFunction}. Otherwise, type arguments are specialized left-to-right, - * as in {@link java.util.function.DoubleConsumer} or {@link java.util.function.ObjIntConsumer}. - * (The type prefix {@code Obj} is used to indicate that we don't want to specialize this parameter, - * but want to move on to the next parameter.) These schemes can be combined as in {@code IntToDoubleFunction}. + * + *
  • Type parameters of functional interfaces can be specialized to + * primitives with additional type prefixes. To specialize the return type + * for a type that has both generic return type and generic arguments, we + * prefix {@code ToXxx}, as in {@link java.util.function.ToIntFunction}. + * Otherwise, type arguments are specialized left-to-right, as in + * {@link java.util.function.DoubleConsumer} + * or {@link java.util.function.ObjIntConsumer}. + * (The type prefix {@code Obj} is used to indicate that we don't want to + * specialize this parameter, but want to move on to the next parameter, + * as in {@link java.util.function.ObjIntConsumer}.) + * These schemes can be combined, as in {@code IntToDoubleFunction}. *
    • - *
  • If there are specialization prefixes for all arguments, the arity prefix may be left - * out (as in {@link java.util.function.ObjIntConsumer}). + * + *
  • If there are specialization prefixes for all arguments, the arity + * prefix may be left out (as in {@link java.util.function.ObjIntConsumer}). *
    • *
*