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 * https://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 * <p>This interface is public and has public methods to allow testing within the other modules.
31 */
32 @FunctionalInterface
33 public interface DoubleTolerance {
34 /**
35 * Evaluates this tolerance predicate on the given arguments.
36 *
37 * @param a the first input argument
38 * @param b the second input argument
39 * @return {@code true} if the input arguments match the tolerance predicate,
40 * otherwise {@code false}
41 */
42 boolean test(double a, double b);
43
44 /**
45 * Returns a composed tolerance predicate that represents a short-circuiting logical
46 * AND of this tolerance predicate and another. When evaluating the composed
47 * tolerance predicate, if this tolerance predicate is {@code false}, then the {@code other}
48 * tolerance predicate is not evaluated.
49 *
50 * <p>Any exceptions thrown during evaluation of either tolerance predicate are relayed
51 * to the caller; if evaluation of this tolerance predicate throws an exception, the
52 * {@code other} tolerance predicate will not be evaluated.
53 *
54 * @param other a tolerance predicate that will be logically-ANDed with this
55 * tolerance predicate
56 * @return a composed tolerance predicate that represents the short-circuiting logical
57 * AND of this tolerance predicate and the {@code other} tolerance predicate
58 * @throws NullPointerException if other is null
59 */
60 default DoubleTolerance and(DoubleTolerance other) {
61 Objects.requireNonNull(other);
62 return (a, b) -> test(a, b) && other.test(a, b);
63 }
64
65 /**
66 * Returns a tolerance predicate that represents the logical negation of this
67 * tolerance predicate.
68 *
69 * @return a tolerance predicate that represents the logical negation of this
70 * tolerance predicate
71 */
72 default DoubleTolerance negate() {
73 return (a, b) -> !test(a, b);
74 }
75
76 /**
77 * Returns a composed tolerance predicate that represents a short-circuiting logical
78 * OR of this tolerance predicate and another. When evaluating the composed
79 * tolerance predicate, if this tolerance predicate is {@code true}, then the {@code other}
80 * tolerance predicate is not evaluated.
81 *
82 * <p>Any exceptions thrown during evaluation of either tolerance predicate are relayed
83 * to the caller; if evaluation of this tolerance predicate throws an exception, the
84 * {@code other} tolerance predicate will not be evaluated.
85 *
86 * @param other a tolerance predicate that will be logically-ORed with this
87 * tolerance predicate
88 * @return a composed tolerance predicate that represents the short-circuiting logical
89 * OR of this tolerance predicate and the {@code other} tolerance predicate
90 * @throws NullPointerException if other is null
91 */
92 default DoubleTolerance or(DoubleTolerance other) {
93 Objects.requireNonNull(other);
94 return (a, b) -> test(a, b) || other.test(a, b);
95 }
96 }