stan/jdk-24
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

8019840: Spec updates for java.util.function

Browse Source 
Reviewed-by: mduigou, chegar
This commit is contained in:
Brian Goetz 2013-07-23 13:20:11 -07:00 committed by Mike Duigou
parent e27ee62c84
commit 19ac28e61d
44 changed files with 824 additions and 643 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

49
jdk/src/share/classes/java/util/function/BiConsumer.java
View File

@ -27,13 +27,16 @@ package java.util.function;
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 @@ import java.util.Objects;
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}.
* 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.
*
* <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.
*
* @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);
};
}
}

39
jdk/src/share/classes/java/util/function/BiFunction.java
View File

@ -27,14 +27,15 @@ package java.util.function;
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 @@ import java.util.Objects;
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) {

79
jdk/src/share/classes/java/util/function/BiPredicate.java
View File

@ -27,11 +27,14 @@ package java.util.function;
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 @@ import java.util.Objects;
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.
*
* @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
* <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 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 @@ public interface BiPredicate<T, U> {
}
/**
* Returns a predicate which evaluates to {@code true} if either this
* predicate or the provided predicate evaluates to {@code true}. If this
* predicate returns {@code true} then the remaining predicate is not
* evaluated.
* Returns a composed predicate that represents a short-circuiting logical
* OR of this predicate and another. When evaluating the composed
* predicate, if this predicate is {@code true}, then the {@code other}
* predicate is not evaluated.
*
* @param p a predicate which will be logically-ORed with this predicate
* @return a new predicate which returns {@code true} if either predicate
* returns {@code true}
* @throws NullPointerException if p is null
* <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 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);
}
}

28
jdk/src/share/classes/java/util/function/BinaryOperator.java
View File

@ -28,42 +28,48 @@ import java.util.Objects;
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;
}

14
jdk/src/share/classes/java/util/function/BooleanSupplier.java
View File

@ -26,8 +26,14 @@ package java.util.function;
/**
* 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 @@ package java.util.function;
public interface BooleanSupplier {
/**
* Returns a {@code boolean} value.
* Gets a result.
*
* @return a {@code boolean} value
* @return a result
*/
boolean getAsBoolean();
}

42
jdk/src/share/classes/java/util/function/Consumer.java
View File

@ -27,11 +27,14 @@ package java.util.function;
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 @@ import java.util.Objects;
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}.
* 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.
*
* <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.
*
* @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); };
}
}

20
jdk/src/share/classes/java/util/function/DoubleBinaryOperator.java
View File

@ -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);
}

41
jdk/src/share/classes/java/util/function/DoubleConsumer.java
View File

@ -27,11 +27,14 @@ package java.util.function;
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 @@ import java.util.Objects;
public interface DoubleConsumer {
/**
* Accept an input value.
* Performs this operation on the given argument.
*
* @param value the input value
* @param value the input argument
*/
void accept(double value);
/**
* Returns a {@code DoubleConsumer} which performs, in sequence, the operation
* represented by this object followed by the operation represented by
* another {@code DoubleConsumer}.
* Returns a composed {@code DoubleConsumer} that performs, in sequence, this
* operation followed by the {@code after} operation. If performing either
* operation throws an exception, it is relayed to the caller of the
* composed operation. If performing this operation throws an exception,
* the {@code after} operation will not be performed.
*
* <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.
*
* @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); };
}
}

13
jdk/src/share/classes/java/util/function/DoubleFunction.java
View File

@ -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 @@ package java.util.function;
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);

80
jdk/src/share/classes/java/util/function/DoublePredicate.java
View File

@ -27,9 +27,12 @@ package java.util.function;
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 @@ import java.util.Objects;
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 @@ public interface DoublePredicate {
}
/**
* 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);
}
}

14
jdk/src/share/classes/java/util/function/DoubleSupplier.java
View File

@ -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 @@ package java.util.function;
public interface DoubleSupplier {
/**
* Returns a {@code double} value.
* Gets a result.
*
* @return a {@code double} value
* @return a result
*/
double getAsDouble();
}

16
jdk/src/share/classes/java/util/function/DoubleToIntFunction.java
View File

@ -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);
}

16
jdk/src/share/classes/java/util/function/DoubleToLongFunction.java
View File

@ -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);
}

52
jdk/src/share/classes/java/util/function/DoubleUnaryOperator.java
View File

@ -27,9 +27,12 @@ package java.util.function;
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 @@ import java.util.Objects;
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 @@ public interface DoubleUnaryOperator {
}
/**
* 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 @@ public interface DoubleUnaryOperator {
}
/**
* 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;

59
jdk/src/share/classes/java/util/function/Function.java
View File

@ -27,12 +27,13 @@ package java.util.function;
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 @@ import java.util.Objects;
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 @@ public interface Function<T, R> {
}
/**
* 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 @@ public interface Function<T, R> {
}
/**
* 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;

20
jdk/src/share/classes/java/util/function/IntBinaryOperator.java
View File

@ -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);
}

43
jdk/src/share/classes/java/util/function/IntConsumer.java
View File

@ -27,10 +27,13 @@ package java.util.function;
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 @@ import java.util.Objects;
public interface IntConsumer {
/**
* Accept an input value.
* Performs this operation on the given argument.
*
* @param value the input value
* @param value the input argument
*/
void accept(int value);
/**
* Returns an {@code IntConsumer} which performs, in sequence, the operation
* represented by this object followed by the operation represented by
* another {@code IntConsumer}.
* Returns a composed {@code IntConsumer} that performs, in sequence, this
* operation followed by the {@code after} operation. If performing either
* operation throws an exception, it is relayed to the caller of the
* composed operation. If performing this operation throws an exception,
* the {@code after} operation will not be performed.
*
* <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.
*
* @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); };
}
}

15
jdk/src/share/classes/java/util/function/IntFunction.java
View File

@ -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 @@ package java.util.function;
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);

79
jdk/src/share/classes/java/util/function/IntPredicate.java
View File

@ -27,8 +27,12 @@ package java.util.function;
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 @@ import java.util.Objects;
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 @@ public interface IntPredicate {
}
/**
* 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);
}
}

14
jdk/src/share/classes/java/util/function/IntSupplier.java
View File

@ -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 @@ package java.util.function;
public interface IntSupplier {
/**
* Returns an {@code int} value.
* Gets a result.
*
* @return an {@code int} value
* @return a result
*/
int getAsInt();
}

