/*
 * Licensed to the Apache Software Foundation (ASF) under one or more
 * contributor license agreements.  See the NOTICE file distributed with
 * this work for additional information regarding copyright ownership.
 * The ASF licenses this file to You under the Apache License, Version 2.0
 * (the "License"); you may not use this file except in compliance with
 * the License.  You may obtain a copy of the License at
 *
 *      https://www.apache.org/licenses/LICENSE-2.0
 *
 * Unless required by applicable law or agreed to in writing, software
 * distributed under the License is distributed on an "AS IS" BASIS,
 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
 * See the License for the specific language governing permissions and
 * limitations under the License.
 */

package org.apache.commons.statistics.distribution;

import java.util.Objects;
import java.util.function.Supplier;
import org.apache.commons.numbers.core.Precision;

/**
 * Creates instances of {@link DoubleTolerance}.
 *
 * <p>Floating-point comparisons are based on
 * {@link Precision org.apache.commons.numbers.core.Precision}.
 *
 * <p>This class is public and has public methods to allow testing within the other modules.
 */
public final class DoubleTolerances {
    /** A tolerance for numerical equality. This is immutable. */
    private static final DoubleTolerance EQUALS = new AbstractDoubleTolerance() {
        @Override
        public boolean test(double a, double b) {
            return Double.doubleToLongBits(a) == Double.doubleToLongBits(b);
        }

        @Override
        public String get() {
            return "exact";
        }
    };

    /** No instances. */
    private DoubleTolerances() {}

    /**
     * Creates a {@link DoubleTolerance} instance that uses exact binary equality.
     *
     * <p>Notes:
     * <ul>
     * <li>{@code 0.0} and {@code -0.0} are not considered equal.
     * <li>NaNs are considered equal.
     * </ul>
     *
     * @return an instance.
     * @see Double#equals(Object)
     * @see Double#doubleToLongBits(double)
     */
    public static DoubleTolerance equals() {
        return EQUALS;
    }

    /**
     * Creates a {@link DoubleTolerance} instance that uses the given range of allowed
     * error (inclusive) for determining equality.
     *
     * <p>Notes:
     * <ul>
     * <li>Two float numbers are considered equal if there are {@code (maxUlps - 1)}
     * (or fewer) floating point numbers between them. Use {@code maxUlps = 0} for
     * numerical equality.
     * <li>NaNs are considered equal.
     * <li>{@code 0.0} and {@code -0.0} are considered equal when {@code maxUlps = 0}.
     * </ul>
     *
     * <p>Use of this method with {@code maxUlps = 0} is slower than using {@link #equals()}
     * for binary equality. The results are identical with the exception that {@code 0.0} and
     * {@code -0.0} are considered equal.
     *
     * @param maxUlps {@code (maxUlps - 1)} is the number of floating point
     * values between {@code x} and {@code y}.
     * @return a new instance.
     * @throws IllegalArgumentException if {@code eps < 0} or is not finite
     * @see Precision#equalsIncludingNaN(double, double, int)
     */
    public static DoubleTolerance ulps(final int maxUlps) {
        return new AbstractDoubleTolerance() {
            @Override
            public boolean test(double a, double b) {
                return Precision.equalsIncludingNaN(a, b, maxUlps);
            }

            @Override
            public String get() {
                return "ulp=" + maxUlps;
            }
        };
    }

    /**
     * Creates a {@link DoubleTolerance} instance that uses the given absolute epsilon
     * value for determining equality.
     *
     * <p>Notes:
     * <ul>
     * <li>Two numbers are considered equal if there are 0
     * floating point numbers between them, i.e. two adjacent
     * floating point numbers are considered equal.
     * <li>NaNs are considered equal.
     * </ul>
     *
     * <p>Use of this method with {@code eps = 0.0} is not recommended as neighbouring
     * floating points numbers are considered equal. Consider using {@link #equals()}
     * for binary equality or {@link #ulps(int)} with {@code ulps=0} for numerical equality.
     *
     * @param eps Value to use for determining equality.
     * @return a new instance.
     * @throws IllegalArgumentException if {@code eps < 0} or is not finite
     * @see Precision#equalsIncludingNaN(double, double, double)
     */
    public static DoubleTolerance absolute(final double eps) {
        if (!Double.isFinite(eps) ||
            eps < 0d) {
            throw new IllegalArgumentException("Invalid epsilon value: " + eps);
        }

        return new AbstractDoubleTolerance() {
            @Override
            public boolean test(double a, double b) {
                return Precision.equalsIncludingNaN(a, b, eps);
            }

            @Override
            public String get() {
                return "abs=" + eps;
            }
        };
    }

