org.apache.commons.math3.util
Class Precision

java.lang.Object
  extended by org.apache.commons.math3.util.Precision

public class Precision
extends Object

Utilities for comparing numbers.

Since:
3.0
Version:
$Id$

Field Summary
static double EPSILON
          Smallest positive number such that 1 - EPSILON is not numerically equal to 1: 1.1102230246251565E-16.
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
private Precision()
          Private constructor.
 
Method Summary
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 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
Smallest positive number such that 1 - EPSILON is not numerically equal to 1: 1.1102230246251565E-16.

See Also:
Constant Field Values

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: 2.2250738585072014E-308.

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:

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:

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.

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)
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.
Since:
1.1 (previously in MathUtils, moved as of version 3.0)

roundUnscaled

private static double roundUnscaled(double unscaled,
                                    double sign,
                                    int roundingMethod)
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:
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