16
jdk/src/share/classes/java/util/function/IntToDoubleFunction.java
View File

@ -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);
}

16
jdk/src/share/classes/java/util/function/IntToLongFunction.java
View File

@ -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);
}

52
jdk/src/share/classes/java/util/function/IntUnaryOperator.java
View File

@ -27,9 +27,12 @@ package java.util.function;
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 @@ import java.util.Objects;
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 @@ public interface IntUnaryOperator {
}
/**
* 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 @@ public interface IntUnaryOperator {
}
/**
* 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;

20
jdk/src/share/classes/java/util/function/LongBinaryOperator.java
View File

@ -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);
}

43
jdk/src/share/classes/java/util/function/LongConsumer.java
View File

@ -27,10 +27,13 @@ package java.util.function;
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 @@ import java.util.Objects;
public interface LongConsumer {
/**
* Accept an input value.
* Performs this operation on the given argument.
*
* @param value the input value
* @param value the input argument
*/
void accept(long value);
/**
* Returns a {@code LongConsumer} which performs, in sequence, the operation
* represented by this object followed by the operation represented by
* another {@code LongConsumer}.
* Returns a composed {@code LongConsumer} that performs, in sequence, this
* operation followed by the {@code after} operation. If performing either
* operation throws an exception, it is relayed to the caller of the
* composed operation. If performing this operation throws an exception,
* the {@code after} operation will not be performed.
*
* <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.
*
* @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); };
}
}

13
jdk/src/share/classes/java/util/function/LongFunction.java
View File

@ -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 @@ package java.util.function;
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);

78
jdk/src/share/classes/java/util/function/LongPredicate.java
View File

@ -27,8 +27,12 @@ package java.util.function;
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 @@ import java.util.Objects;
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 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}
* @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 @@ public interface LongPredicate {
}
/**
* 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);
}
}

14
jdk/src/share/classes/java/util/function/LongSupplier.java
View File

@ -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 @@ package java.util.function;
public interface LongSupplier {
/**
* Returns a {@code long} value.
* Gets a result.
*
* @return a {@code long} value
* @return a result
*/
long getAsLong();
}

16
jdk/src/share/classes/java/util/function/LongToDoubleFunction.java
View File

@ -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);
}

16
jdk/src/share/classes/java/util/function/LongToIntFunction.java
View File

@ -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);
}

52
jdk/src/share/classes/java/util/function/LongUnaryOperator.java
View File

@ -27,9 +27,12 @@ package java.util.function;
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 @@ import java.util.Objects;
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 @@ public interface LongUnaryOperator {
}
/**
* 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 @@ public interface LongUnaryOperator {
}
/**
* 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;

20
jdk/src/share/classes/java/util/function/ObjDoubleConsumer.java
View File

@ -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 @@ package java.util.function;
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);
}

20
jdk/src/share/classes/java/util/function/ObjIntConsumer.java
View File

@ -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 @@ package java.util.function;
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);
}

20
jdk/src/share/classes/java/util/function/ObjLongConsumer.java
View File

@ -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 @@ package java.util.function;
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);
}

99
jdk/src/share/classes/java/util/function/Predicate.java
View File

@ -27,9 +27,12 @@ package java.util.function;
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 @@ import java.util.Objects;
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.
*
* @return a new predicate who's result is always the opposite of this
* Returns a predicate that represents the logical negation 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);
}
}

15
jdk/src/share/classes/java/util/function/Supplier.java
View File

@ -25,10 +25,15 @@
package java.util.function;
/**
* A supplier of objects. The result objects are either created during the
* invocation of {@link #get} or by some prior action.
* Represents a supplier of results.
*
* @param <T> The type of objects returned by {@code get}
* <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 #get()}.
*
* @param <T> the type of results supplied by this supplier
*
* @since 1.8
*/
@ -36,9 +41,9 @@ package java.util.function;
public interface Supplier<T> {
/**
* Returns an object.
* Gets a result.
*
* @return an object
* @return a result
*/
T get();
}

22
jdk/src/share/classes/java/util/function/ToDoubleBiFunction.java
View File

@ -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 @@ package java.util.function;
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);
}

17
jdk/src/share/classes/java/util/function/ToDoubleFunction.java
View File

@ -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 @@ package java.util.function;
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);
}

22
jdk/src/share/classes/java/util/function/ToIntBiFunction.java
View File

@ -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 @@ package java.util.function;
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);
}

17
jdk/src/share/classes/java/util/function/ToIntFunction.java
View File

@ -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 @@ package java.util.function;
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);
}

22
jdk/src/share/classes/java/util/function/ToLongBiFunction.java
View File

@ -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 @@ package java.util.function;
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);
}

17
jdk/src/share/classes/java/util/function/ToLongFunction.java
View File

@ -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 @@ package java.util.function;
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);
}

15
jdk/src/share/classes/java/util/function/UnaryOperator.java
View File

@ -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 @@ package java.util.function;
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;

92
jdk/src/share/classes/java/util/function/package-info.java
View File

@ -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>
*