Package org.apache.commons.numbers.core

Class Precision

  • public final class Precision
extends Object
    Utilities for comparing numbers.

    • Nested Class Summary

      Nested Classes 
      Modifier and Type Class Description
      static interface  Precision.DoubleEquivalence
      Interface containing comparison operations for doubles that allow values to be considered equal even if they are not exactly equal.

    • Field Summary

      Fields 
      Modifier and Type Field Description
      static double EPSILON
      Largest double-precision floating-point number such that 1 + EPSILON is numerically equal to 1.
      static double SAFE_MIN
      Safe minimum, such that 1 / SAFE_MIN does not overflow.

    • Method Summary

      All Methods Static Methods Concrete Methods 
      Modifier and Type Method Description
      static int compareTo​(double x, double y, double eps)
      Compares two numbers given some amount of allowed error.
      static int compareTo​(double x, double y, int maxUlps)
      Compares two numbers given some amount of allowed error.
      static Precision.DoubleEquivalence doubleEquivalenceOfEpsilon​(double eps)
      Creates a Precision.DoubleEquivalence instance that uses the given epsilon value for determining equality.
      static boolean equals​(double x, double y)
      Returns true iff they are equal as defined by equals(x, y, 1).
      static boolean equals​(double x, double y, double eps)
      Returns true if there is no double value strictly between the arguments or the difference between them is within the range of allowed error (inclusive).
      static boolean equals​(double x, double y, int maxUlps)
      Returns true if the arguments are equal or within the range of allowed error (inclusive).
      static boolean equals​(float x, float y)
      Returns true iff they are equal as defined by equals(x, y, 1).
      static boolean equals​(float x, float y, float eps)
      Returns true if there is no float value strictly between the arguments or the difference between them is within the range of allowed error (inclusive).
      static boolean equals​(float x, float y, int maxUlps)
      Returns true if the arguments are equal or within the range of allowed error (inclusive).
      static boolean equalsIncludingNaN​(double x, double y)
      Returns true if the arguments are both NaN or they are equal as defined by equals(x, y, 1).
      static boolean equalsIncludingNaN​(double x, double y, double eps)
      Returns true if the arguments are both NaN, there are no double value strictly between the arguments or the difference between them is within the range of allowed error (inclusive).
      static boolean equalsIncludingNaN​(double x, double y, int maxUlps)
      Returns true if both arguments are NaN or if they are equal as defined by equals(x, y, maxUlps).
      static boolean equalsIncludingNaN​(float x, float y)
      Returns true if both arguments are NaN or they are equal as defined by equals(x, y, 1).
      static boolean equalsIncludingNaN​(float x, float y, float eps)
      Returns true if the arguments are both NaN, there are no float value strictly between the arguments or the difference between them is within the range of allowed error (inclusive).
      static boolean equalsIncludingNaN​(float x, float y, int maxUlps)
      Returns true if both arguments are NaN or if they are equal as defined by equals(x, y, maxUlps).
      static boolean equalsWithRelativeTolerance​(double x, double y, double eps)
      Returns true if there is no double value strictly between the arguments or the relative difference between them is less than or equal to the given tolerance.
      static double representableDelta​(double x, double delta)
      Computes a number close to delta with the property that (x + delta - x) is exactly machine-representable.
      static double round​(double x, int scale)
      Rounds the given value to the specified number of decimal places.
      static double round​(double x, int scale, RoundingMode roundingMode)
      Rounds the given value to the specified number of decimal places.

    • Field Detail

      • EPSILON

        public static final double EPSILON

        Largest double-precision floating-point number such that 1 + EPSILON is numerically equal to 1. This value is an upper bound on the relative error due to rounding real numbers to double precision floating-point numbers.

        In IEEE 754 arithmetic, this is 2-53.

        See Also:
        Machine epsilon

      • SAFE_MIN

        public static final double SAFE_MIN
        Safe minimum, such that 1 / SAFE_MIN does not overflow. In IEEE 754 arithmetic, this is also the smallest normalized number 2-1022.
        See Also:
        Double.MIN_NORMAL, Constant Field Values

    • Method Detail

      • compareTo

        public static int compareTo​(double x,
                            double y,
                            double eps)
        Compares two numbers given some amount of allowed error. The returned value is:
        • zero if considered equal using equals(x, y, eps)
        • negative if not equal and x < y
        • positive if not equal and x > y

        NaN values are handled as if using Double.compare(double, double) where the returned value is:

        • zero if NaN, NaN
        • negative if !NaN, NaN
        • positive if NaN, !NaN
        Parameters:
        x - First value.
        y - Second value.
        eps - Allowed error when checking for equality.
        Returns:
        0 if the value are considered equal, -1 if the first is smaller than the second, 1 if the first is larger than the second.
        See Also:
        equals(double, double, double)

      • compareTo

        public static int compareTo​(double x,
                            double y,
                            int maxUlps)
        Compares two numbers given some amount of allowed error. The returned value is:
        • zero if considered equal using equals(x, y, maxUlps)
        • negative if not equal and x < y
        • positive if not equal and x > y

        NaN values are handled as if using Double.compare(double, double) where the returned value is:

        • zero if NaN, NaN
        • negative if !NaN, NaN
        • positive if NaN, !NaN
        Parameters:
        x - First value.
        y - Second value.
        maxUlps - (maxUlps - 1) is the number of floating point values between x and y.
        Returns:
        0 if the value are considered equal, -1 if the first is smaller than the second, 1 if the first is larger than the second.
        See Also:
        equals(double, double, int)

      • equals

        public static boolean equals​(float x,
                             float y)
        Returns true iff they are equal as defined by equals(x, y, 1).
        Parameters:
        x - first value
        y - second value
        Returns:
        true if the values are equal.

      • equalsIncludingNaN

        public static boolean equalsIncludingNaN​(float x,
                                         float y)
        Returns true if both arguments are NaN or they are equal as defined by equals(x, y, 1).
        Parameters:
        x - first value
        y - second value
        Returns:
        true if the values are equal or both are NaN.

      • equals

        public static boolean equals​(float x,
                             float y,
                             float eps)
        Returns true if there is no float value strictly between the arguments or the difference between them is within the range of allowed error (inclusive). Returns false if either of the arguments is NaN.
        Parameters:
        x - first value
        y - second value
        eps - the amount of absolute error to allow.
        Returns:
        true if the values are equal or within range of each other.

      • equalsIncludingNaN

        public static boolean equalsIncludingNaN​(float x,
                                         float y,
                                         float eps)
        Returns true if the arguments are both NaN, there are no float value strictly between the arguments or the difference between them is within the range of allowed error (inclusive).
        Parameters:
        x - first value
        y - second value
        eps - the amount of absolute error to allow.
        Returns:
        true if the values are equal or within range of each other, or both are NaN.

      • equals

        public static boolean equals​(float x,
                             float y,
                             int maxUlps)
        Returns true if the arguments are equal or within the range of allowed error (inclusive). Returns false if either of the arguments is NaN.

        Two double numbers are considered equal if there are (maxUlps - 1) (or fewer) floating point numbers between them, i.e. two adjacent floating point numbers are considered equal.

        Adapted from Bruce Dawson.

        Parameters:
        x - first value
        y - second value
        maxUlps - (maxUlps - 1) is the number of floating point values between x and y.
        Returns:
        true if there are fewer than maxUlps floating point values between x and y.

      • equalsIncludingNaN

        public static boolean equalsIncludingNaN​(float x,
                                         float y,
                                         int maxUlps)
        Returns true if both arguments are NaN or if they are equal as defined by equals(x, y, maxUlps).
        Parameters:
        x - first value
        y - second value
        maxUlps - (maxUlps - 1) is the number of floating point values between x and y.
        Returns:
        true if both arguments are NaN or if there are less than maxUlps floating point values between x and y.

      • equals

        public static boolean equals​(double x,
                             double y)
        Returns true iff they are equal as defined by equals(x, y, 1).
        Parameters:
        x - first value
        y - second value
        Returns:
        true if the values are equal.

      • equalsIncludingNaN

        public static boolean equalsIncludingNaN​(double x,
                                         double y)
        Returns true if the arguments are both NaN or they are equal as defined by equals(x, y, 1).
        Parameters:
        x - first value
        y - second value
        Returns:
        true if the values are equal or both are NaN.

      • equals

        public static boolean equals​(double x,
                             double y,
                             double eps)
        Returns true if there is no double value strictly between the arguments or the difference between them is within the range of allowed error (inclusive). Returns false if either of the arguments is NaN.
        Parameters:
        x - First value.
        y - Second value.
        eps - Amount of allowed absolute error.
        Returns:
        true if the values are equal or within range of each other.

      • equalsWithRelativeTolerance

        public static boolean equalsWithRelativeTolerance​(double x,
                                                  double y,
                                                  double eps)
        Returns true if there is no double value strictly between the arguments or the relative difference between them is less than or equal to the given tolerance. Returns false if either of the arguments is NaN.
        Parameters:
        x - First value.
        y - Second value.
        eps - Amount of allowed relative error.
        Returns:
        true if the values are two adjacent floating point numbers or they are within range of each other.

      • equalsIncludingNaN

        public static boolean equalsIncludingNaN​(double x,
                                         double y,
                                         double eps)
        Returns true if the arguments are both NaN, there are no double value strictly between the arguments or the difference between them is within the range of allowed error (inclusive).
        Parameters:
        x - first value
        y - second value
        eps - the amount of absolute error to allow.
        Returns:
        true if the values are equal or within range of each other, or both are NaN.

      • equals

        public static boolean equals​(double x,
                             double y,
                             int maxUlps)
        Returns true if the arguments are equal or within the range of allowed error (inclusive). Returns false if either of the arguments is NaN.

        Two float numbers are considered equal if there are (maxUlps - 1) (or fewer) floating point numbers between them, i.e. two adjacent floating point numbers are considered equal.

        Adapted from Bruce Dawson.

        Parameters:
        x - first value
        y - second value
        maxUlps - (maxUlps - 1) is the number of floating point values between x and y.
        Returns:
        true if there are fewer than maxUlps floating point values between x and y.

      • equalsIncludingNaN

        public static boolean equalsIncludingNaN​(double x,
                                         double y,
                                         int maxUlps)
        Returns true if both arguments are NaN or if they are equal as defined by equals(x, y, maxUlps).
        Parameters:
        x - first value
        y - second value
        maxUlps - (maxUlps - 1) is the number of floating point values between x and y.
        Returns:
        true if both arguments are NaN or if there are less than maxUlps floating point values between x and y.

      • round

        public static double round​(double x,
                           int scale)
        Rounds the given value to the specified number of decimal places. The value is rounded using RoundingMode.HALF_UP.

        Note: This method is intended to act on the String representation of the double argument. See round(double, int, RoundingMode) for details.

        Parameters:
        x - Value to round.
        scale - Number of digits to the right of the decimal point.
        Returns:
        the rounded value.
        See Also:
        round(double, int, RoundingMode)

      • round

        public static double round​(double x,
                           int scale,
                           RoundingMode roundingMode)
        Rounds the given value to the specified number of decimal places. The value is rounded using the given rounding mode.

        If x is infinite or NaN, then the value of x is returned unchanged, regardless of the other parameters.

        Note

        Rounding of a 64-bit base-2 format double using a decimal representation may result in rounding during conversion to and/or from a base-10 representation.

        This method is intended to act on the String representation of the double argument, i.e. the closest representable decimal value. The argument is converted to a String (with possible rounding), rounding is performed on the decimal representation, and the resulting String is returned as the closest representable double.

        Conversion from base-2 to base-10 format uses the BigDecimal.valueOf(double) method. The alternative would be to use new BigDecimal(x) to construct an exact decimal representation of the value.

        Conversion from base-10 to base-2 format uses the equivalent of Double.parseDouble(String) to create the closest representable double to the decimal value.

        The following code demonstrates how to eliminate rounding during conversion to a decimal format. The return conversion to a double may be inexact: 

         double rounded = new BigDecimal(x).setScale(scale, roundingMode).doubleValue();

        Acting on the String representation of the double allows this method to return expected output when rounding double representations of decimal text. 

         Precision.round(39.245, 2) == 39.25
 Precision.round(30.095, 2) == 30.1
 Precision.round(30.645, 2) == 30.65
        Parameters:
        x - Value to round.
        scale - Number of digits to the right of the decimal point.
        roundingMode - Rounding mode as defined in BigDecimal.
        Returns:
        the rounded value.
        Throws:
        ArithmeticException - if roundingMode is RoundingMode.UNNECESSARY and the specified scaling operation would require rounding.
        See Also:
        BigDecimal.doubleValue()

      • representableDelta

        public static double representableDelta​(double x,
                                        double delta)
        Computes a number close to delta with the property that (x + delta - x) is exactly machine-representable. This is useful when computing numerical derivatives, in order to reduce roundoff errors.
        Parameters:
        x - Value.
        delta - Offset value.
        Returns:
        the machine-representable floating number closest to the difference between x + delta and x.