src/share/classes/java/util/function/LongPredicate.java

Print this page
rev 7675 : 8019840: Spec updates for java.util.function
Reviewed-by: mduigou
Contributed-by: brian.goetz@oracle.com

@@ -25,72 +25,80 @@
 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
  */
 @FunctionalInterface
 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.
-     *
-     * <p>Any exceptions thrown by either {@code test} method are relayed
-     * to the caller; if performing first operation throws an exception, the
-     * second operation will not be performed.
-     *
-     * @param p a predicate which will be logically-ANDed with this predicate
-     * @return a new predicate which returns {@code true} only if both
-     * predicates return {@code true}
+     * Returns a composed predicate that represents a short-circuiting logical
+     * AND of this predicate and another.  When evaluating the composed
+     * predicate, if this predicate is {@code false}, then the {@code other}
+     * predicate is not evaluated.
+     *
+     * <p>Any exceptions thrown during evaluation of either predicate are relayed
+     * to the caller; if evaluation of this predicate throws an exception, the
+     * {@code other} predicate will not be evaluated.
+     *
+     * @param 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() {
         return (value) -> !test(value);
     }
 
     /**
-     * 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.
-     *
-     * <p>Any exceptions thrown by either {@code test} method are relayed
-     * to the caller; if performing first operation throws an exception, the
-     * second operation will not be performed.
-     *
-     * @param p a predicate which will be logically-ORed with this predicate
-     * @return a new predicate which returns {@code true} if either predicate
-     * returns {@code true}
-     * @throws NullPointerException if p is null
+     * Returns a composed predicate that represents a short-circuiting logical
+     * OR of this predicate and another.  When evaluating the composed
+     * predicate, if this predicate is {@code true}, then the {@code other}
+     * predicate is not evaluated.
+     *
+     * <p>Any exceptions thrown during evaluation of either predicate are relayed
+     * to the caller; if evaluation of this predicate throws an exception, the
+     * {@code other} predicate will not be evaluated.
+     *
+     * @param 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);
     }
 }