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
  Version:
    $Id: Precision.java 1422313 2012-12-15 18:53:41Z psteitz $

- - ### Field Summary

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

  - ### Constructor Summary

    Constructors
    Modifier | Constructor and Description
    --- | ---
    `private` | `Precision()` Private constructor.

  - ### Method Summary

    Methods
    Modifier and Type | Method and 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 both 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 both arguments are equal or within the range of allowed error (inclusive).
    `static boolean` | `equals(float x, float y, int maxUlps)` Returns true if both arguments are equal or within the range of allowed error (inclusive).
    `static boolean` | `equalsIncludingNaN(double x, double y)` Returns true if both arguments are NaN or neither is NaN and they are equal as defined by `equals(x, y, 1)`.
    `static boolean` | `equalsIncludingNaN(double x, double y, double eps)` Returns true if both arguments are NaN or are equal or 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 neither is NaN and they are equal as defined by `equals(x, y, 1)`.
    `static boolean` | `equalsIncludingNaN(float x, float y, float eps)` Returns true if both arguments are NaN or are equal or 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 reltaive difference between them is smaller 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 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.

    - #### EXPONENT_OFFSET

          private static final long EXPONENT_OFFSET

      Exponent offset in IEEE754 representation.
      See Also:
        Constant Field Values

    - #### SGN_MASK

          private static final long SGN_MASK

      Offset to order signed double numbers lexicographically.
      See Also:
        Constant Field Values

    - #### SGN_MASK_FLOAT

          private static final int SGN_MASK_FLOAT

      Offset to order signed double numbers lexicographically.
      See Also:
        Constant Field Values

  - ### Constructor Detail

    - #### Precision

          private Precision()

      Private constructor.

  - ### Method Detail

    - #### 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:
        - 0 if `equals(x, y, eps)`
        - < 0 if !`equals(x, y, eps)` && x < y
        - > 0 if !`equals(x, y, eps)` && x > y

    - #### 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
      Parameters:
        `x` - first value
        `y` - second value
        `maxUlps` - `(maxUlps - 1)` is the number of floating point values between `x` and `y`.
      Returns:
        - 0 if `equals(x, y, maxUlps)`
        - < 0 if !`equals(x, y, maxUlps)` && x < y
        - > 0 if !`equals(x, y, maxUlps)` && x > y

    - #### 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 neither is NaN and 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 both arguments are equal or 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.
      Since:
        2.2

    - #### equalsIncludingNaN

          public static boolean equalsIncludingNaN(float x,
                                   float y,
                                   float eps)

      Returns true if both arguments are NaN or are equal or 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 both 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
      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 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

    - #### 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 both arguments are NaN or neither is NaN and 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).
      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 reltaive difference between them is smaller or equal to the given tolerance.
      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 both arguments are NaN or are equal or 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 both 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
      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.

Copyright (c) 2003-2013 Apache Software Foundation