1 /*
2 * Licensed to the Apache Software Foundation (ASF) under one or more
3 * contributor license agreements. See the NOTICE file distributed with
4 * this work for additional information regarding copyright ownership.
5 * The ASF licenses this file to You under the Apache License, Version 2.0
6 * (the "License"); you may not use this file except in compliance with
7 * the License. You may obtain a copy of the License at
8 *
9 * http://www.apache.org/licenses/LICENSE-2.0
10 *
11 * Unless required by applicable law or agreed to in writing, software
12 * distributed under the License is distributed on an "AS IS" BASIS,
13 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
14 * See the License for the specific language governing permissions and
15 * limitations under the License.
16 */
17
18 package org.apache.commons.statistics.distribution;
19
20 import java.util.Objects;
21
22 /**
23 * Represents a tolerance predicate (boolean-valued function) of two {@code double}-valued
24 * argument. This is the {@code double}-consuming primitive type specialization
25 * of {@link java.util.function.BiPredicate BiPredicate}.
26 *
27 * <p>This interface is intended for comparing outputs of a computation where floating
28 * point errors may have occurred.
29 */
30 @FunctionalInterface
31 interface DoubleTolerance {
32 /**
33 * Evaluates this tolerance predicate on the given arguments.
34 *
35 * @param a the first input argument
36 * @param b the second input argument
37 * @return {@code true} if the input arguments match the tolerance predicate,
38 * otherwise {@code false}
39 */
40 boolean test(double a, double b);
41
42 /**
43 * Returns a composed tolerance predicate that represents a short-circuiting logical
44 * AND of this tolerance predicate and another. When evaluating the composed
45 * tolerance predicate, if this tolerance predicate is {@code false}, then the {@code other}
46 * tolerance predicate is not evaluated.
47 *
48 * <p>Any exceptions thrown during evaluation of either tolerance predicate are relayed
49 * to the caller; if evaluation of this tolerance predicate throws an exception, the
50 * {@code other} tolerance predicate will not be evaluated.
51 *
52 * @param other a tolerance predicate that will be logically-ANDed with this
53 * tolerance predicate
54 * @return a composed tolerance predicate that represents the short-circuiting logical
55 * AND of this tolerance predicate and the {@code other} tolerance predicate
56 * @throws NullPointerException if other is null
57 */
58 default DoubleTolerance and(DoubleTolerance other) {
59 Objects.requireNonNull(other);
60 return (a, b) -> test(a, b) && other.test(a, b);
61 }
62
63 /**
64 * Returns a tolerance predicate that represents the logical negation of this
65 * tolerance predicate.
66 *
67 * @return a tolerance predicate that represents the logical negation of this
68 * tolerance predicate
69 */
70 default DoubleTolerance negate() {
71 return (a, b) -> !test(a, b);
72 }
73
74 /**
75 * Returns a composed tolerance predicate that represents a short-circuiting logical
76 * OR of this tolerance predicate and another. When evaluating the composed
77 * tolerance predicate, if this tolerance predicate is {@code true}, then the {@code other}
78 * tolerance predicate is not evaluated.
79 *
80 * <p>Any exceptions thrown during evaluation of either tolerance predicate are relayed
81 * to the caller; if evaluation of this tolerance predicate throws an exception, the
82 * {@code other} tolerance predicate will not be evaluated.
83 *
84 * @param other a tolerance predicate that will be logically-ORed with this
85 * tolerance predicate
86 * @return a composed tolerance predicate that represents the short-circuiting logical
87 * OR of this tolerance predicate and the {@code other} tolerance predicate
88 * @throws NullPointerException if other is null
89 */
90 default DoubleTolerance or(DoubleTolerance other) {
91 Objects.requireNonNull(other);
92 return (a, b) -> test(a, b) || other.test(a, b);
93 }
94 }