org.geotoolkit.math
Class XMath

Object
  Static
      XMath

public final class XMath
extends Static

Simple mathematical functions in addition to the ones provided in Math.

Since:

1.0

Version:

3.20

Author:

Martin Desruisseaux (MPO, IRD, Geomatys)

Module:

utility/geotk-utility (download)

View source code for this class

Field Summary

static long	SIGN_BIT_MASK Bit mask to isolate the sign bit of non-NaN values in a double.
static double	SQRT2 The square root of 2, which is 1.4142135623730951.

Method Summary

static double	adjacentForType(Class<? extends Number> type, double value, int amount) Returns the number adjacent to the given value, as one of the nearest representable numbers of the given type.
static double	atanh(double x) Returns the inverse hyperbolic tangent of the given value.
static int[]	commonDivisors(int... numbers) Returns the divisors which are common to all the specified numbers.
static int	countDecimalFractionDigits(double value) Deprecated. Was used by trimDecimalFractionDigits(double, int, int), which has been deprecated.
static int[]	divisors(int number) Returns the divisors of the specified number as positive integers.
static boolean	isNegative(double value) Returns true if the given value is negative, including negative zero.
static boolean	isPositive(double value) Returns true if the given value is positive, excluding negative zero.
static boolean	isSameSign(double v1, double v2) Returns true if the given values have the same sign, differentiating positive and negative zeros.
static double	magnitude(double... vector) Returns the magnitude of the given vector.
static double	pow10(double x) Computes 10 raised to the power of x.
static double	pow10(int x) Computes 10 raised to the power of x.
static int	primeNumber(int index) Returns the ith prime number.
static double	roundIfAlmostInteger(double value, int maxULP) Deprecated. This method is inefficient, and the work to do about rounding error is a bit too much implementation specific anyway.
static byte	sgn(byte x) Returns the sign of x.
static int	sgn(double x) Returns the sign of x.
static int	sgn(float x) Returns the sign of x.
static int	sgn(int x) Returns the sign of x.
static int	sgn(long x) Returns the sign of x.
static short	sgn(short x) Returns the sign of x.
static float	toNaN(int index) Returns a NaN number for the specified index.
static double	trimDecimalFractionDigits(double value, int maxULP, int n) Deprecated. This method is inefficient, and the work to do about rounding error is a bit too much implementation specific anyway.
static double	xorSign(double value, double sign) Returns the first floating-point argument with the sign reversed if the second floating-point argument is negative.

Methods inherited from class Object

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

Field Detail

SQRT2

public static final double SQRT2

The square root of 2, which is 1.4142135623730951.

Since:

3.20

See Also:

Constant Field Values

SIGN_BIT_MASK

public static final long SIGN_BIT_MASK

Bit mask to isolate the sign bit of non-NaN values in a double. For any value other than NaN, the following code evaluate to 0 if the given value is positive:

Double.doubleToRawLongBits(value) & SIGN_BIT_MASK;

Note that this idiom differentiates positive zero from negative zero. It should be used only when such difference matter.

Since:

3.20

See Also:

isPositive(double), isNegative(double), Constant Field Values

Method Detail

magnitude

public static double magnitude(double... vector)

Returns the magnitude of the given vector. This is defined by:

sqrt(vector[0]² + vector[1]² + … + vector[length-1]²)

Implementation note
In the special case where only one element is different than zero, this method returns directly the absolute value of that element without computing sqrt(v²), in order to avoid rounding error. This special case has been implemented because this method is often invoked for computing the length of offset vectors, typically aligned with the axes of a Cartesian coordinate system.

Parameters:

vector - The vector for which to compute the magnitude.

Returns:

The magnitude of the given vector.

Since:

3.09

See Also:

Math.hypot(double, double)

pow10

public static double pow10(double x)

Computes 10 raised to the power of x. This method delegates to pow10((int) x) if x is an integer, or to Math.pow(10, x) otherwise.

Parameters:

x - The exponent.

Returns:

10 raised to the given exponent.

See Also:

pow10(int), Math.pow(double, double)

pow10

public static double pow10(int x)

Computes 10 raised to the power of x. This method tries to be slightly more accurate than Math.pow(10,x), sometime at the cost of performance.

The Math.pow(10,x) method doesn't always return the closest IEEE floating point representation. More accurate calculations are slower and usually not necessary, but the base 10 is a special case since it is used for scaling axes or formatting human-readable output, in which case the precision may matter.

Parameters:

x - The exponent.

Returns:

10 raised to the given exponent.

atanh

public static double atanh(double x)