    /**
     * Creates a {@link DoubleTolerance} instance that uses the given relative epsilon
     * value for determining equality.
     *
     * <p>Notes:
     * <ul>
     * <li>Two numbers are considered equal if there are 0
     * floating point numbers between them, i.e. two adjacent
     * floating point numbers are considered equal; or
     * the relative difference between them is less than or equal
     * to the given tolerance.
     * <li>NaNs are <strong>not</strong> considered equal.
     * <li>The relative tolerance instance is symmetric; it evaluates the same for
     * {@code (a, b)} or {@code (b, a)}.
     * </ul>
     *
     * <p>Use of this method with {@code eps = 0.0} is not recommended as neighbouring
     * floating points numbers are considered equal. Consider using {@link #equals()}
     * for binary equality or {@link #ulps(int)} with {@code ulps=0} for numerical equality.
     *
     * @param eps Value to use for determining equality.
     * @return a new instance.
     * @throws IllegalArgumentException if {@code eps < 0} or is not finite
     * @see Precision#equalsIncludingNaN(double, double, double)
     */
    public static DoubleTolerance relative(final double eps) {
        if (!Double.isFinite(eps) ||
            eps < 0d) {
            throw new IllegalArgumentException("Invalid epsilon value: " + eps);
        }

        return new AbstractDoubleTolerance() {
            @Override
            public boolean test(double a, double b) {
                return Precision.equalsWithRelativeTolerance(a, b, eps);
            }

            @Override
            public String get() {
                return "rel=" + eps;
            }
        };
    }

    /**
     * Custom implementation of the DoubleTolerance interface to allow message formatting
     * in assertions using {@link Supplier Supplier<String>}.
     */
    abstract static class AbstractDoubleTolerance implements DoubleTolerance, Supplier<String> {
        @Override
        public DoubleTolerance and(DoubleTolerance other) {
            return new DoubleAndTolerance(this, other);
        }

        @Override
        public DoubleTolerance negate() {
            return new DoubleNegateTolerance(this);
        }

        @Override
        public DoubleTolerance or(DoubleTolerance other) {
            return new DoubleOrTolerance(this, other);
        }

        @Override
        public String toString() {
            // This is overridden so that the tolerance is converted into a human readable
            // string using its description. For example this is used by JUnit to display
            // a DoubleTolerance argument for a ParameterizedTest.
            return get();
        }
    }

    /**
     * Represents a logical {@code And} of two tolerances, each tolerance testing the two
     * input values.
     *
     * <p>Supports a description {@link Supplier} for a {@link String}.
     */
    static class DoubleAndTolerance extends AbstractDoubleTolerance {
        /** The first tolerance. */
        private final DoubleTolerance tolerance1;
        /** The second tolerance. */
        private final DoubleTolerance tolerance2;

        /**
         * @param tolerance1 The first tolerance
         * @param tolerance2 The second tolerance
         */
        DoubleAndTolerance(DoubleTolerance tolerance1, DoubleTolerance tolerance2) {
            this.tolerance1 = Objects.requireNonNull(tolerance1, "Tolerance 1 is null");
            this.tolerance2 = Objects.requireNonNull(tolerance2, "Tolerance 2 is null");
        }

        @Override
        public boolean test(double value1, double value2) {
            return tolerance1.test(value1, value2) && tolerance2.test(value1, value2);
        }

        @Override
        public String get() {
            return StringUtils.andToString(tolerance1, tolerance2);
        }
    }

    /**
     * Represents a logical {@code Or} of two tolerances, each tolerance testing the two
     * input values.
     *
     * <p>Supports a description {@link Supplier} for a {@link String}.
     */
    static class DoubleOrTolerance extends AbstractDoubleTolerance {
        /** The first tolerance. */
        private final DoubleTolerance tolerance1;
        /** The second tolerance. */
        private final DoubleTolerance tolerance2;

        /**
         * @param tolerance1 The first tolerance
         * @param tolerance2 The second tolerance
         */
        DoubleOrTolerance(DoubleTolerance tolerance1, DoubleTolerance tolerance2) {
            this.tolerance1 = Objects.requireNonNull(tolerance1, "Tolerance 1 is null");
            this.tolerance2 = Objects.requireNonNull(tolerance2, "Tolerance 2 is null");
        }

        @Override
        public boolean test(double value1, double value2) {
            return tolerance1.test(value1, value2) || tolerance2.test(value1, value2);
        }

        @Override
        public String get() {
            return StringUtils.orToString(tolerance1, tolerance2);
        }
    }

    /**
     * Represents a negation of a tolerance including the string representation using
     * {@link Supplier} for a {@link String}.
     */
    static class DoubleNegateTolerance extends AbstractDoubleTolerance {
        /** The tolerance. */
        private final DoubleTolerance tolerance;

        /**
         * @param tolerance The tolerance
         */
        DoubleNegateTolerance(DoubleTolerance tolerance) {
            this.tolerance = Objects.requireNonNull(tolerance, "Tolerance is null");
        }

        @Override
        public boolean test(double value1, double value2) {
            return !tolerance.test(value1, value2);
        }

        @Override
        public DoubleTolerance negate() {
            // Back to the original
            return tolerance;
        }

        @Override
        public String get() {
            return StringUtils.negateToString(tolerance);
        }
    }
}
