Package com.sun.ts.lib.util

# Class FpUtils

java.lang.Object
com.sun.ts.lib.util.FpUtils

public class FpUtils extends Object
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 Type
  Method
  Description
  `static 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 a `double`.
  `static int`
  `getExponent(float f)`
  Returns unbiased exponent of a `float`.
  `static int`
  `ilogb(double d)`
  Returns unbiased exponent of a `double`; for subnormal values, the number is treated as if it were normalized.
  `static int`
  `ilogb(float f)`
  Returns unbiased exponent of a `float`; for subnormal values, the number is treated as if it were normalized.
  `static boolean`
  `isFinite(double d)`
  Returns `true` if the argument is a finite floating-point value; returns `false` otherwise (for NaN and infinity arguments).
  `static boolean`
  `isFinite(float f)`
  Returns `true` if the argument is a finite floating-point value; returns `false` otherwise (for NaN and infinity arguments).
  `static boolean`
  `isInfinite(double d)`
  Returns `true` if the specified number is infinitely large in magnitude, `false` otherwise.
  `static boolean`
  `isInfinite(float f)`
  Returns `true` if the specified number is infinitely large in magnitude, `false` otherwise.
  `static boolean`
  `isNaN(double d)`
  Returns `true` if the specified number is a Not-a-Number (NaN) value, `false` otherwise.
  `static boolean`
  `isNaN(float f)`
  Returns `true` if the specified number is a Not-a-Number (NaN) value, `false` otherwise.
  `static boolean`
  `isUnordered(double arg1, double arg2)`
  Returns `true` if the unordered relation holds between the two arguments.
  `static boolean`
  `isUnordered(float arg1, float arg2)`
  Returns `true` 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 to `d` in the direction of negative infinity.
  `static double`
  `nextDown(float f)`
  Returns the floating-point value adjacent to `f` in the direction of negative infinity.
  `static double`
  `nextUp(double d)`
  Returns the floating-point value adjacent to `d` in the direction of positive infinity.
  `static float`
  `nextUp(float f)`
  Returns the floating-point value adjacent to `f` 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)`
  Return `d` × 2`scale_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)`
  Return `f` × 2`scale_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.

  ### Methods inherited from class java.lang.Object

  `clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait`

- ## Method Details

  - ### getExponent

    public static int getExponent(double d)
    Returns unbiased exponent of a `double`.

  - ### getExponent

    public static int getExponent(float f)
    Returns unbiased exponent of a `float`.

  - ### 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 the `copySign` method, this method does not require NaN `sign` 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 result
      `sign` - the parameter providing the sign of the result
    Returns:
      a value with the magnitude of `magnitude` and the sign of `sign`.

  - ### 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 the `copySign` method, this method does not require NaN `sign` 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 result
      `sign` - the parameter providing the sign of the result
    Returns:
      a value with the magnitude of `magnitude` and the sign of `sign`.

  - ### isFinite

    public static boolean isFinite(double d)
    Returns `true` if the argument is a finite floating-point value; returns `false` otherwise (for NaN and infinity arguments).
    Parameters:
      `d` - the `double` value to be tested
    Returns:
      `true` if the argument is a finite floating-point value, `false` otherwise.

  - ### isFinite

    public static boolean isFinite(float f)
    Returns `true` if the argument is a finite floating-point value; returns `false` otherwise (for NaN and infinity arguments).
    Parameters:
      `f` - the `float` value to be tested
    Returns:
      `true` if the argument is a finite floating-point value, `false` otherwise.

  - ### isInfinite

    public static boolean isInfinite(double d)
    Returns `true` if the specified number is infinitely large in magnitude, `false` otherwise. Note that this method is equivalent to the `Double.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)
    Returns `true` if the specified number is infinitely large in magnitude, `false` otherwise. Note that this method is equivalent to the `Float.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)
    Returns `true` if the specified number is a Not-a-Number (NaN) value, `false` otherwise. Note that this method is equivalent to the `Double.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)
    Returns `true` if the specified number is a Not-a-Number (NaN) value, `false` otherwise. Note that this method is equivalent to the `Float.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)
    Returns `true` 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 a `NaN`.
    Parameters:
      `arg1` - the first argument
      `arg2` - the second argument
    Returns:
      `true` if at least one argument is a NaN, `false` otherwise.

  - ### isUnordered

    public static boolean isUnordered(float arg1, float arg2)
    Returns `true` 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 a `NaN`.
    Parameters:
      `arg1` - the first argument
      `arg2` - 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 a `double`; 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 a `float`; 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)
    Return `d` × 2`scale_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 the `double`'s minimum exponent and maximum exponent, the answer is calculated exactly. If the exponent of the result would be larger than `doubles`'s maximum exponent, an infinity is returned. Note that if the result is subnormal, precision may be lost; that is, when `scalb(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 as `d`. 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 scale `d`
    Returns:
      `d *` 2`scale_factor`

  - ### scalb

    public static float scalb(float f, int scale_factor)
    Return `f` × 2`scale_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 the `float`'s minimum exponent and maximum exponent, the answer is calculated exactly. If the exponent of the result would be larger than `float`'s maximum exponent, an infinity is returned. Note that if the result is subnormal, precision may be lost; that is, when `scalb(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 as `f`. 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 scale `f`
    Returns:
      `f *` 2`scale_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` and `direction` has a value such that the result should have a smaller magnitude, then a zero with the same sign as `start` is returned.
    - If `start` is infinite and `direction` has a value such that the result should have a smaller magnitude, `Double.MAX_VALUE` with the same sign as `start` is returned.
    - If `start` is equal to ± `Double.MAX_VALUE` and `direction` has a value such that the result should have a larger magnitude, an infinity with same sign as `start` is returned.
    Parameters:
      `start` - starting floating-point value
      `direction` - value indicating which of `start`'s neighbors or `start` should be returned
    Returns:
      The floating-point number adjacent to `start` in the direction of `direction`.

  - ### 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 as `direction` is returned (as implied by the requirement of returning the second argument if the arguments compare as equal).
    - If `start` is ±`Float.MIN_VALUE` and `direction` has a value such that the result should have a smaller magnitude, then a zero with the same sign as `start` is returned.
    - If `start` is infinite and `direction` has a value such that the result should have a smaller magnitude, `Float.MAX_VALUE` with the same sign as `start` is returned.
    - If `start` is equal to ± `Float.MAX_VALUE` and `direction` has a value such that the result should have a larger magnitude, an infinity with same sign as `start` is returned.
    Parameters:
      `start` - starting floating-point value
      `direction` - value indicating which of `start`'s neighbors or `start` should be returned
    Returns:
      The floating-point number adjacent to `start` in the direction of `direction`.

  - ### nextUp

    public static double nextUp(double d)
    Returns the floating-point value adjacent to `d` in the direction of positive infinity. This method is semantically equivalent to `nextAfter(d, Double.POSITIVE_INFINITY)`; however, a `nextUp` implementation may run faster than its equivalent `nextAfter` 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 to `f` in the direction of positive infinity. This method is semantically equivalent to `nextAfter(f, Double.POSITIVE_INFINITY)`; however, a `nextUp` implementation may run faster than its equivalent `nextAfter` 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 to `d` in the direction of negative infinity. This method is semantically equivalent to `nextAfter(d, Double.NEGATIVE_INFINITY)`; however, a `nextDown` implementation may run faster than its equivalent `nextAfter` 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 to `f` in the direction of negative infinity. This method is semantically equivalent to `nextAfter(f, Float.NEGATIVE_INFINITY)`; however, a `nextDown` implementation may run faster than its equivalent `nextAfter` 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 NaN `sign` argument is always treated as if it were positive.
    Parameters:
      `magnitude` - the parameter providing the magnitude of the result
      `sign` - the parameter providing the sign of the result
    Returns:
      a value with the magnitude of `magnitude` and the sign of `sign`.
    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 NaN `sign` argument is always treated as if it were positive.
    Parameters:
      `magnitude` - the parameter providing the magnitude of the result
      `sign` - the parameter providing the sign of the result
    Returns:
      a value with the magnitude of `magnitude` and the sign of `sign`.

  - ### ulp

    public static double ulp(double d)
    Returns the size of an ulp of the argument. An ulp of a `double` value is the positive distance between this floating-point value and the `double` 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 a `float` value is the positive distance between this floating-point value and the `float` 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