Returns the inverse hyperbolic tangent of the given value. This is the inverse of the tanh method. The range of input values is [-1…1]. Special cases:

For x = NaN, this method returns NaN.

For x = -1, this method returns negative infinity.

For x = +1, this method returns positive infinity.

Parameters:

x - The value for which to compute the inverse hyperbolic tangent.

Returns:

The inverse hyperbolic tangent of the given value.

Since:

3.20

See Also:

Math.tanh(double)

isPositive

public static boolean isPositive(double value)

Returns true if the given value is positive, excluding negative zero. Special cases:

• If the value is +0.0, returns true
• If the value is -0.0, returns false
• If the value is NaN, returns false

As seen from the above cases, this method distinguishes positive zero from negative zero. The handling of zero values is the difference between invoking isPositive(double) and testing if (value >= 0).

Parameters:

value - The value to test.

Returns:

true if the given value is positive, excluding negative zero.

Since:

3.20

isNegative

public static boolean isNegative(double value)

Returns true if the given value is negative, including negative zero. Special cases:

• If the value is +0.0, returns false
• If the value is -0.0, returns true
• If the value is NaN, returns false

As seen from the above cases, this method distinguishes positive zero from negative zero. The handling of zero values is the difference between invoking isNegative(double) and testing if (value < 0).

Parameters:

value - The value to test.

Returns:

true if the given value is negative, including negative zero.

Since:

3.20

isSameSign

public static boolean isSameSign(double v1,
                                 double v2)

Returns true if the given values have the same sign, differentiating positive and negative zeros. Special cases:

• +0.0 and -0.0 are considered to have opposite sign
• If any value is NaN, returns false

Parameters:

v1 - The first value.

v2 - The second value, to compare the sign with the first value.

Returns:

true if the given values are not NaN and have the same sign.

Since:

3.20

See Also:

Math.signum(double)

sgn

public static int sgn(double x)

Returns the sign of x. This method returns -1 if x is negative, 0 if x is zero or NaN and +1 if x is positive.

Parameters:

x - The number from which to get the sign.

Returns:

+1 if x is positive, -1 if negative, or 0 otherwise.

See Also:

Math.signum(double)

sgn

public static int sgn(float x)

Returns the sign of x. This method returns -1 if x is negative, 0 if x is zero or NaN and +1 if x is positive.

Parameters:

x - The number from which to get the sign.

Returns:

+1 if x is positive, -1 if negative, or 0 otherwise.

See Also:

Math.signum(float)

sgn

public static int sgn(long x)

Returns the sign of x. This method returns -1 if x is negative, 0 if x is zero and +1 if x is positive.

Parameters:

x - The number from which to get the sign.

Returns:

+1 if x is positive, -1 if negative, or 0 otherwise.

sgn

public static int sgn(int x)

Returns the sign of x. This method returns -1 if x is negative, 0 if x is zero and +1 if x is positive.

Parameters:

x - The number from which to get the sign.

Returns:

+1 if x is positive, -1 if negative, or 0 otherwise.

sgn

public static short sgn(short x)

Returns the sign of x. This method returns -1 if x is negative, 0 if x is zero and +1 if x is positive.

Parameters:

x - The number from which to get the sign.

Returns:

+1 if x is positive, -1 if negative, or 0 otherwise.

sgn

public static byte sgn(byte x)

Returns the sign of x. This method returns -1 if x is negative, 0 if x is zero and +1 if x is positive.

Parameters:

x - The number from which to get the sign.

Returns:

+1 if x is positive, -1 if negative, or 0 otherwise.

xorSign

public static double xorSign(double value,
                             double sign)

Returns the first floating-point argument with the sign reversed if the second floating-point argument is negative. This method is similar to Math.copySign(value, sign) except that the sign is combined with an exclusive or operation instead than being copied.

This method computes the same result than the formula below (using only standard functions from Math) except that zeros and Double.NaN values for the sign argument are treated as a positive or negative numbers.

return magnitude * signum(sign);

Parameters:

value - The parameter providing the value that may need a sign change.

sign - The parameter providing the sign to xor with the value.

Returns:

The provided value with its sign reversed if the sign parameter is negative.

Since:

3.00

See Also:

Math.copySign(double, double)

adjacentForType

public static double adjacentForType(Class<? extends Number> type,
                                     double value,
                                     int amount)
                              throws IllegalArgumentException

Returns the number adjacent to the given value, as one of the nearest representable numbers of the given type. First this method selects the nearest adjacent value in the direction of positive infinity if amount is positive, or in the direction of negative infinity if amount is negative. Then this operation is repeated as many time as the absolute value of amount. More specifically:

