Class Precision
- java.lang.Object
-
- org.apache.commons.numbers.core.Precision
-
-
Nested Class Summary
Nested Classes Modifier and Type Class Description static interfacePrecision.DoubleEquivalenceInterface containing comparison operations for doubles that allow values to be considered equal even if they are not exactly equal.
-
Method Summary
All Methods Static Methods Concrete Methods Modifier and Type Method Description static intcompareTo(double x, double y, double eps)Compares two numbers given some amount of allowed error.static intcompareTo(double x, double y, int maxUlps)Compares two numbers given some amount of allowed error.static Precision.DoubleEquivalencedoubleEquivalenceOfEpsilon(double eps)Creates aPrecision.DoubleEquivalenceinstance that uses the given epsilon value for determining equality.static booleanequals(double x, double y)Returns true iff they are equal as defined byequals(x, y, 1).static booleanequals(double x, double y, double eps)Returnstrueif there is no double value strictly between the arguments or the difference between them is within the range of allowed error (inclusive).static booleanequals(double x, double y, int maxUlps)Returns true if the arguments are equal or within the range of allowed error (inclusive).static booleanequals(float x, float y)Returns true iff they are equal as defined byequals(x, y, 1).static booleanequals(float x, float y, float eps)Returnstrueif there is no float value strictly between the arguments or the difference between them is within the range of allowed error (inclusive).static booleanequals(float x, float y, int maxUlps)Returns true if the arguments are equal or within the range of allowed error (inclusive).static booleanequalsIncludingNaN(double x, double y)Returns true if the arguments are both NaN or they are equal as defined byequals(x, y, 1).static booleanequalsIncludingNaN(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 booleanequalsIncludingNaN(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 booleanequalsIncludingNaN(float x, float y)Returns true if both arguments are NaN or they are equal as defined byequals(x, y, 1).static booleanequalsIncludingNaN(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 booleanequalsIncludingNaN(float x, float y, int maxUlps)Returns true if both arguments are NaN or if they are equal as defined byequals(x, y, maxUlps).static booleanequalsWithRelativeTolerance(double x, double y, double eps)Returnstrueif 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 doublerepresentableDelta(double x, double delta)Computes a number close todeltawith the property that(x + delta - x)is exactly machine-representable.static doubleround(double x, int scale)Rounds the given value to the specified number of decimal places.static doubleround(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 + EPSILONis 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 that1 / SAFE_MINdoes 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)
- zero if considered equal using
-
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 betweenxandy.- 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)
- zero if considered equal using
-
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:
trueif 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:
trueif the values are equal or both are NaN.
-
equals
public static boolean equals(float x, float y, float eps)
Returnstrueif there is no float value strictly between the arguments or the difference between them is within the range of allowed error (inclusive). Returnsfalseif either of the arguments is NaN.- Parameters:
x- first valuey- second valueeps- the amount of absolute error to allow.- Returns:
trueif 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 valuey- second valueeps- the amount of absolute error to allow.- Returns:
trueif 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). Returnsfalseif 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 valuey- second valuemaxUlps-(maxUlps - 1)is the number of floating point values betweenxandy.- Returns:
trueif there are fewer thanmaxUlpsfloating point values betweenxandy.
-
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 byequals(x, y, maxUlps).- Parameters:
x- first valuey- second valuemaxUlps-(maxUlps - 1)is the number of floating point values betweenxandy.- Returns:
trueif both arguments are NaN or if there are less thanmaxUlpsfloating point values betweenxandy.
-
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:
trueif 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:
trueif the values are equal or both are NaN.
-
equals
public static boolean equals(double x, double y, double eps)
Returnstrueif there is no double value strictly between the arguments or the difference between them is within the range of allowed error (inclusive). Returnsfalseif either of the arguments is NaN.- Parameters:
x- First value.y- Second value.eps- Amount of allowed absolute error.- Returns:
trueif the values are equal or within range of each other.
-
equalsWithRelativeTolerance
public static boolean equalsWithRelativeTolerance(double x, double y, double eps)
Returnstrueif there is no double value strictly between the arguments or the relative difference between them is less than or equal to the given tolerance. Returnsfalseif either of the arguments is NaN.- Parameters:
x- First value.y- Second value.eps- Amount of allowed relative error.- Returns:
trueif 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 valuey- second valueeps- the amount of absolute error to allow.- Returns:
trueif 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). Returnsfalseif 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 valuey- second valuemaxUlps-(maxUlps - 1)is the number of floating point values betweenxandy.- Returns:
trueif there are fewer thanmaxUlpsfloating point values betweenxandy.
-
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 betweenxandy.- Returns:
trueif both arguments are NaN or if there are less thanmaxUlpsfloating point values betweenxandy.
-
round
public static double round(double x, int scale)
Rounds the given value to the specified number of decimal places. The value is rounded usingRoundingMode.HALF_UP.Note: This method is intended to act on the String representation of the
doubleargument. Seeround(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 givenrounding mode.If
xis infinite orNaN, then the value ofxis returned unchanged, regardless of the other parameters.Note
Rounding of a 64-bit base-2 format
doubleusing 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
doubleargument, 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 representabledouble.Conversion from base-2 to base-10 format uses the
BigDecimal.valueOf(double)method. The alternative would be to usenew 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 representabledoubleto the decimal value.The following code demonstrates how to eliminate rounding during conversion to a decimal format. The return conversion to a
doublemay be inexact:double rounded = new BigDecimal(x).setScale(scale, roundingMode).doubleValue();
Acting on the String representation of the
doubleallows this method to return expected output when roundingdoublerepresentations 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 inBigDecimal.- Returns:
- the rounded value.
- Throws:
ArithmeticException- ifroundingModeisRoundingMode.UNNECESSARYand the specified scaling operation would require rounding.- See Also:
BigDecimal.doubleValue()
-
representableDelta
public static double representableDelta(double x, double delta)
Computes a number close todeltawith 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 + deltaandx.
-
doubleEquivalenceOfEpsilon
public static Precision.DoubleEquivalence doubleEquivalenceOfEpsilon(double eps)
Creates aPrecision.DoubleEquivalenceinstance that uses the given epsilon value for determining equality.- Parameters:
eps- Value to use for determining equality.- Returns:
- a new instance.
-
-