Package com.sun.ts.lib.util
Class FpUtils
java.lang.Object
com.sun.ts.lib.util.FpUtils
The class
FpUtils
contains static utility methods for manipulating and inspecting float
and
double
floating-point numbers. These methods include functionality recommended or required by the IEEE 754
floating-point standard.- Author:
- Joseph D. Darcy
-
Method Summary
Modifier and TypeMethodDescriptionstatic double
copySign
(double magnitude, double sign) Returns the first floating-point argument with the sign of the second floating-point argument.static float
copySign
(float magnitude, float sign) Returns the first floating-point argument with the sign of the second floating-point argument.static int
getExponent
(double d) Returns unbiased exponent of adouble
.static int
getExponent
(float f) Returns unbiased exponent of afloat
.static int
ilogb
(double d) Returns unbiased exponent of adouble
; for subnormal values, the number is treated as if it were normalized.static int
ilogb
(float f) Returns unbiased exponent of afloat
; for subnormal values, the number is treated as if it were normalized.static boolean
isFinite
(double d) Returnstrue
if the argument is a finite floating-point value; returnsfalse
otherwise (for NaN and infinity arguments).static boolean
isFinite
(float f) Returnstrue
if the argument is a finite floating-point value; returnsfalse
otherwise (for NaN and infinity arguments).static boolean
isInfinite
(double d) Returnstrue
if the specified number is infinitely large in magnitude,false
otherwise.static boolean
isInfinite
(float f) Returnstrue
if the specified number is infinitely large in magnitude,false
otherwise.static boolean
isNaN
(double d) Returnstrue
if the specified number is a Not-a-Number (NaN) value,false
otherwise.static boolean
isNaN
(float f) Returnstrue
if the specified number is a Not-a-Number (NaN) value,false
otherwise.static boolean
isUnordered
(double arg1, double arg2) Returnstrue
if the unordered relation holds between the two arguments.static boolean
isUnordered
(float arg1, float arg2) Returnstrue
if the unordered relation holds between the two arguments.static double
nextAfter
(double start, double direction) Returns the floating-point number adjacent to the first argument in the direction of the second argument.static float
nextAfter
(float start, double direction) Returns the floating-point number adjacent to the first argument in the direction of the second argument.static double
nextDown
(double d) Returns the floating-point value adjacent tod
in the direction of negative infinity.static double
nextDown
(float f) Returns the floating-point value adjacent tof
in the direction of negative infinity.static double
nextUp
(double d) Returns the floating-point value adjacent tod
in the direction of positive infinity.static float
nextUp
(float f) Returns the floating-point value adjacent tof
in the direction of positive infinity.static double
rawCopySign
(double magnitude, double sign) Returns the first floating-point argument with the sign of the second floating-point argument.static float
rawCopySign
(float magnitude, float sign) Returns the first floating-point argument with the sign of the second floating-point argument.static double
scalb
(double d, int scale_factor) Returnd
× 2scale_factor
rounded as if performed by a single correctly rounded floating-point multiply to a member of the double value set.static float
scalb
(float f, int scale_factor) Returnf
× 2scale_factor
rounded as if performed by a single correctly rounded floating-point multiply to a member of the float value set.static double
signum
(double d) Returns the signum function of the argument; zero if the argument is zero, 1.0 if the argument is greater than zero, -1.0 if the argument is less than zero.static float
signum
(float f) Returns the signum function of the argument; zero if the argument is zero, 1.0f if the argument is greater than zero, -1.0f if the argument is less than zero.static double
ulp
(double d) Returns the size of an ulp of the argument.static float
ulp
(float f) Returns the size of an ulp of the argument.
-
Method Details
-
getExponent
public static int getExponent(double d) Returns unbiased exponent of adouble
. -
getExponent
public static int getExponent(float f) Returns unbiased exponent of afloat
. -
rawCopySign
public static double rawCopySign(double magnitude, double sign) Returns the first floating-point argument with the sign of the second floating-point argument. Note that unlike thecopySign
method, this method does not require NaNsign
arguments to be treated as positive values; implementations are permitted to treat some NaN arguments as positive and other NaN arguments as negative to allow greater performance.- Parameters:
magnitude
- the parameter providing the magnitude of the resultsign
- the parameter providing the sign of the result- Returns:
- a value with the magnitude of
magnitude
and the sign ofsign
.
-
rawCopySign
public static float rawCopySign(float magnitude, float sign) Returns the first floating-point argument with the sign of the second floating-point argument. Note that unlike thecopySign
method, this method does not require NaNsign
arguments to be treated as positive values; implementations are permitted to treat some NaN arguments as positive and other NaN arguments as negative to allow greater performance.- Parameters:
magnitude
- the parameter providing the magnitude of the resultsign
- the parameter providing the sign of the result- Returns:
- a value with the magnitude of
magnitude
and the sign ofsign
.
-
isFinite
public static boolean isFinite(double d) Returnstrue
if the argument is a finite floating-point value; returnsfalse
otherwise (for NaN and infinity arguments).- Parameters:
d
- thedouble
value to be tested- Returns:
true
if the argument is a finite floating-point value,false
otherwise.
-
isFinite
public static boolean isFinite(float f) Returnstrue
if the argument is a finite floating-point value; returnsfalse
otherwise (for NaN and infinity arguments).- Parameters:
f
- thefloat
value to be tested- Returns:
true
if the argument is a finite floating-point value,false
otherwise.
-
isInfinite
public static boolean isInfinite(double d) Returnstrue
if the specified number is infinitely large in magnitude,false
otherwise. Note that this method is equivalent to theDouble.isInfinite
method; the functionality is included in this class for convenience.- Parameters:
d
- the value to be tested.- Returns:
true
if the value of the argument is positive infinity or negative infinity;false
otherwise.
-
isInfinite
public static boolean isInfinite(float f) Returnstrue
if the specified number is infinitely large in magnitude,false
otherwise. Note that this method is equivalent to theFloat.isInfinite
method; the functionality is included in this class for convenience.- Parameters:
f
- the value to be tested.- Returns:
true
if the argument is positive infinity or negative infinity;false
otherwise.
-
isNaN
public static boolean isNaN(double d) Returnstrue
if the specified number is a Not-a-Number (NaN) value,false
otherwise. Note that this method is equivalent to theDouble.isNaN
method; the functionality is included in this class for convenience.- Parameters:
d
- the value to be tested.- Returns:
true
if the value of the argument is NaN;false
otherwise.
-
isNaN
public static boolean isNaN(float f) Returnstrue
if the specified number is a Not-a-Number (NaN) value,false
otherwise. Note that this method is equivalent to theFloat.isNaN
method; the functionality is included in this class for convenience.- Parameters:
f
- the value to be tested.- Returns:
true
if the argument is NaN;false
otherwise.
-
isUnordered
public static boolean isUnordered(double arg1, double arg2) Returnstrue
if the unordered relation holds between the two arguments. When two floating-point values are unordered, one value is neither less than, equal to, nor greater than the other. For the unordered relation to be true, at least one argument must be aNaN
.- Parameters:
arg1
- the first argumentarg2
- the second argument- Returns:
true
if at least one argument is a NaN,false
otherwise.
-
isUnordered
public static boolean isUnordered(float arg1, float arg2) Returnstrue
if the unordered relation holds between the two arguments. When two floating-point values are unordered, one value is neither less than, equal to, nor greater than the other. For the unordered relation to be true, at least one argument must be aNaN
.- Parameters:
arg1
- the first argumentarg2
- the second argument- Returns:
true
if at least one argument is a NaN,false
otherwise.
-
ilogb
public static int ilogb(double d) Returns unbiased exponent of adouble
; for subnormal values, the number is treated as if it were normalized. That is for all finite, non-zero, positive numbers x,scalb(x, -ilogb(x))
is always in the range [1, 2). Special cases:- If the argument is NaN, then the result is 230.
- If the argument is infinite, then the result is 228.
- If the argument is zero, then the result is -(228).
- Parameters:
d
- floating-point number whose exponent is to be extracted- Returns:
- unbiased exponent of the argument.
-
ilogb
public static int ilogb(float f) Returns unbiased exponent of afloat
; for subnormal values, the number is treated as if it were normalized. That is for all finite, non-zero, positive numbers x,scalb(x, -ilogb(x))
is always in the range [1, 2). Special cases:- If the argument is NaN, then the result is 230.
- If the argument is infinite, then the result is 228.
- If the argument is zero, then the result is -(228).
- Parameters:
f
- floating-point number whose exponent is to be extracted- Returns:
- unbiased exponent of the argument.
-
scalb
public static double scalb(double d, int scale_factor) Returnd
× 2scale_factor
rounded as if performed by a single correctly rounded floating-point multiply to a member of the double value set. See section 4.2.3 of The Java™ Language Specification for a discussion of floating-point value sets. If the exponent of the result is between thedouble
's minimum exponent and maximum exponent, the answer is calculated exactly. If the exponent of the result would be larger thandoubles
's maximum exponent, an infinity is returned. Note that if the result is subnormal, precision may be lost; that is, whenscalb(x, n)
is subnormal,scalb(scalb(x, n), -n)
may not equal x. When the result is non-NaN, the result has the same sign asd
. Special cases:- If the first argument is NaN, NaN is returned.
- If the first argument is infinite, then an infinity of the same sign is returned.
- If the first argument is zero, then a zero of the same sign is returned.
- Parameters:
d
- number to be scaled by a power of two.scale_factor
- power of 2 used to scaled
- Returns:
d *
2scale_factor
-
scalb
public static float scalb(float f, int scale_factor) Returnf
× 2scale_factor
rounded as if performed by a single correctly rounded floating-point multiply to a member of the float value set. See section 4.2.3 of The Java™ Language Specification for a discussion of floating-point value sets. If the exponent of the result is between thefloat
's minimum exponent and maximum exponent, the answer is calculated exactly. If the exponent of the result would be larger thanfloat
's maximum exponent, an infinity is returned. Note that if the result is subnormal, precision may be lost; that is, whenscalb(x, n)
is subnormal,scalb(scalb(x, n), -n)
may not equal x. When the result is non-NaN, the result has the same sign asf
. Special cases:- If the first argument is NaN, NaN is returned.
- If the first argument is infinite, then an infinity of the same sign is returned.
- If the first argument is zero, then a zero of the same sign is returned.
- Parameters:
f
- number to be scaled by a power of two.scale_factor
- power of 2 used to scalef
- Returns:
f *
2scale_factor
-
nextAfter
public static double nextAfter(double start, double direction) Returns the floating-point number adjacent to the first argument in the direction of the second argument. If both arguments compare as equal the second argument is returned. Special cases:- If either argument is a NaN, then NaN is returned.
- If both arguments are signed zeros,
direction
is returned unchanged (as implied by the requirement of returning the second argument if the arguments compare as equal). - If
start
is ±Double.MIN_VALUE
anddirection
has a value such that the result should have a smaller magnitude, then a zero with the same sign asstart
is returned. - If
start
is infinite anddirection
has a value such that the result should have a smaller magnitude,Double.MAX_VALUE
with the same sign asstart
is returned. - If
start
is equal to ±Double.MAX_VALUE
anddirection
has a value such that the result should have a larger magnitude, an infinity with same sign asstart
is returned.
- Parameters:
start
- starting floating-point valuedirection
- value indicating which ofstart
's neighbors orstart
should be returned- Returns:
- The floating-point number adjacent to
start
in the direction ofdirection
.
-
nextAfter
public static float nextAfter(float start, double direction) Returns the floating-point number adjacent to the first argument in the direction of the second argument. If both arguments compare as equal, the second argument is returned. Special cases:- If either argument is a NaN, then NaN is returned.
- If both arguments are signed zeros, a
float
zero with the same sign asdirection
is returned (as implied by the requirement of returning the second argument if the arguments compare as equal). - If
start
is ±Float.MIN_VALUE
anddirection
has a value such that the result should have a smaller magnitude, then a zero with the same sign asstart
is returned. - If
start
is infinite anddirection
has a value such that the result should have a smaller magnitude,Float.MAX_VALUE
with the same sign asstart
is returned. - If
start
is equal to ±Float.MAX_VALUE
anddirection
has a value such that the result should have a larger magnitude, an infinity with same sign asstart
is returned.
- Parameters:
start
- starting floating-point valuedirection
- value indicating which ofstart
's neighbors orstart
should be returned- Returns:
- The floating-point number adjacent to
start
in the direction ofdirection
.
-
nextUp
public static double nextUp(double d) Returns the floating-point value adjacent tod
in the direction of positive infinity. This method is semantically equivalent tonextAfter(d, Double.POSITIVE_INFINITY)
; however, anextUp
implementation may run faster than its equivalentnextAfter
call. Special Cases:- If the argument is NaN, the result is NaN.
- If the argument is positive infinity, the result is positive infinity.
- If the argument is zero, the result is
Double.MIN_VALUE
- Parameters:
d
- starting floating-point value- Returns:
- The adjacent floating-point value closer to positive infinity.
-
nextUp
public static float nextUp(float f) Returns the floating-point value adjacent tof
in the direction of positive infinity. This method is semantically equivalent tonextAfter(f, Double.POSITIVE_INFINITY)
; however, anextUp
implementation may run faster than its equivalentnextAfter
call. Special Cases:- If the argument is NaN, the result is NaN.
- If the argument is positive infinity, the result is positive infinity.
- If the argument is zero, the result is
Float.MIN_VALUE
- Parameters:
f
- starting floating-point value- Returns:
- The adjacent floating-point value closer to positive infinity.
-
nextDown
public static double nextDown(double d) Returns the floating-point value adjacent tod
in the direction of negative infinity. This method is semantically equivalent tonextAfter(d, Double.NEGATIVE_INFINITY)
; however, anextDown
implementation may run faster than its equivalentnextAfter
call. Special Cases:- If the argument is NaN, the result is NaN.
- If the argument is negative infinity, the result is negative infinity.
- If the argument is zero, the result is
-Double.MIN_VALUE
- Parameters:
d
- starting floating-point value- Returns:
- The adjacent floating-point value closer to negative infinity.
-
nextDown
public static double nextDown(float f) Returns the floating-point value adjacent tof
in the direction of negative infinity. This method is semantically equivalent tonextAfter(f, Float.NEGATIVE_INFINITY)
; however, anextDown
implementation may run faster than its equivalentnextAfter
call. Special Cases:- If the argument is NaN, the result is NaN.
- If the argument is negative infinity, the result is negative infinity.
- If the argument is zero, the result is
-Float.MIN_VALUE
- Parameters:
f
- starting floating-point value- Returns:
- The adjacent floating-point value closer to negative infinity.
-
copySign
public static double copySign(double magnitude, double sign) Returns the first floating-point argument with the sign of the second floating-point argument. For this method, a NaNsign
argument is always treated as if it were positive.- Parameters:
magnitude
- the parameter providing the magnitude of the resultsign
- the parameter providing the sign of the result- Returns:
- a value with the magnitude of
magnitude
and the sign ofsign
. - Since:
- 1.5
-
copySign
public static float copySign(float magnitude, float sign) Returns the first floating-point argument with the sign of the second floating-point argument. For this method, a NaNsign
argument is always treated as if it were positive.- Parameters:
magnitude
- the parameter providing the magnitude of the resultsign
- the parameter providing the sign of the result- Returns:
- a value with the magnitude of
magnitude
and the sign ofsign
.
-
ulp
public static double ulp(double d) Returns the size of an ulp of the argument. An ulp of adouble
value is the positive distance between this floating-point value and thedouble
value next larger in magnitude. Note that for non-NaN x,ulp(-x) == ulp(x)
. Special Cases:- If the argument is NaN, then the result is NaN.
- If the argument is positive or negative infinity, then the result is positive infinity.
- If the argument is positive or negative zero, then the result is
Double.MIN_VALUE
. - If the argument is ±
Double.MAX_VALUE
, then the result is equal to 2971.
- Parameters:
d
- the floating-point value whose ulp is to be returned- Returns:
- the size of an ulp of the argument
- Since:
- 1.5
-
ulp
public static float ulp(float f) Returns the size of an ulp of the argument. An ulp of afloat
value is the positive distance between this floating-point value and thefloat
value next larger in magnitude. Note that for non-NaN x,ulp(-x) == ulp(x)
. Special Cases:- If the argument is NaN, then the result is NaN.
- If the argument is positive or negative infinity, then the result is positive infinity.
- If the argument is positive or negative zero, then the result is
Float.MIN_VALUE
. - If the argument is ±
Float.MAX_VALUE
, then the result is equal to 2104.
- Parameters:
f
- the floating-point value whose ulp is to be returned- Returns:
- the size of an ulp of the argument
- Since:
- 1.5
-
signum
public static double signum(double d) Returns the signum function of the argument; zero if the argument is zero, 1.0 if the argument is greater than zero, -1.0 if the argument is less than zero. Special Cases:- If the argument is NaN, then the result is NaN.
- If the argument is positive zero or negative zero, then the result is the same as the argument.
- Parameters:
d
- the floating-point value whose signum is to be returned- Returns:
- the signum function of the argument
- Since:
- 1.5
-
signum
public static float signum(float f) Returns the signum function of the argument; zero if the argument is zero, 1.0f if the argument is greater than zero, -1.0f if the argument is less than zero. Special Cases:- If the argument is NaN, then the result is NaN.
- If the argument is positive zero or negative zero, then the result is the same as the argument.
- Parameters:
f
- the floating-point value whose signum is to be returned- Returns:
- the signum function of the argument
- Since:
- 1.5
-