• If type is an integer type (Integer, Short, etc.), then this method returns value + amount. If value had a fractional part, then this part is truncated before the addition is performed.

• If type is Double, then this method is equivalent to invoking Math.nextUp(value) if amount is positive, or -Math.nextUp(-value) if amount is negative, and to repeat this operation abs(amount) times.

• If type is Float, then this method is equivalent to invoking Math.nextUp((float) value) if amount is positive, or -Math.nextUp((float) -value) if amount is negative, and to repeat this operation abs(amount) times.

Parameters:

type - The type. Should be the class of Double, Float, Long, Integer, Short or Byte.

value - The number for which to find an adjacent number.

amount - -1 to return the previous representable number, +1 to return the next representable number, or a multiple of the above.

Returns:

One of previous or next representable number as a double.

Throws:

IllegalArgumentException - if type is not one of supported types.

roundIfAlmostInteger

@Deprecated
public static double roundIfAlmostInteger(double value,
                                                     int maxULP)

Deprecated. This method is inefficient, and the work to do about rounding error is a bit too much implementation specific anyway.

Rounds the specified value, providing that the difference between the original value and the rounded value is not greater than the specified amount of floating point units. This method can be used for hiding floating point error likes 2.9999999996.

Parameters:

value - The value to round.

maxULP - The maximal change allowed in ULPs (Unit in the Last Place).

Returns:

The rounded value, of value if it was not close enough to an integer.

trimDecimalFractionDigits

@Deprecated
public static double trimDecimalFractionDigits(double value,
                                                          int maxULP,
                                                          int n)

Deprecated. This method is inefficient, and the work to do about rounding error is a bit too much implementation specific anyway.

Tries to remove at least n fraction digits in the decimal representation of the specified value. This method tries small changes to value, by adding or subtracting up to maxULP (Unit in the Last Place). If there is no small change that remove at least n fraction digits, then the value is returned unchanged. This method is used for hiding rounding errors, like in conversions from radians to degrees.

Example: XMath.trimLastDecimalDigits(-61.500000000000014, 12, 4) returns -61.5.

Parameters:

value - The value to fix.

maxULP - The maximal change allowed in ULPs (Unit in the Last Place). A typical value is 4.

n - The minimum amount of fraction digits.

Returns:

The trimmed value, or the unchanged value if there is no small change that remove at least n fraction digits.

countDecimalFractionDigits

@Deprecated
public static int countDecimalFractionDigits(double value)

Deprecated. Was used by trimDecimalFractionDigits(double, int, int), which has been deprecated.

Counts the fraction digits in the string representation of the specified value. This method is equivalent to a calling Double.toString(value) and counting the number of digits after the decimal separator.

Parameters:

value - The value for which to count the fraction digits.

Returns:

The number of fraction digits.

toNaN

public static float toNaN(int index)
                   throws IndexOutOfBoundsException

Returns a NaN number for the specified index. Valid NaN numbers have bit fields ranging from 0x7f800001 through 0x7fffffff or 0xff800001 through 0xffffffff. The standard Float.NaN has bit fields 0x7fc00000. See Float.intBitsToFloat(int) for more details on NaN bit values.

Tip: if the caller needs to ensure that the index is never out of bounds, he can set the parameter value to index % 0x200000.

Parameters:

index - The index, from -2097152 to 2097151 inclusive.

Returns:

One of the legal NaN values as a float.

Throws:

IndexOutOfBoundsException - if the specified index is out of bounds.

See Also:

Float.intBitsToFloat(int)

primeNumber

public static int primeNumber(int index)
                       throws IndexOutOfBoundsException

Returns the i^th prime number. This method returns (2, 3, 5, 7, 11...) for index (0, 1, 2, 3, 4, ...). This method is designed for relatively small prime numbers only; don't use it for large values.

Parameters:

index - The prime number index, starting at index 0 for prime number 2.

Returns:

The prime number at the specified index.

Throws:

IndexOutOfBoundsException - if the specified index is too large.

See Also:

BigInteger.isProbablePrime(int)

divisors

public static int[] divisors(int number)

Returns the divisors of the specified number as positive integers. For any value other than O (which returns an empty array), the first element in the returned array is always 1 and the last element is always the absolute value of number.

Parameters:

number - The number for which to compute the divisors.

Returns:

The divisors in strictly increasing order.

commonDivisors

public static int[] commonDivisors(int... numbers)

Returns the divisors which are common to all the specified numbers.

Parameters:

numbers - The numbers for which to compute the divisors.

Returns:

The divisors common to all the given numbers, in strictly increasing order.

Since:

3.15