org.apache.commons.math.util
Class MathUtils

java.lang.Object
  org.apache.commons.math.util.MathUtils

public final class MathUtils
extends java.lang.Object

Some useful additions to the built-in functions in Math.

Version:

$Id: MathUtils.java 1185841 2011-10-18 20:30:42Z erans $

Field Summary

static double	EPSILON Smallest positive number such that 1 - EPSILON is not numerically equal to 1.
static double	SAFE_MIN Safe minimum, such that 1 / SAFE_MIN does not overflow.
static double	TWO_PI 2 π.

Method Summary

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 number.
static void	checkNotNull(java.lang.Object o) Checks that an object is not null.
static void	checkNotNull(java.lang.Object o, Localizable pattern, java.lang.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	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 byte	indicator(byte x) For a byte value x, this method returns (byte)(+1) if x >= 0 and (byte)(-1) if x < 0.
static double	indicator(double x) For a double precision value x, this method returns +1.0 if x >= 0 and -1.0 if x < 0.
static float	indicator(float x) For a float value x, this method returns +1.0F if x >= 0 and -1.0F if x < 0.
static int	indicator(int x) For an int value x, this method returns +1 if x >= 0 and -1 if x < 0.
static long	indicator(long x) For a long value x, this method returns +1L if x >= 0 and -1L if x < 0.
static short	indicator(short x) For a short value x, this method returns (short)(+1) if x >= 0 and (short)(-1) if x < 0.
static double	log(double base, double x) Returns the logarithm for base b of x.
static double	normalizeAngle(double a, double center) Normalize an angle in a 2&pi wide interval around a center value.
static java.math.BigInteger	pow(java.math.BigInteger k, java.math.BigInteger e) Raise a BigInteger to a BigInteger power.
static java.math.BigInteger	pow(java.math.BigInteger k, int e) Raise a BigInteger to an int power.
static java.math.BigInteger	pow(java.math.BigInteger k, long e) Raise a BigInteger to a long power.
static int	pow(int k, int e) Raise an int to an int power.
static int	pow(int k, long e) Raise an int to a long power.
static long	pow(long k, int e) Raise a long to an int power.
static long	pow(long k, long e) Raise a long to a long power.
static double	reduce(double a, double period, double offset) Reduce |a - offset| to the primary interval [0, |period|).
static double	round(double x, int scale) Round the given value to the specified number of decimal places.
static double	round(double x, int scale, int roundingMethod) Round the given value to the specified number of decimal places.
static float	round(float x, int scale) Round the given value to the specified number of decimal places.
static float	round(float x, int scale, int roundingMethod) Round the given value to the specified number of decimal places.
static byte	sign(byte x) Returns the sign for byte value x.
static int	sign(int x) Returns the sign for int value x.
static long	sign(long x) Returns the sign for long value x.
static short	sign(short x) Compute the sign of the argument.

Methods inherited from class java.lang.Object

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

Field Detail

EPSILON

public static final double EPSILON

Smallest positive number such that 1 - EPSILON is not numerically equal to 1.

See Also:

Constant Field Values

SAFE_MIN

public static final double SAFE_MIN

Safe minimum, such that 1 / SAFE_MIN does not overflow.

In IEEE 754 arithmetic, this is also the smallest normalized number 2^-1022.

See Also:

Constant Field Values

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

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

indicator

public static byte indicator(byte x)

For a byte value x, this method returns (byte)(+1) if x >= 0 and (byte)(-1) if x < 0.

Parameters:

x - the value, a byte

Returns:

(byte)(+1) or (byte)(-1), depending on the sign of x

indicator

public static double indicator(double x)

For a double precision value x, this method returns +1.0 if x >= 0 and -1.0 if x < 0. Returns NaN if x is NaN.

Parameters:

x - the value, a double

Returns:

+1.0 or -1.0, depending on the sign of x

indicator

public static float indicator(float x)

For a float value x, this method returns +1.0F if x >= 0 and -1.0F if x < 0. Returns NaN if x is NaN.

Parameters:

x - the value, a float

Returns:

+1.0F or -1.0F, depending on the sign of x

indicator

public static int indicator(int x)

For an int value x, this method returns +1 if x >= 0 and -1 if x < 0.

Parameters:

x - the value, an int

Returns:

+1 or -1, depending on the sign of x

indicator

public static long indicator(long x)

For a long value x, this method returns +1L if x >= 0 and -1L if x < 0.

Parameters:

x - the value, a long

Returns:

+1L or -1L, depending on the sign of x

indicator

public static short indicator(short x)

For a short value x, this method returns (short)(+1) if x >= 0 and (short)(-1) if x < 0.

Parameters:

x - the value, a short

Returns:

(short)(+1) or (short)(-1), depending on the sign of x

log

public static double log(double base,
                         double x)

Returns the logarithm for base b of x.

Returns NaN if either argument is negative. If base is 0 and x is positive, 0 is returned. If base is positive and x is 0, Double.NEGATIVE_INFINITY is returned. If both arguments are 0, the result is NaN.

Parameters:

base - the base of the logarithm, must be greater than 0

x - argument, must be greater than 0

Returns:

the value of the logarithm - the number y such that base^y = x.

Since:

1.2

normalizeAngle

public static double normalizeAngle(double a,
                                    double center)

Normalize an angle in a 2&pi 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.

round

public static double round(double x,
                           int scale)

Round the given value to the specified number of decimal places. The value is rounded using the BigDecimal.ROUND_HALF_UP method.

Parameters:

x - the value to round.

scale - the number of digits to the right of the decimal point.

Returns:

the rounded value.

Since:

1.1

round

public static double round(double x,
                           int scale,
                           int roundingMethod)

Round the given value to the specified number of decimal places. The value is rounded using the given method which is any method defined in BigDecimal.

If x is infinite or NaN, then the value of x is returned unchanged, regardless of the other parameters.

Parameters:

x - the value to round.

scale - the number of digits to the right of the decimal point.

roundingMethod - the rounding method as defined in BigDecimal.

Returns:

the rounded value.

Throws:

java.lang.ArithmeticException - if roundingMethod==ROUND_UNNECESSARY and the specified scaling operation would require rounding.

java.lang.IllegalArgumentException - if roundingMethod does not represent a valid rounding mode.

Since:

1.1

round

public static float round(float x,
                          int scale)

Round the given value to the specified number of decimal places. The value is rounded using the BigDecimal.ROUND_HALF_UP method.

Parameters:

x - the value to round.

scale - the number of digits to the right of the decimal point.

Returns:

the rounded value.

Since:

1.1

round

public static float round(float x,
                          int scale,
                          int roundingMethod)

Round the given value to the specified number of decimal places. The value is rounded using the given method which is any method defined in BigDecimal.

Parameters:

x - the value to round.

scale - the number of digits to the right of the decimal point.

roundingMethod - the rounding method as defined in BigDecimal.

Returns:

the rounded value.

Since:

1.1

sign

public static byte sign(byte x)

Returns the sign for byte value x.

For a byte value x, this method returns (byte)(+1) if x > 0, (byte)(0) if x = 0, and (byte)(-1) if x < 0.

Parameters:

x - the value, a byte

Returns:

(byte)(+1), (byte)(0), or (byte)(-1), depending on the sign of x

copySign

public static byte copySign(byte magnitude,
                            byte sign)

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.

sign

public static int sign(int x)

Returns the sign for int value x.

For an int value x, this method returns +1 if x > 0, 0 if x = 0, and -1 if x < 0.

Parameters:

x - the value, an int

Returns:

+1, 0, or -1, depending on the sign of x

sign

public static long sign(long x)

Returns the sign for long value x.

For a long value x, this method returns +1L if x > 0, 0L if x = 0, and -1L if x < 0.

Parameters:

x - the value, a long

Returns:

+1L, 0L, or -1L, depending on the sign of x

sign

public static short sign(short x)

Compute the sign of the argument.

Parameters:

x - the value, a short

Returns:

1 if x > 0, 0 if x == 0, and -1 if x < 0.

pow

public static int pow(int k,
                      int e)

Raise an int to an int power.

Parameters:

k - Number to raise.

e - Exponent (must be positive or zero).

Returns:

k^e

Throws:

NotPositiveException - if e < 0.

pow

public static int pow(int k,
                      long e)

Raise an int to a long power.

Parameters:

k - Number to raise.

e - Exponent (must be positive or zero).

Returns:

k^e

Throws:

NotPositiveException - if e < 0.

pow

public static long pow(long k,
                       int e)

Raise a long to an int power.

Parameters:

k - Number to raise.

e - Exponent (must be positive or zero).

Returns:

k^e

Throws:

NotPositiveException - if e < 0.

pow

public static long pow(long k,
                       long e)

Raise a long to a long power.

Parameters:

k - Number to raise.

e - Exponent (must be positive or zero).

Returns:

k^e

Throws:

NotPositiveException - if e < 0.

pow

public static java.math.BigInteger pow(java.math.BigInteger k,
                                       int e)

Raise a BigInteger to an int power.

Parameters:

k - Number to raise.

e - Exponent (must be positive or zero).

Returns:

k^e

Throws:

NotPositiveException - if e < 0.

pow

public static java.math.BigInteger pow(java.math.BigInteger k,
                                       long e)

Raise a BigInteger to a long power.

Parameters:

k - Number to raise.

e - Exponent (must be positive or zero).

Returns:

k^e

Throws:

NotPositiveException - if e < 0.

pow

public static java.math.BigInteger pow(java.math.BigInteger k,
                                       java.math.BigInteger e)

Raise a BigInteger to a BigInteger power.

Parameters:

k - Number to raise.

e - Exponent (must be positive or zero).

Returns:

k^e

Throws:

NotPositiveException - if e < 0.

checkFinite

public static void checkFinite(double x)

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)

Check that all the elements are real number.

Parameters:

val - Arguments.

Throws:

NotFiniteNumberException - if any values of the array is not a finite real number.

checkNotNull

public static void checkNotNull(java.lang.Object o,
                                Localizable pattern,
                                java.lang.Object... args)

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(java.lang.Object o)
                         throws NullArgumentException

Checks that an object is not null.

Parameters:

o - Object to be checked.

Throws:

NullArgumentException - if o is null.