public final class MathFunctions extends Static
Math
.
Some methods in this class are very similar to the standard Math
methods
or could be implemented with straightforward formulas.
However the methods in this class put an emphasis on:
magnitude
,
pow10
.isPositive
,
isNegative
,
isSameSign
,
xorSign
.toNanFloat
,
toNanOrdinal
.Math
are:
atanh
,
nextPrimeNumber
.Numbers
Defined in the sis-utility module
Modifier and Type | Field and Description |
---|---|
static int |
HIGHEST_SUPPORTED_PRIME_NUMBER
The highest prime number supported by the
nextPrimeNumber(int) method. |
static double |
SQRT_2
The square root of 2, which is 1.4142135623730951.
|
Modifier and Type | Method and Description |
---|---|
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[] |
divisors(int number)
Returns the divisors of the specified number as positive integers.
|
static boolean |
epsilonEqual(double v1,
double v2,
double ε)
Returns
true if the given values are equal
or if their difference is not greater than the given threshold. |
static boolean |
epsilonEqual(float v1,
float v2,
float ε)
Returns
true if the given values are equal
or if their difference is not greater than the given threshold. |
static int |
fractionDigitsForDelta(double accuracy,
boolean strict)
Returns the number of fraction digits needed for formatting in base 10 numbers of the given
accuracy.
|
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 int |
nextPrimeNumber(int number)
Returns the first prime number equals or greater than the given value.
|
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 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 |
toNanFloat(int ordinal)
Returns a NaN number for the specified ordinal value.
|
static int |
toNanOrdinal(float value)
Returns the ordinal value of the given NaN number.
|
static double |
truncate(double value)
Truncates the given value toward zero.
|
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.
|
public static final double SQRT_2
Math.sqrt(double)
,
Constant Field Valuespublic static final int HIGHEST_SUPPORTED_PRIME_NUMBER
nextPrimeNumber(int)
method.
In the current implementation, this value is 65521. However this limit may
change in any future Apache SIS version.
Note: The current value is the highest prime number representable as an unsigned 16 bits integer. This is enough for current needs because 16 bits prime numbers are sufficient for finding the divisors of any 32 bits integers.
nextPrimeNumber(int)
,
Constant Field Valuespublic static double truncate(double value)
Math.floor(double)
if the value is positive, or Math.ceil(double)
if
the value is negative.value
- The value to truncate.public static double magnitude(double... vector)
sqrt(vector[0]² + vector[1]² + … + vector[length-1]²)
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.vector
- The vector for which to compute the magnitude.Math.hypot(double, double)
public static int fractionDigitsForDelta(double accuracy, boolean strict)
strict
argument is true
, then for any given accuracy
this method returns a value n such as the difference between adjacent numbers
formatted in base 10 with n fraction digits will always be equal or smaller
than accuracy
. Examples:
fractionDigitsForDelta(0.001, true)
returns 3.fractionDigitsForDelta(0.009, true)
returns 3.fractionDigitsForDelta(0.010, true)
returns 2.fractionDigitsForDelta(0.099, true)
returns 3 (special case).Special cases:
accuracy
is 0, NaN
or infinity,
then this method returns 0.accuracy
is greater than 1, then this method returns
the number of "unnecessary" trailing zeros as a negative number.
For example fractionDigitsForDelta(100, …)
returns -2.accuracy
are equal or greater than 95
(e.g. 0.00099) and the strict
argument is true
, then this method
increases the number of needed fraction digits in order to prevent the rounded
number to be collapsed into the next integer value.
Example: If {@code accuracy} is 0.95, then a return value of 1 is not sufficient since the rounded value of 0.95 with 1 fraction digit would be 1.0. Such value would be a violation of this method contract since the difference between 0 and that formatted value would be greater than the accuracy. Note that this is not an artificial rule; this is related to the fact that 0.9999… is mathematically strictly equals to 1.
Invoking this method is equivalent to computing (int)
-floor(log10(accuracy))
except for the 0, NaN
, infinities and 0.…95
special cases.
accuracy
- The desired accuracy of numbers to format in base 10.strict
- true
for checking the 0.…95
special case.
If false
, then the difference between adjacent formatted numbers is not
guaranteed to be smaller than accuracy
in every cases.NumberFormat.setMaximumFractionDigits(int)
public static double pow10(double x)
pow10((int) x)
if x is an
integer, or to Math.pow(10, x)
otherwise.x
- The exponent.pow10(int)
,
Math.pow(double, double)
@Workaround(library="JDK", version="1.4") public static double pow10(int x)
Math.pow(10, x)
,
sometime at the cost of performance.
Note:
This method has been defined because the standard Math.pow(10, x)
method does not always return the closest IEEE floating point representation.
Slight departures (1 or 2 ULP) are often allowed in math functions for performance
reasons. The most accurate calculations are usually not necessary, but the base 10
is a special case since it is used for scaling axes or formatting human-readable
output.
x
- The exponent.public static double atanh(double x)
x
- The value for which to compute the inverse hyperbolic tangent.Math.tanh(double)
public static boolean isPositive(double value)
true
if the given value is positive, excluding negative zero.
Special cases:
+0.0
, returns true
-0.0
, returns false
NaN
, returns false
isPositive(double)
and testing if (value >= 0).value
- The value to test.true
if the given value is positive, excluding negative zero.public static boolean isNegative(double value)
true
if the given value is negative, including negative zero.
Special cases:
+0.0
, returns false
-0.0
, returns true
NaN
, returns false
isNegative(double)
and testing if (value < 0).value
- The value to test.true
if the given value is negative, including negative zero.public static boolean isSameSign(double v1, double v2)
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 signNaN
, returns false
v1
- The first value.v2
- The second value, to compare the sign with the first value.true
if the given values are not NaN and have the same sign.Math.signum(double)
public static double xorSign(double value, double sign)
Math.copySign(value, sign)
except that the sign is combined with an exclusive
or operation instead than being copied.
This method makes no guarantee about whether NaN
values are handled as positive
or negative numbers. This is the same policy than Math.copySign(double, double)
.
value
- The parameter providing the value that may need a sign change.sign
- The parameter providing the sign to xor with the value.sign
parameter is negative.Math.copySign(double, double)
public static int sgn(double x)
NaN
and
+1 if x is positive.x
- The number from which to get the sign.+1
if x is positive, -1
if negative, or 0 otherwise.Math.signum(double)
public static int sgn(float x)
NaN
and
+1 if x is positive.x
- The number from which to get the sign.+1
if x is positive, -1
if negative, or 0 otherwise.Math.signum(float)
public static int sgn(long x)
x
- The number from which to get the sign.+1
if x is positive, -1
if negative, or 0 otherwise.public static int sgn(int x)
x
- The number from which to get the sign.+1
if x is positive, -1
if negative, or 0 otherwise.public static short sgn(short x)
x
- The number from which to get the sign.+1
if x is positive, -1
if negative, or 0 otherwise.public static byte sgn(byte x)
x
- The number from which to get the sign.+1
if x is positive, -1
if negative, or 0 otherwise.public static boolean epsilonEqual(float v1, float v2, float ε)
true
if the given values are equal
or if their difference is not greater than the given threshold. More specifically:
true
.true
.
Note that this method does not differentiate the various NaN values.abs(v1 - v2) <= ε
comparison.v1
- The first value to compare.v2
- The second value to compare.ε
- The tolerance threshold, which must be positive.true
If both values are equal given the tolerance threshold.public static boolean epsilonEqual(double v1, double v2, double ε)
true
if the given values are equal
or if their difference is not greater than the given threshold. More specifically:
true
.true
.
Note that this method does not differentiate the various NaN values.abs(v1 - v2) <= ε
comparison.v1
- The first value to compare.v2
- The second value to compare.ε
- The tolerance threshold, which must be positive.true
If both values are equal given the tolerance threshold.public static float toNanFloat(int ordinal) throws IllegalArgumentException
0x7F800001
… 0x7FFFFFFF
], with
0x7FC00000
as the bit fields of the standard Float.NaN
value0xFF800001
… 0xFFFFFFFF
]ordinal
- The NaN ordinal value, from -0x200000
to 0x1FFFFF
inclusive.IllegalArgumentException
- if the specified ordinal is out of range.Float.intBitsToFloat(int)
public static int toNanOrdinal(float value) throws IllegalArgumentException
toNanFloat(int)
.value
- The value from which to get the NaN ordinal value.IllegalArgumentException
- If the given value is not a NaN value,
or does not use a supported bits pattern.public static int nextPrimeNumber(int number) throws IllegalArgumentException
number
- The number for which to find the next prime.IllegalArgumentException
- If the given value is outside the supported range.BigInteger.isProbablePrime(int)
public static int[] divisors(int number)
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
.number
- The number for which to compute the divisors.public static int[] commonDivisors(int... numbers)
numbers
- The numbers for which to compute the divisors.Copyright © 2010–2013 The Apache Software Foundation. All rights reserved.