Package org.apache.commons.math3.util
Class Precision
java.lang.Object
org.apache.commons.math3.util.Precision
Utilities for comparing numbers.
- Since:
- 3.0
-
Field Summary
FieldsModifier and TypeFieldDescriptionstatic final double
Largest double-precision floating-point number such that1 + EPSILON
is numerically equal to 1.private static final long
Exponent offset in IEEE754 representation.private static final long
Negative zero bits.private static final int
Negative zero bits.private static final double
Positive zero.private static final long
Positive zero bits.private static final int
Positive zero bits.static final double
Safe minimum, such that1 / SAFE_MIN
does not overflow.private static final long
Offset to order signed double numbers lexicographically.private static final int
Offset to order signed double numbers lexicographically. -
Constructor Summary
Constructors -
Method Summary
Modifier and TypeMethodDescriptionstatic 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 byequals(x, y, 1)
.static boolean
equals
(double x, double y, double eps) Returnstrue
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 byequals(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 byequals(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 byequals(x, y, maxUlps)
.static boolean
equalsIncludingNaN
(float x, float y) Returns true if both arguments are NaN or they are equal as defined byequals(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 byequals(x, y, maxUlps)
.static boolean
equalsWithRelativeTolerance
(double x, double y, double eps) Returnstrue
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 numberdelta
close tooriginalDelta
with the property thatstatic 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.
-
Field Details
-
EPSILON
public static final double EPSILONLargest 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_MINSafe minimum, such that1 / 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_OFFSETExponent offset in IEEE754 representation.- See Also:
-
SGN_MASK
private static final long SGN_MASKOffset to order signed double numbers lexicographically.- See Also:
-
SGN_MASK_FLOAT
private static final int SGN_MASK_FLOATOffset to order signed double numbers lexicographically.- See Also:
-
POSITIVE_ZERO
private static final double POSITIVE_ZEROPositive zero.- See Also:
-
POSITIVE_ZERO_DOUBLE_BITS
private static final long POSITIVE_ZERO_DOUBLE_BITSPositive zero bits. -
NEGATIVE_ZERO_DOUBLE_BITS
private static final long NEGATIVE_ZERO_DOUBLE_BITSNegative zero bits. -
POSITIVE_ZERO_FLOAT_BITS
private static final int POSITIVE_ZERO_FLOAT_BITSPositive zero bits. -
NEGATIVE_ZERO_FLOAT_BITS
private static final int NEGATIVE_ZERO_FLOAT_BITSNegative 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 numbery
- the second numbereps
- 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 or either argument is NaN
- 0 if
-
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. Returnsfalse
if either of the arguments is NaN.- Parameters:
x
- first valuey
- second valuemaxUlps
-(maxUlps - 1)
is the number of floating point values betweenx
andy
.- Returns:
- 0 if
equals(x, y, maxUlps)
- < 0 if !
equals(x, y, maxUlps)
&& x < y - > 0 if !
equals(x, y, maxUlps)
&& x > y or either argument is NaN
- 0 if
-
equals
public static boolean equals(float x, float y) Returns true iff they are equal as defined byequals(x, y, 1)
.- Parameters:
x
- first valuey
- 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 byequals(x, y, 1)
.- Parameters:
x
- first valuey
- 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). Returnsfalse
if either of the arguments is NaN.- Parameters:
x
- first valuey
- second valueeps
- 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 valuey
- second valueeps
- 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. Returnsfalse
if either of the arguments is NaN.- Parameters:
x
- first valuey
- second valuemaxUlps
-(maxUlps - 1)
is the number of floating point values betweenx
andy
.- Returns:
true
if there are fewer thanmaxUlps
floating point values betweenx
andy
.- 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 byequals(x, y, maxUlps)
.- Parameters:
x
- first valuey
- second valuemaxUlps
-(maxUlps - 1)
is the number of floating point values betweenx
andy
.- Returns:
true
if both arguments are NaN or if there are less thanmaxUlps
floating point values betweenx
andy
.- Since:
- 2.2
-
equals
public static boolean equals(double x, double y) Returns true iff they are equal as defined byequals(x, y, 1)
.- Parameters:
x
- first valuey
- 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 byequals(x, y, 1)
.- Parameters:
x
- first valuey
- 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) Returnstrue
if there is no double value strictly between the arguments or the difference between them is within the range of allowed error (inclusive). Returnsfalse
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) Returnstrue
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. Returnsfalse
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 valuey
- second valueeps
- 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 valuey
- second valuemaxUlps
-(maxUlps - 1)
is the number of floating point values betweenx
andy
.- Returns:
true
if there are fewer thanmaxUlps
floating point values betweenx
andy
.
-
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 byequals(x, y, maxUlps)
.- Parameters:
x
- first valuey
- second valuemaxUlps
-(maxUlps - 1)
is the number of floating point values betweenx
andy
.- Returns:
true
if both arguments are NaN or if there are less thanmaxUlps
floating point values betweenx
andy
.- 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 theBigDecimal.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 inBigDecimal
. Ifx
is infinite orNaN
, then the value ofx
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 inBigDecimal
.- Returns:
- the rounded value.
- Throws:
ArithmeticException
- ifroundingMethod == ROUND_UNNECESSARY
and the specified scaling operation would require rounding.IllegalArgumentException
- ifroundingMethod
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 theBigDecimal.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 inBigDecimal
.- Parameters:
x
- Value to round.scale
- Number of digits to the right of the decimal point.roundingMethod
- Rounding method as defined inBigDecimal
.- Returns:
- the rounded value.
- Throws:
MathArithmeticException
- if an exact operation is required but result is not exactMathIllegalArgumentException
- ifroundingMethod
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 inBigDecimal
.- Parameters:
unscaled
- Value to round.sign
- Sign of the original, scaled value.roundingMethod
- Rounding method, as defined inBigDecimal
.- Returns:
- the rounded value.
- Throws:
MathArithmeticException
- if an exact operation is required but result is not exactMathIllegalArgumentException
- ifroundingMethod
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 numberdelta
close tooriginalDelta
with the property that
is exactly machine-representable. This is useful when computing numerical derivatives, in order to reduce roundoff errors.x + delta - x
- Parameters:
x
- Value.originalDelta
- Offset value.- Returns:
- a number
delta
so thatx + delta
andx
differ by a representable floating number.
-