MathUtils (Apache Commons Math 3.3 API)

org.apache.commons.math3.util

## Class MathUtils

- java.lang.Object
- - org.apache.commons.math3.util.MathUtils

-     public final class MathUtils
      extends Object

  Miscellaneous utility functions.
  Version:
    $Id: MathUtils.java 1591835 2014-05-02 09:04:01Z tn $
  See Also:
    `ArithmeticUtils`, `Precision`, `MathArrays`

- - ### Field Summary

    Fields
    Modifier and Type | Field and Description
    --- | ---
    `static double` | `TWO_PI` 2 π.

  - ### Method Summary

    Methods
    Modifier and Type | Method and Description
    --- | ---
    `static void` | `checkFinite(double x)` Check that the argument is a real number.
    `static void` | `checkFinite(double[] val)` Check that all the elements are real numbers.
    `static void` | `checkNotNull(Object o)` Checks that an object is not null.
    `static void` | `checkNotNull(Object o, Localizable pattern, Object... args)` Checks that an object is not null.
    `static byte` | `copySign(byte magnitude, byte sign)` Returns the first argument with the sign of the second argument.
    `static int` | `copySign(int magnitude, int sign)` Returns the first argument with the sign of the second argument.
    `static long` | `copySign(long magnitude, long sign)` Returns the first argument with the sign of the second argument.
    `static short` | `copySign(short magnitude, short sign)` Returns the first argument with the sign of the second argument.
    `static boolean` | `equals(double x, double y)` Returns `true` if the values are equal according to semantics of `Double.equals(Object)`.
    `static int` | `hash(double value)` Returns an integer hash code representing the given double value.
    `static int` | `hash(double[] value)` Returns an integer hash code representing the given double array.
    `static double` | `normalizeAngle(double a, double center)` Normalize an angle in a 2π wide interval around a center value.
    `static double` | `reduce(double a, double period, double offset)` Reduce `|a - offset|` to the primary interval `[0, |period|)`.

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

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

- - ### Field Detail

    - #### TWO_PI

          public static final double TWO_PI

      2 π.
      Since:
        2.1
      See Also:
        Constant Field Values

  - ### Method Detail

    - #### hash

          public static int hash(double value)

      Returns an integer hash code representing the given double value.
      Parameters:
        `value` - the value to be hashed
      Returns:
        the hash code

    - #### equals

          public static boolean equals(double x,
                       double y)

      Returns `true` if the values are equal according to semantics of `Double.equals(Object)`.
      Parameters:
        `x` - Value
        `y` - Value
      Returns:
        `new Double(x).equals(new Double(y))`

    - #### hash

          public static int hash(double[] value)

      Returns an integer hash code representing the given double array.
      Parameters:
        `value` - the value to be hashed (may be null)
      Returns:
        the hash code
      Since:
        1.2

    - #### normalizeAngle

          public static double normalizeAngle(double a,
                              double center)

      Normalize an angle in a 2π wide interval around a center value.

      This method has three main uses:

      - normalize an angle between 0 and 2π:
        `a = MathUtils.normalizeAngle(a, FastMath.PI);`
      - normalize an angle between -π and +π
        `a = MathUtils.normalizeAngle(a, 0.0);`
      - compute the angle between two defining angular positions:
        `angle = MathUtils.normalizeAngle(end, start) - start;`

      Note that due to numerical accuracy and since π cannot be represented exactly, the result interval is closed, it cannot be half-closed as would be more satisfactory in a purely mathematical view.

      Parameters:
        `a` - angle to normalize
        `center` - center of the desired 2π interval for the result
      Returns:
        a-2kπ with integer k and center-π <= a-2kπ <= center+π
      Since:
        1.2

    - #### reduce

          public static double reduce(double a,
                      double period,
                      double offset)

      Reduce `|a - offset|` to the primary interval `[0, |period|)`.

      Specifically, the value returned is
      `a - |period| * floor((a - offset) / |period|) - offset`.

      If any of the parameters are `NaN` or infinite, the result is `NaN`.

      Parameters:
        `a` - Value to reduce.
        `period` - Period.
        `offset` - Value that will be mapped to `0`.
      Returns:
        the value, within the interval `[0 |period|)`, that corresponds to `a`.

    - #### copySign

          public static byte copySign(byte magnitude,
                      byte sign)
                               throws MathArithmeticException

      Returns the first argument with the sign of the second argument.
      Parameters:
        `magnitude` - Magnitude of the returned value.
        `sign` - Sign of the returned value.
      Returns:
        a value with magnitude equal to `magnitude` and with the same sign as the `sign` argument.
      Throws:
        `MathArithmeticException` - if `magnitude == Byte.MIN_VALUE` and `sign >= 0`.

    - #### copySign

          public static short copySign(short magnitude,
                       short sign)
                                throws MathArithmeticException

      Returns the first argument with the sign of the second argument.
      Parameters:
        `magnitude` - Magnitude of the returned value.
        `sign` - Sign of the returned value.
      Returns:
        a value with magnitude equal to `magnitude` and with the same sign as the `sign` argument.
      Throws:
        `MathArithmeticException` - if `magnitude == Short.MIN_VALUE` and `sign >= 0`.

    - #### copySign

          public static int copySign(int magnitude,
                     int sign)
                              throws MathArithmeticException

      Returns the first argument with the sign of the second argument.
      Parameters:
        `magnitude` - Magnitude of the returned value.
        `sign` - Sign of the returned value.
      Returns:
        a value with magnitude equal to `magnitude` and with the same sign as the `sign` argument.
      Throws:
        `MathArithmeticException` - if `magnitude == Integer.MIN_VALUE` and `sign >= 0`.

    - #### copySign

          public static long copySign(long magnitude,
                      long sign)
                               throws MathArithmeticException

      Returns the first argument with the sign of the second argument.
      Parameters:
        `magnitude` - Magnitude of the returned value.
        `sign` - Sign of the returned value.
      Returns:
        a value with magnitude equal to `magnitude` and with the same sign as the `sign` argument.
      Throws:
        `MathArithmeticException` - if `magnitude == Long.MIN_VALUE` and `sign >= 0`.

    - #### checkFinite

          public static void checkFinite(double x)
                                  throws NotFiniteNumberException

      Check that the argument is a real number.
      Parameters:
        `x` - Argument.
      Throws:
        `NotFiniteNumberException` - if `x` is not a finite real number.

    - #### checkFinite

          public static void checkFinite(double[] val)
                                  throws NotFiniteNumberException

      Check that all the elements are real numbers.
      Parameters:
        `val` - Arguments.
      Throws:
        `NotFiniteNumberException` - if any values of the array is not a finite real number.

    - #### checkNotNull

          public static void checkNotNull(Object o,
                          Localizable pattern,
                          Object... args)
                                   throws NullArgumentException

      Checks that an object is not null.
      Parameters:
        `o` - Object to be checked.
        `pattern` - Message pattern.
        `args` - Arguments to replace the placeholders in `pattern`.
      Throws:
        `NullArgumentException` - if `o` is `null`.

    - #### checkNotNull

          public static void checkNotNull(Object o)
                                   throws NullArgumentException

      Checks that an object is not null.
      Parameters:
        `o` - Object to be checked.
      Throws:
        `NullArgumentException` - if `o` is `null`.

Copyright © 2003–2014 The Apache Software Foundation. All rights reserved.