8019840: Spec updates for java.util.function
Reviewed-by: mduigou, chegar
Contributed-by: brian.goetz@oracle.com
--- a/jdk/src/share/classes/java/util/function/BiConsumer.java Mon Jul 22 12:59:09 2013 -0700
+++ b/jdk/src/share/classes/java/util/function/BiConsumer.java Tue Jul 23 13:20:11 2013 -0700
@@ -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 <T> the type of the first argument to the {@code accept} operation
- * @param <U> the type of the second argument to the {@code accept} operation
+ * <p>This is a <a href="package-summary.html">functional interface</a>
+ * whose functional method is {@link #accept(Object, Object)}.
+ *
+ * @param <T> the type of the first argument to the operation
+ * @param <U> the type of the second argument to the operation
*
* @see Consumer
* @since 1.8
@@ -42,35 +45,31 @@
public interface BiConsumer<T, U> {
/**
- * 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}.
- *
- * <p>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.
+ * 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.
*
- * @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<T, U> chain(BiConsumer<? super T, ? super U> other) {
- Objects.requireNonNull(other);
+ default BiConsumer<T, U> andThen(BiConsumer<? super T, ? super U> after) {
+ Objects.requireNonNull(after);
return (l, r) -> {
accept(l, r);
- other.accept(l, r);
+ after.accept(l, r);
};
}
}
--- a/jdk/src/share/classes/java/util/function/BiFunction.java Mon Jul 22 12:59:09 2013 -0700
+++ b/jdk/src/share/classes/java/util/function/BiFunction.java Tue Jul 23 13:20:11 2013 -0700
@@ -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 <T> the type of the first argument to the {@code apply} operation
- * @param <U> the type of the second argument to the {@code apply} operation
- * @param <R> the type of results returned by the {@code apply} operation
+ * <p>This is a <a href="package-summary.html">functional interface</a>
+ * whose functional method is {@link #apply(Object, Object)}.
+ *
+ * @param <T> the type of the first argument to the function
+ * @param <U> the type of the second argument to the function
+ * @param <R> the type of the result of the function
*
* @see Function
* @since 1.8
@@ -43,25 +44,25 @@
public interface BiFunction<T, U, R> {
/**
- * 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 <V> Type of output objects to the combined function. May be the
- * same type as {@code <T>}, {@code <U>} or {@code <R>}
- * @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 <V> 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 <V> BiFunction<T, U, V> andThen(Function<? super R, ? extends V> after) {
--- a/jdk/src/share/classes/java/util/function/BiPredicate.java Mon Jul 22 12:59:09 2013 -0700
+++ b/jdk/src/share/classes/java/util/function/BiPredicate.java Tue Jul 23 13:20:11 2013 -0700
@@ -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 <T> the type of the first argument to {@code test}
- * @param <U> the type of the second argument to {@code test}
+ * <p>This is a <a href="package-summary.html">functional interface</a>
+ * whose functional method is {@link #test(Object, Object)}.
+ *
+ * @param <T> the type of the first argument to the predicate
+ * @param <U> the type of the second argument the predicate
*
* @see Predicate
* @since 1.8
@@ -40,34 +43,41 @@
public interface BiPredicate<T, U> {
/**
- * 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.
+ *
+ * <p>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 BiPredicate<T, U> and(BiPredicate<? super T, ? super U> p) {
- Objects.requireNonNull(p);
- return (T t, U u) -> test(t, u) && p.test(t, u);
+ default BiPredicate<T, U> and(BiPredicate<? super T, ? super U> 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<T, U> 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.
+ *
+ * <p>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 BiPredicate<T, U> or(BiPredicate<? super T, ? super U> p) {
- Objects.requireNonNull(p);
- return (T t, U u) -> test(t, u) || p.test(t, u);
+ default BiPredicate<T, U> or(BiPredicate<? super T, ? super U> other) {
+ Objects.requireNonNull(other);
+ return (T t, U u) -> test(t, u) || other.test(t, u);
}
}
--- a/jdk/src/share/classes/java/util/function/BinaryOperator.java Mon Jul 22 12:59:09 2013 -0700
+++ b/jdk/src/share/classes/java/util/function/BinaryOperator.java Tue Jul 23 13:20:11 2013 -0700
@@ -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 <T> the type of operands to {@code apply} and of the result
+ * <p>This is a <a href="package-summary.html">functional interface</a>
+ * whose functional method is {@link #apply(Object, Object)}.
+ *
+ * @param <T> the type of the operands and result of the operator
*
* @see BiFunction
+ * @see UnaryOperator
* @since 1.8
*/
@FunctionalInterface
public interface BinaryOperator<T> extends BiFunction<T,T,T> {
/**
* Returns a {@link BinaryOperator} which returns the lesser of two elements
- * according to the specified {@code Comparator}
+ * according to the specified {@code Comparator}.
*
- * @param <T> the type of values to be compared and returned
- * @param comparator a {@code Comparator} for comparing the two values
+ * @param <T> 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<T> BinaryOperator<T> minBy(Comparator<? super T> comparator) {
+ public static <T> BinaryOperator<T> minBy(Comparator<? super T> 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 <T> the type of values to be compared and returned
- * @param comparator a {@code Comparator} for comparing the two values
+ * @param <T> 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<T> BinaryOperator<T> maxBy(Comparator<? super T> comparator) {
+ public static <T> BinaryOperator<T> maxBy(Comparator<? super T> comparator) {
Objects.requireNonNull(comparator);
return (a, b) -> comparator.compare(a, b) >= 0 ? a : b;
}
--- a/jdk/src/share/classes/java/util/function/BooleanSupplier.java Mon Jul 22 12:59:09 2013 -0700
+++ b/jdk/src/share/classes/java/util/function/BooleanSupplier.java Tue Jul 23 13:20:11 2013 -0700
@@ -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}.
+ *
+ * <p>There is no requirement that a new or distinct result be returned each
+ * time the supplier is invoked.
+ *
+ * <p>This is a <a href="package-summary.html">functional interface</a>
+ * 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();
}
--- a/jdk/src/share/classes/java/util/function/Consumer.java Mon Jul 22 12:59:09 2013 -0700
+++ b/jdk/src/share/classes/java/util/function/Consumer.java Tue Jul 23 13:20:11 2013 -0700
@@ -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 <T> The type of input objects to {@code accept}
+ * <p>This is a <a href="package-summary.html">functional interface</a>
+ * whose functional method is {@link #accept(Object)}.
+ *
+ * @param <T> the type of the input to the operation
*
* @since 1.8
*/
@@ -39,29 +42,26 @@
public interface Consumer<T> {
/**
- * 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}.
- *
- * <p>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.
+ * 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.
*
- * @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<T> chain(Consumer<? super T> other) {
- Objects.requireNonNull(other);
- return (T t) -> { accept(t); other.accept(t); };
+ default Consumer<T> andThen(Consumer<? super T> after) {
+ Objects.requireNonNull(after);
+ return (T t) -> { accept(t); after.accept(t); };
}
}
--- a/jdk/src/share/classes/java/util/function/DoubleBinaryOperator.java Mon Jul 22 12:59:09 2013 -0700
+++ b/jdk/src/share/classes/java/util/function/DoubleBinaryOperator.java Tue Jul 23 13:20:11 2013 -0700
@@ -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}.
+ *
+ * <p>This is a <a href="package-summary.html">functional interface</a>
+ * 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);
}
--- a/jdk/src/share/classes/java/util/function/DoubleConsumer.java Mon Jul 22 12:59:09 2013 -0700
+++ b/jdk/src/share/classes/java/util/function/DoubleConsumer.java Tue Jul 23 13:20:11 2013 -0700
@@ -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.
*
+ * <p>This is a <a href="package-summary.html">functional interface</a>
+ * 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}.
- *
- * <p>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.
+ * 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.
*
- * @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); };
}
}
--- a/jdk/src/share/classes/java/util/function/DoubleFunction.java Mon Jul 22 12:59:09 2013 -0700
+++ b/jdk/src/share/classes/java/util/function/DoubleFunction.java Tue Jul 23 13:20:11 2013 -0700
@@ -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 <R> the type of output objects from the function
+ * <p>This is a <a href="package-summary.html">functional interface</a>
+ * whose functional method is {@link #apply(double)}.
+ *
+ * @param <R> the type of the result of the function
*
* @see Function
* @since 1.8
@@ -38,9 +41,9 @@
public interface DoubleFunction<R> {
/**
- * 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);
--- a/jdk/src/share/classes/java/util/function/DoublePredicate.java Mon Jul 22 12:59:09 2013 -0700
+++ b/jdk/src/share/classes/java/util/function/DoublePredicate.java Tue Jul 23 13:20:11 2013 -0700
@@ -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}.
+ *
+ * <p>This is a <a href="package-summary.html">functional interface</a>
+ * 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.
*
- * <p>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.
+ * <p>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.
*
- * <p>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.
+ * <p>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);
}
}
--- a/jdk/src/share/classes/java/util/function/DoubleSupplier.java Mon Jul 22 12:59:09 2013 -0700
+++ b/jdk/src/share/classes/java/util/function/DoubleSupplier.java Tue Jul 23 13:20:11 2013 -0700
@@ -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}.
+ *
+ * <p>There is no requirement that a distinct result be returned each
+ * time the supplier is invoked.
+ *
+ * <p>This is a <a href="package-summary.html">functional interface</a>
+ * 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();
}
--- a/jdk/src/share/classes/java/util/function/DoubleToIntFunction.java Mon Jul 22 12:59:09 2013 -0700
+++ b/jdk/src/share/classes/java/util/function/DoubleToIntFunction.java Tue Jul 23 13:20:11 2013 -0700
@@ -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}.
+ *
+ * <p>This is a <a href="package-summary.html">functional interface</a>
+ * 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);
}
--- a/jdk/src/share/classes/java/util/function/DoubleToLongFunction.java Mon Jul 22 12:59:09 2013 -0700
+++ b/jdk/src/share/classes/java/util/function/DoubleToLongFunction.java Tue Jul 23 13:20:11 2013 -0700
@@ -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}.
+ *
+ * <p>This is a <a href="package-summary.html">functional interface</a>
+ * 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);
}
--- a/jdk/src/share/classes/java/util/function/DoubleUnaryOperator.java Mon Jul 22 12:59:09 2013 -0700
+++ b/jdk/src/share/classes/java/util/function/DoubleUnaryOperator.java Tue Jul 23 13:20:11 2013 -0700
@@ -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}.
+ *
+ * <p>This is a <a href="package-summary.html">functional interface</a>
+ * 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;
--- a/jdk/src/share/classes/java/util/function/Function.java Mon Jul 22 12:59:09 2013 -0700
+++ b/jdk/src/share/classes/java/util/function/Function.java Tue Jul 23 13:20:11 2013 -0700
@@ -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 <T> the type of the input to the {@code apply} operation
- * @param <R> the type of the result of the {@code apply} operation
+ * <p>This is a <a href="package-summary.html">functional interface</a>
+ * whose functional method is {@link #apply(Object)}.
+ *
+ * @param <T> the type of the input to the function
+ * @param <R> the type of the result of the function
*
* @since 1.8
*/
@@ -40,25 +41,27 @@
public interface Function<T, R> {
/**
- * 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 <V> type of input objects to the combined function. May be the
- * same type as {@code <T>} or {@code <R>}
- * @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 <V> 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 <V> Function<V, R> compose(Function<? super V, ? extends T> 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 <V> type of output objects to the combined function. May be the
- * same type as {@code <T>} or {@code <R>}
- * @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 <V> 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 <V> Function<T, V> andThen(Function<? super R, ? extends V> 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 <T> 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 <T> Function<T, T> identity() {
return t -> t;
--- a/jdk/src/share/classes/java/util/function/IntBinaryOperator.java Mon Jul 22 12:59:09 2013 -0700
+++ b/jdk/src/share/classes/java/util/function/IntBinaryOperator.java Tue Jul 23 13:20:11 2013 -0700
@@ -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}.
+ *
+ * <p>This is a <a href="package-summary.html">functional interface</a>
+ * 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);
}
--- a/jdk/src/share/classes/java/util/function/IntConsumer.java Mon Jul 22 12:59:09 2013 -0700
+++ b/jdk/src/share/classes/java/util/function/IntConsumer.java Tue Jul 23 13:20:11 2013 -0700
@@ -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.
+ *
+ * <p>This is a <a href="package-summary.html">functional interface</a>
+ * 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}.
- *
- * <p>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.
+ * 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.
*
- * @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); };
}
}
--- a/jdk/src/share/classes/java/util/function/IntFunction.java Mon Jul 22 12:59:09 2013 -0700
+++ b/jdk/src/share/classes/java/util/function/IntFunction.java Tue Jul 23 13:20:11 2013 -0700
@@ -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 <R> the type of output objects from the function
+ * <p>This is a <a href="package-summary.html">functional interface</a>
+ * whose functional method is {@link #apply(int)}.
+ *
+ * @param <R> the type of the result of the function
*
* @see Function
* @since 1.8
@@ -38,9 +41,9 @@
public interface IntFunction<R> {
/**
- * 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);
--- a/jdk/src/share/classes/java/util/function/IntPredicate.java Mon Jul 22 12:59:09 2013 -0700
+++ b/jdk/src/share/classes/java/util/function/IntPredicate.java Tue Jul 23 13:20:11 2013 -0700
@@ -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}.
+ *
+ * <p>This is a <a href="package-summary.html">functional interface</a>
+ * 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.
*
- * <p>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.
+ * <p>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.
*
- * <p>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.
+ * <p>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);
}
}
--- a/jdk/src/share/classes/java/util/function/IntSupplier.java Mon Jul 22 12:59:09 2013 -0700
+++ b/jdk/src/share/classes/java/util/function/IntSupplier.java Tue Jul 23 13:20:11 2013 -0700
@@ -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}.
+ *
+ * <p>There is no requirement that a distinct result be returned each
+ * time the supplier is invoked.
+ *
+ * <p>This is a <a href="package-summary.html">functional interface</a>
+ * 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();
}
--- a/jdk/src/share/classes/java/util/function/IntToDoubleFunction.java Mon Jul 22 12:59:09 2013 -0700
+++ b/jdk/src/share/classes/java/util/function/IntToDoubleFunction.java Tue Jul 23 13:20:11 2013 -0700
@@ -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}.
+ *
+ * <p>This is a <a href="package-summary.html">functional interface</a>
+ * 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);
}
--- a/jdk/src/share/classes/java/util/function/IntToLongFunction.java Mon Jul 22 12:59:09 2013 -0700
+++ b/jdk/src/share/classes/java/util/function/IntToLongFunction.java Tue Jul 23 13:20:11 2013 -0700
@@ -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}.
+ *
+ * <p>This is a <a href="package-summary.html">functional interface</a>
+ * 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);
}
--- a/jdk/src/share/classes/java/util/function/IntUnaryOperator.java Mon Jul 22 12:59:09 2013 -0700
+++ b/jdk/src/share/classes/java/util/function/IntUnaryOperator.java Tue Jul 23 13:20:11 2013 -0700
@@ -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}.
+ *
+ * <p>This is a <a href="package-summary.html">functional interface</a>
+ * 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;
--- a/jdk/src/share/classes/java/util/function/LongBinaryOperator.java Mon Jul 22 12:59:09 2013 -0700
+++ b/jdk/src/share/classes/java/util/function/LongBinaryOperator.java Tue Jul 23 13:20:11 2013 -0700
@@ -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}.
+ *
+ * <p>This is a <a href="package-summary.html">functional interface</a>
+ * 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);
}
--- a/jdk/src/share/classes/java/util/function/LongConsumer.java Mon Jul 22 12:59:09 2013 -0700
+++ b/jdk/src/share/classes/java/util/function/LongConsumer.java Tue Jul 23 13:20:11 2013 -0700
@@ -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.
+ *
+ * <p>This is a <a href="package-summary.html">functional interface</a>
+ * 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}.
- *
- * <p>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.
+ * 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.
*
- * @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); };
}
}
--- a/jdk/src/share/classes/java/util/function/LongFunction.java Mon Jul 22 12:59:09 2013 -0700
+++ b/jdk/src/share/classes/java/util/function/LongFunction.java Tue Jul 23 13:20:11 2013 -0700
@@ -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 <R> the type of output objects from the function
+ * <p>This is a <a href="package-summary.html">functional interface</a>
+ * whose functional method is {@link #apply(long)}.
+ *
+ * @param <R> the type of the result of the function
*
* @see Function
* @since 1.8
@@ -38,9 +41,9 @@
public interface LongFunction<R> {
/**
- * 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);
--- a/jdk/src/share/classes/java/util/function/LongPredicate.java Mon Jul 22 12:59:09 2013 -0700
+++ b/jdk/src/share/classes/java/util/function/LongPredicate.java Tue Jul 23 13:20:11 2013 -0700
@@ -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}.
+ *
+ * <p>This is a <a href="package-summary.html">functional interface</a>
+ * 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.
+ *
+ * <p>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.
*
- * <p>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.
- *
- * @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.
*
- * <p>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.
+ * <p>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);
}
}
--- a/jdk/src/share/classes/java/util/function/LongSupplier.java Mon Jul 22 12:59:09 2013 -0700
+++ b/jdk/src/share/classes/java/util/function/LongSupplier.java Tue Jul 23 13:20:11 2013 -0700
@@ -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}.
+ *
+ * <p>There is no requirement that a distinct result be returned each
+ * time the supplier is invoked.
+ *
+ * <p>This is a <a href="package-summary.html">functional interface</a>
+ * 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();
}
--- a/jdk/src/share/classes/java/util/function/LongToDoubleFunction.java Mon Jul 22 12:59:09 2013 -0700
+++ b/jdk/src/share/classes/java/util/function/LongToDoubleFunction.java Tue Jul 23 13:20:11 2013 -0700
@@ -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}.
+ *
+ * <p>This is a <a href="package-summary.html">functional interface</a>
+ * 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);
}
--- a/jdk/src/share/classes/java/util/function/LongToIntFunction.java Mon Jul 22 12:59:09 2013 -0700
+++ b/jdk/src/share/classes/java/util/function/LongToIntFunction.java Tue Jul 23 13:20:11 2013 -0700
@@ -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}.
+ *
+ * <p>This is a <a href="package-summary.html">functional interface</a>
+ * 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);
}
--- a/jdk/src/share/classes/java/util/function/LongUnaryOperator.java Mon Jul 22 12:59:09 2013 -0700
+++ b/jdk/src/share/classes/java/util/function/LongUnaryOperator.java Tue Jul 23 13:20:11 2013 -0700
@@ -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}.
+ *
+ * <p>This is a <a href="package-summary.html">functional interface</a>
+ * 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;
--- a/jdk/src/share/classes/java/util/function/ObjDoubleConsumer.java Mon Jul 22 12:59:09 2013 -0700
+++ b/jdk/src/share/classes/java/util/function/ObjDoubleConsumer.java Tue Jul 23 13:20:11 2013 -0700
@@ -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 <T> Type of reference argument to {@code accept()}.
+ * <p>This is a <a href="package-summary.html">functional interface</a>
+ * whose functional method is {@link #accept(Object, double)}.
+ *
+ * @param <T> the type of the object argument to the operation
*
* @see BiConsumer
* @since 1.8
@@ -39,10 +43,10 @@
public interface ObjDoubleConsumer<T> {
/**
- * 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);
}
--- a/jdk/src/share/classes/java/util/function/ObjIntConsumer.java Mon Jul 22 12:59:09 2013 -0700
+++ b/jdk/src/share/classes/java/util/function/ObjIntConsumer.java Tue Jul 23 13:20:11 2013 -0700
@@ -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 <T> Type of reference argument to {@code accept()}
+ * <p>This is a <a href="package-summary.html">functional interface</a>
+ * whose functional method is {@link #accept(Object, int)}.
+ *
+ * @param <T> the type of the object argument to the operation
*
* @see BiConsumer
* @since 1.8
@@ -39,10 +43,10 @@
public interface ObjIntConsumer<T> {
/**
- * 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);
}
--- a/jdk/src/share/classes/java/util/function/ObjLongConsumer.java Mon Jul 22 12:59:09 2013 -0700
+++ b/jdk/src/share/classes/java/util/function/ObjLongConsumer.java Tue Jul 23 13:20:11 2013 -0700
@@ -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 <T> Type of reference argument to {@code accept()}
+ * <p>This is a <a href="package-summary.html">functional interface</a>
+ * whose functional method is {@link #accept(Object, long)}.
+ *
+ * @param <T> the type of the object argument to the operation
*
* @see BiConsumer
* @since 1.8
@@ -39,10 +43,10 @@
public interface ObjLongConsumer<T> {
/**
- * 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);
}
--- a/jdk/src/share/classes/java/util/function/Predicate.java Mon Jul 22 12:59:09 2013 -0700
+++ b/jdk/src/share/classes/java/util/function/Predicate.java Tue Jul 23 13:20:11 2013 -0700
@@ -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 <T> the type of argument to {@code test}
+ * <p>This is a <a href="package-summary.html">functional interface</a>
+ * whose functional method is {@link #test(Object)}.
+ *
+ * @param <T> the type of the input to the predicate
*
* @since 1.8
*/
@@ -37,76 +40,80 @@
public interface Predicate<T> {
/**
- * 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.
*
- * <p>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.
+ * <p>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<T> and(Predicate<? super T> p) {
- Objects.requireNonNull(p);
- return (t) -> test(t) && p.test(t);
+ default Predicate<T> and(Predicate<? super T> 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<T> 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.
*
- * <p>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.
+ * <p>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<T> or(Predicate<? super T> p) {
- Objects.requireNonNull(p);
- return (t) -> test(t) || p.test(t);
+ default Predicate<T> or(Predicate<? super T> 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 <T> 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 <T> 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 <T> Predicate<T> isEqual(Object target) {
- return (null == target)
+ static <T> Predicate<T> isEqual(Object targetRef) {
+ return (null == targetRef)
? Objects::isNull
- : object -> target.equals(object);
+ : object -> targetRef.equals(object);
}
}
--- a/jdk/src/share/classes/java/util/function/Supplier.java Mon Jul 22 12:59:09 2013 -0700
+++ b/jdk/src/share/classes/java/util/function/Supplier.java Tue Jul 23 13:20:11 2013 -0700
@@ -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.
+ *
+ * <p>There is no requirement that a new or distinct result be returned each
+ * time the supplier is invoked.
*
- * @param <T> The type of objects returned by {@code get}
+ * <p>This is a <a href="package-summary.html">functional interface</a>
+ * whose functional method is {@link #get()}.
+ *
+ * @param <T> the type of results supplied by this supplier
*
* @since 1.8
*/
@@ -36,9 +41,9 @@
public interface Supplier<T> {
/**
- * Returns an object.
+ * Gets a result.
*
- * @return an object
+ * @return a result
*/
T get();
}
--- a/jdk/src/share/classes/java/util/function/ToDoubleBiFunction.java Mon Jul 22 12:59:09 2013 -0700
+++ b/jdk/src/share/classes/java/util/function/ToDoubleBiFunction.java Tue Jul 23 13:20:11 2013 -0700
@@ -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 <T> the type of the first argument to the {@code applyAsDouble}
- * operation.
- * @param <U> the type of the second argument to the {@code applyAsDouble}
- * operation.
+ * <p>This is a <a href="package-summary.html">functional interface</a>
+ * whose functional method is {@link #applyAsDouble(Object, Object)}.
+ *
+ * @param <T> the type of the first argument to the function
+ * @param <U> the type of the second argument to the function
*
* @see BiFunction
* @since 1.8
@@ -40,11 +42,11 @@
public interface ToDoubleBiFunction<T, U> {
/**
- * 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);
}
--- a/jdk/src/share/classes/java/util/function/ToDoubleFunction.java Mon Jul 22 12:59:09 2013 -0700
+++ b/jdk/src/share/classes/java/util/function/ToDoubleFunction.java Tue Jul 23 13:20:11 2013 -0700
@@ -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 <T> the type of input objects to the function
+ * <p>This is a <a href="package-summary.html">functional interface</a>
+ * whose functional method is {@link #applyAsDouble(Object)}.
+ *
+ * @param <T> the type of the input to the function
*
* @see Function
* @since 1.8
@@ -37,10 +40,10 @@
public interface ToDoubleFunction<T> {
/**
- * 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);
}
--- a/jdk/src/share/classes/java/util/function/ToIntBiFunction.java Mon Jul 22 12:59:09 2013 -0700
+++ b/jdk/src/share/classes/java/util/function/ToIntBiFunction.java Tue Jul 23 13:20:11 2013 -0700
@@ -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 <T> the type of the first argument to the {@code applyAsInt}
- * operation
- * @param <U> the type of the second argument to the {@code applyAsInt}
- * operation
+ * <p>This is a <a href="package-summary.html">functional interface</a>
+ * whose functional method is {@link #applyAsInt(Object, Object)}.
+ *
+ * @param <T> the type of the first argument to the function
+ * @param <U> the type of the second argument to the function
*
* @see BiFunction
* @since 1.8
@@ -40,11 +42,11 @@
public interface ToIntBiFunction<T, U> {
/**
- * 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);
}
--- a/jdk/src/share/classes/java/util/function/ToIntFunction.java Mon Jul 22 12:59:09 2013 -0700
+++ b/jdk/src/share/classes/java/util/function/ToIntFunction.java Tue Jul 23 13:20:11 2013 -0700
@@ -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 <T> the type of input objects to the function
+ * <p>This is a <a href="package-summary.html">functional interface</a>
+ * whose functional method is {@link #applyAsInt(Object)}.
+ *
+ * @param <T> the type of the input to the function
*
* @see Function
* @since 1.8
@@ -37,10 +40,10 @@
public interface ToIntFunction<T> {
/**
- * 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);
}
--- a/jdk/src/share/classes/java/util/function/ToLongBiFunction.java Mon Jul 22 12:59:09 2013 -0700
+++ b/jdk/src/share/classes/java/util/function/ToLongBiFunction.java Tue Jul 23 13:20:11 2013 -0700
@@ -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 <T> the type of the first argument to the {@code applyAsLong}
- * operation.
- * @param <U> the type of the second argument to the {@code applyAsLong}
- * operation.
+ * <p>This is a <a href="package-summary.html">functional interface</a>
+ * whose functional method is {@link #applyAsLong(Object, Object)}.
+ *
+ * @param <T> the type of the first argument to the function
+ * @param <U> the type of the second argument to the function
*
* @see BiFunction
* @since 1.8
@@ -40,11 +42,11 @@
public interface ToLongBiFunction<T, U> {
/**
- * 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);
}
--- a/jdk/src/share/classes/java/util/function/ToLongFunction.java Mon Jul 22 12:59:09 2013 -0700
+++ b/jdk/src/share/classes/java/util/function/ToLongFunction.java Tue Jul 23 13:20:11 2013 -0700
@@ -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 <T> the type of input objects to the function
+ * <p>This is a <a href="package-summary.html">functional interface</a>
+ * whose functional method is {@link #applyAsLong(Object)}.
+ *
+ * @param <T> the type of the input to the function
*
* @see Function
* @since 1.8
@@ -37,10 +40,10 @@
public interface ToLongFunction<T> {
/**
- * 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);
}
--- a/jdk/src/share/classes/java/util/function/UnaryOperator.java Mon Jul 22 12:59:09 2013 -0700
+++ b/jdk/src/share/classes/java/util/function/UnaryOperator.java Tue Jul 23 13:20:11 2013 -0700
@@ -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 <T> the type of operand to {@code apply} and of the result
+ * <p>This is a <a href="package-summary.html">functional interface</a>
+ * whose functional method is {@link #apply(Object)}.
+ *
+ * @param <T> the type of the operand and result of the operator
*
* @see Function
* @since 1.8
@@ -38,10 +41,10 @@
public interface UnaryOperator<T> extends Function<T, T> {
/**
- * Returns a unary operator that provides its input value as the result.
+ * Returns a unary operator that always returns its input argument.
*
- * @param <T> the type of the input and output objects to the function
- * @return a unary operator that provides its input value as the result
+ * @param <T> the type of the input and output of the operator
+ * @return a unary operator that always returns its input argument
*/
static <T> UnaryOperator<T> identity() {
return t -> t;
--- a/jdk/src/share/classes/java/util/function/package-info.java Mon Jul 22 12:59:09 2013 -0700
+++ b/jdk/src/share/classes/java/util/function/package-info.java Tue Jul 23 13:20:11 2013 -0700
@@ -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 @@
/**
* <em>Functional interfaces</em> 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 <em>functional method</em> 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:
*
* <pre>{@code
+ * // Assignment context
* Predicate<String> p = String::isEmpty;
*
+ * // Method invocation context
* stream.filter(e -> e.getSize() > 10)...
*
+ * // Cast context
* stream.map((ToIntFunction) e -> e.getSize())...
* }</pre>
*
- * <p>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.
+ * <p>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.
*
- * <p>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.
+ * <p>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.
*
- * <p>The functional interfaces in this package follow an extensible naming convention,
- * as follows:
+ * <p>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".
+ *
+ * <p>The functional interfaces in this package follow an extensible naming
+ * convention, as follows:
*
* <ul>
- * <li>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}).
+ * <li>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}).
* </li>
- * <li>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}).
+ *
+ * <li>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}).
* </li>
- * <li>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}).
+ *
+ * <li>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}).
* </li>
- * <li>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}.
+ *
+ * <li>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}.
* </li>
- * <li>If there are specialization prefixes for all arguments, the arity prefix may be left
- * out (as in {@link java.util.function.ObjIntConsumer}).
+ *
+ * <li>If there are specialization prefixes for all arguments, the arity
+ * prefix may be left out (as in {@link java.util.function.ObjIntConsumer}).
* </li>
* </ul>
*