Package org.apache.commons.math3.util

Class Precision

java.lang.Object
org.apache.commons.math3.util.Precision
public class Precision extends Object
Utilities for comparing numbers.
Since:
3.0

  • Field Summary

    Fields
    Modifier and Type
    Field
    Description
    static final double
    EPSILON
    Largest double-precision floating-point number such that 1 + EPSILON is numerically equal to 1.
    private static final long
    EXPONENT_OFFSET
    Exponent offset in IEEE754 representation.
    private static final long
    NEGATIVE_ZERO_DOUBLE_BITS
    Negative zero bits.
    private static final int
    NEGATIVE_ZERO_FLOAT_BITS
    Negative zero bits.
    private static final double
    POSITIVE_ZERO
    Positive zero.
    private static final long
    POSITIVE_ZERO_DOUBLE_BITS
    Positive zero bits.
    private static final int
    POSITIVE_ZERO_FLOAT_BITS
    Positive zero bits.
    static final double
    SAFE_MIN
    Safe minimum, such that 1 / SAFE_MIN does not overflow.
    private static final long
    SGN_MASK
    Offset to order signed double numbers lexicographically.
    private static final int
    SGN_MASK_FLOAT
    Offset to order signed double numbers lexicographically.

  • Constructor Summary

    Constructors
    Modifier
    Constructor
    Description
    private
    Precision()
    Private constructor.

  • Method Summary

    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 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 the arguments are equal or 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, are equal or are 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, are equal, or are within the range of allowed error (inclusive).
    static boolean
    equalsIncludingNaN(float x, float y, int maxUlps)
    Returns true if the arguments are both 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 originalDelta)
    Computes a number delta close to originalDelta with the property that
    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, int roundingMethod)
    Rounds the given value to the specified number of decimal places.
    static float
    round(float x, int scale)
    Rounds the given value to the specified number of decimal places.
    static float
    round(float x, int scale, int roundingMethod)
    Rounds the given value to the specified number of decimal places.
    private static double
    roundUnscaled(double unscaled, double sign, int roundingMethod)
    Rounds the given non-negative value to the "nearest" integer.

    Methods inherited from class java.lang.Object

    clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

  • Field Details

    • 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:

    • 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.

    • EXPONENT_OFFSET

      private static final long EXPONENT_OFFSET
      Exponent offset in IEEE754 representation.
      See Also:

    • SGN_MASK

      private static final long SGN_MASK
      Offset to order signed double numbers lexicographically.
      See Also:

    • SGN_MASK_FLOAT

      private static final int SGN_MASK_FLOAT
      Offset to order signed double numbers lexicographically.
      See Also:

    • POSITIVE_ZERO

      private static final double POSITIVE_ZERO
      Positive zero.
      See Also:

    • POSITIVE_ZERO_DOUBLE_BITS

      private static final long POSITIVE_ZERO_DOUBLE_BITS
      Positive zero bits.

    • NEGATIVE_ZERO_DOUBLE_BITS

      private static final long NEGATIVE_ZERO_DOUBLE_BITS
      Negative zero bits.

    • POSITIVE_ZERO_FLOAT_BITS

      private static final int POSITIVE_ZERO_FLOAT_BITS
      Positive zero bits.

    • NEGATIVE_ZERO_FLOAT_BITS

      private static final int NEGATIVE_ZERO_FLOAT_BITS
      Negative zero bits.

  • Constructor Details

    • Precision

      private Precision()
      Private constructor.

  • Method Details

    • compareTo

      public static int compareTo(double x, double y, double eps)
      Compares two numbers given some amount of allowed error.
      Parameters:
      x - the first number
      y - the second number
      eps - the amount of error to allow when checking for equality
      Returns:

    • compareTo

      public static int compareTo(double x, double y, int maxUlps)
      Compares two numbers given some amount of allowed error. 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. Returns false if either of the arguments is NaN.
      Parameters:
      x - first value
      y - second value
      maxUlps - (maxUlps - 1) is the number of floating point values between x and y.
      Returns:

    • 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.
      Since:
      2.2

    • equals

      public static boolean equals(float x, float y, float eps)
      Returns true if the arguments are equal or 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.
      Since:
      2.2

    • equalsIncludingNaN

      public static boolean equalsIncludingNaN(float x, float y, float eps)
      Returns true if the arguments are both NaN, are equal, or are 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.
      Since:
      2.2

    • 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). 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. Returns false if either of the arguments is NaN.
      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.
      Since:
      2.2

    • equalsIncludingNaN

      public static boolean equalsIncludingNaN(float x, float y, int maxUlps)
      Returns true if the arguments are both 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.
      Since:
      2.2

    • 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.
      Since:
      2.2

    • 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 two adjacent floating point numbers or they are 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.
      Since:
      3.1

    • equalsIncludingNaN

      public static boolean equalsIncludingNaN(double x, double y, double eps)
      Returns true if the arguments are both NaN, are equal or are 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.
      Since:
      2.2

    • 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).

      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. Returns false if either of the arguments is NaN.

      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.
      Since:
      2.2

    • 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 the BigDecimal.ROUND_HALF_UP method.
      Parameters:
      x - Value to round.
      scale - Number of digits to the right of the decimal point.
      Returns:
      the rounded value.
      Since:
      1.1 (previously in MathUtils, moved as of version 3.0)

    • round

      public static double round(double x, int scale, int roundingMethod)
      Rounds the given value to the specified number of decimal places. The value is rounded using the given method which is any method defined in BigDecimal. If x is infinite or NaN, then the value of x is returned unchanged, regardless of the other parameters.
      Parameters:
      x - Value to round.
      scale - Number of digits to the right of the decimal point.
      roundingMethod - Rounding method as defined in BigDecimal.
      Returns:
      the rounded value.
      Throws:
      ArithmeticException - if roundingMethod == ROUND_UNNECESSARY and the specified scaling operation would require rounding.
      IllegalArgumentException - if roundingMethod does not represent a valid rounding mode.
      Since:
      1.1 (previously in MathUtils, moved as of version 3.0)

    • round

      public static float round(float x, int scale)
      Rounds the given value to the specified number of decimal places. The value is rounded using the BigDecimal.ROUND_HALF_UP method.
      Parameters:
      x - Value to round.
      scale - Number of digits to the right of the decimal point.
      Returns:
      the rounded value.
      Since:
      1.1 (previously in MathUtils, moved as of version 3.0)

    • round

      public static float round(float x, int scale, int roundingMethod) throws MathArithmeticException, MathIllegalArgumentException
      Rounds the given value to the specified number of decimal places. The value is rounded using the given method which is any method defined in BigDecimal.
      Parameters:
      x - Value to round.
      scale - Number of digits to the right of the decimal point.
      roundingMethod - Rounding method as defined in BigDecimal.
      Returns:
      the rounded value.
      Throws:
      MathArithmeticException - if an exact operation is required but result is not exact
      MathIllegalArgumentException - if roundingMethod is not a valid rounding method.
      Since:
      1.1 (previously in MathUtils, moved as of version 3.0)

    • roundUnscaled

      private static double roundUnscaled(double unscaled, double sign, int roundingMethod) throws MathArithmeticException, MathIllegalArgumentException
      Rounds the given non-negative value to the "nearest" integer. Nearest is determined by the rounding method specified. Rounding methods are defined in BigDecimal.
      Parameters:
      unscaled - Value to round.
      sign - Sign of the original, scaled value.
      roundingMethod - Rounding method, as defined in BigDecimal.
      Returns:
      the rounded value.
      Throws:
      MathArithmeticException - if an exact operation is required but result is not exact
      MathIllegalArgumentException - if roundingMethod is not a valid rounding method.
      Since:
      1.1 (previously in MathUtils, moved as of version 3.0)

    • representableDelta

      public static double representableDelta(double x, double originalDelta)
      Computes a number delta close to originalDelta 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.
      originalDelta - Offset value.
      Returns:
      a number delta so that x + delta and x differ by a representable floating number.