Package org.apache.sis.util
Class Numbers

public final class Numbers extends Static
Static methods working withNumber
objects, and a few primitive types by extension. Since:
 0.3
 See Also:
MathFunctions
Defined in the
sisutility
module


Field Summary
Fields Modifier and Type Field Description static byte
BIG_DECIMAL
Constant of value 11 used inswitch
statements or as index in arrays.static byte
BIG_INTEGER
Constant of value 10 used inswitch
statements or as index in arrays.static byte
BOOLEAN
Constant of value 1 used inswitch
statements or as index in arrays.static byte
BYTE
Constant of value 3 used inswitch
statements or as index in arrays.static byte
CHARACTER
Constant of value 2 used inswitch
statements or as index in arrays.static byte
DOUBLE
Constant of value 9 used inswitch
statements or as index in arrays.static byte
FLOAT
Constant of value 8 used inswitch
statements or as index in arrays.static byte
FRACTION
Constant of value 7 used inswitch
statements or as index in arrays.static byte
INTEGER
Constant of value 5 used inswitch
statements or as index in arrays.static byte
LONG
Constant of value 6 used inswitch
statements or as index in arrays.static byte
OTHER
Constant of value 0 used inswitch
statements or as index in arrays.static byte
SHORT
Constant of value 4 used inswitch
statements or as index in arrays.

Method Summary
All Methods Static Methods Concrete Methods Modifier and Type Method Description static <N extends Number>
Ncast(Number number, Class<N> type)
Casts a number to the specified type.static byte
getEnumConstant(Class<?> type)
Returns a numeric constant for the given type.static boolean
isFloat(Class<?> type)
Returnstrue
if the giventype
is a floating point type.static boolean
isInteger(Class<?> type)
Returnstrue
if the giventype
is an integer type.static Class<? extends Number>
narrowestClass(Class<? extends Number> c1, Class<? extends Number> c2)
Returns the narrowest of the given types.static Class<? extends Number>
narrowestClass(Number value)
Returns the smallest class capable to hold the specified value.static Class<? extends Number>
narrowestClass(Number n1, Number n2)
Returns the narrowest type of two numbers.static Number
narrowestNumber(Number value)
Returns the given number wrapped in the smallest class capable to hold the specified value.static Number
narrowestNumber(String value)
Returns the smallest number capable to hold the specified value.static int
primitiveBitCount(Class<?> type)
Returns the number of bits used by primitive of the specified type.static Class<?>
primitiveToWrapper(Class<?> type)
Changes a primitive class to its wrapper (for exampleint
toInteger
).static <T> T
valueOf(String value, Class<T> type)
Converts the specified string into a value object.static <T> T
valueOfNil(Class<T> type)
Returns aNaN
, zero, empty ornull
value of the given type.static Class<? extends Number>
widestClass(Class<? extends Number> c1, Class<? extends Number> c2)
Returns the widest of the given types.static Class<? extends Number>
widestClass(Number n1, Number n2)
Returns the widest type of two numbers.static <N extends Number>
Nwrap(double value, Class<N> type)
Wraps the given floatingpoint value in aNumber
of the specified class.static <N extends Number>
Nwrap(long value, Class<N> type)
Wraps the given integer value in aNumber
of the specified class.static Class<?>
wrapperToPrimitive(Class<?> type)
Changes a wrapper class to its primitive (for exampleInteger
toint
).



Field Detail

BIG_DECIMAL
public static final byte BIG_DECIMAL
Constant of value 11 used inswitch
statements or as index in arrays. This enumeration provides the following guarantees (some Apache SIS codes rely on them):OTHER
value is 0. Primitive types are enumerated in this exact order
(from lower value to higher value, but not necessarily as consecutive values):
BYTE
,SHORT
,INTEGER
,LONG
,FLOAT
,DOUBLE
. java.math
types of greater capacity than primitive types (BIG_DECIMAL
andBIG_INTEGER
) have higher enumeration values.Fraction
is considered as a kind of floating point value.
 See Also:
 Constant Field Values

BIG_INTEGER
public static final byte BIG_INTEGER
Constant of value 10 used inswitch
statements or as index in arrays. This enumeration provides the following guarantees (some Apache SIS codes rely on them):OTHER
value is 0. Primitive types are enumerated in this exact order
(from lower value to higher value, but not necessarily as consecutive values):
BYTE
,SHORT
,INTEGER
,LONG
,FLOAT
,DOUBLE
. java.math
types of greater capacity than primitive types (BIG_DECIMAL
andBIG_INTEGER
) have higher enumeration values.Fraction
is considered as a kind of floating point value.
 See Also:
 Constant Field Values

FRACTION
public static final byte FRACTION
Constant of value 7 used inswitch
statements or as index in arrays. This enumeration provides the following guarantees (some Apache SIS codes rely on them):OTHER
value is 0. Primitive types are enumerated in this exact order
(from lower value to higher value, but not necessarily as consecutive values):
BYTE
,SHORT
,INTEGER
,LONG
,FLOAT
,DOUBLE
. java.math
types of greater capacity than primitive types (BIG_DECIMAL
andBIG_INTEGER
) have higher enumeration values.Fraction
is considered as a kind of floating point value.
 See Also:
 Constant Field Values

DOUBLE
public static final byte DOUBLE
Constant of value 9 used inswitch
statements or as index in arrays. This enumeration provides the following guarantees (some Apache SIS codes rely on them):OTHER
value is 0. Primitive types are enumerated in this exact order
(from lower value to higher value, but not necessarily as consecutive values):
BYTE
,SHORT
,INTEGER
,LONG
,FLOAT
,DOUBLE
. java.math
types of greater capacity than primitive types (BIG_DECIMAL
andBIG_INTEGER
) have higher enumeration values.Fraction
is considered as a kind of floating point value.
 See Also:
 Constant Field Values

FLOAT
public static final byte FLOAT
Constant of value 8 used inswitch
statements or as index in arrays. This enumeration provides the following guarantees (some Apache SIS codes rely on them):OTHER
value is 0. Primitive types are enumerated in this exact order
(from lower value to higher value, but not necessarily as consecutive values):
BYTE
,SHORT
,INTEGER
,LONG
,FLOAT
,DOUBLE
. java.math
types of greater capacity than primitive types (BIG_DECIMAL
andBIG_INTEGER
) have higher enumeration values.Fraction
is considered as a kind of floating point value.
 See Also:
 Constant Field Values

LONG
public static final byte LONG
Constant of value 6 used inswitch
statements or as index in arrays. This enumeration provides the following guarantees (some Apache SIS codes rely on them):OTHER
value is 0. Primitive types are enumerated in this exact order
(from lower value to higher value, but not necessarily as consecutive values):
BYTE
,SHORT
,INTEGER
,LONG
,FLOAT
,DOUBLE
. java.math
types of greater capacity than primitive types (BIG_DECIMAL
andBIG_INTEGER
) have higher enumeration values.Fraction
is considered as a kind of floating point value.
 See Also:
 Constant Field Values

INTEGER
public static final byte INTEGER
Constant of value 5 used inswitch
statements or as index in arrays. This enumeration provides the following guarantees (some Apache SIS codes rely on them):OTHER
value is 0. Primitive types are enumerated in this exact order
(from lower value to higher value, but not necessarily as consecutive values):
BYTE
,SHORT
,INTEGER
,LONG
,FLOAT
,DOUBLE
. java.math
types of greater capacity than primitive types (BIG_DECIMAL
andBIG_INTEGER
) have higher enumeration values.Fraction
is considered as a kind of floating point value.
 See Also:
 Constant Field Values

SHORT
public static final byte SHORT
Constant of value 4 used inswitch
statements or as index in arrays. This enumeration provides the following guarantees (some Apache SIS codes rely on them):OTHER
value is 0. Primitive types are enumerated in this exact order
(from lower value to higher value, but not necessarily as consecutive values):
BYTE
,SHORT
,INTEGER
,LONG
,FLOAT
,DOUBLE
. java.math
types of greater capacity than primitive types (BIG_DECIMAL
andBIG_INTEGER
) have higher enumeration values.Fraction
is considered as a kind of floating point value.
 See Also:
 Constant Field Values

BYTE
public static final byte BYTE
Constant of value 3 used inswitch
statements or as index in arrays. This enumeration provides the following guarantees (some Apache SIS codes rely on them):OTHER
value is 0. Primitive types are enumerated in this exact order
(from lower value to higher value, but not necessarily as consecutive values):
BYTE
,SHORT
,INTEGER
,LONG
,FLOAT
,DOUBLE
. java.math
types of greater capacity than primitive types (BIG_DECIMAL
andBIG_INTEGER
) have higher enumeration values.Fraction
is considered as a kind of floating point value.
 See Also:
 Constant Field Values

CHARACTER
public static final byte CHARACTER
Constant of value 2 used inswitch
statements or as index in arrays. This enumeration provides the following guarantees (some Apache SIS codes rely on them):OTHER
value is 0. Primitive types are enumerated in this exact order
(from lower value to higher value, but not necessarily as consecutive values):
BYTE
,SHORT
,INTEGER
,LONG
,FLOAT
,DOUBLE
. java.math
types of greater capacity than primitive types (BIG_DECIMAL
andBIG_INTEGER
) have higher enumeration values.Fraction
is considered as a kind of floating point value.
 See Also:
 Constant Field Values

BOOLEAN
public static final byte BOOLEAN
Constant of value 1 used inswitch
statements or as index in arrays. This enumeration provides the following guarantees (some Apache SIS codes rely on them):OTHER
value is 0. Primitive types are enumerated in this exact order
(from lower value to higher value, but not necessarily as consecutive values):
BYTE
,SHORT
,INTEGER
,LONG
,FLOAT
,DOUBLE
. java.math
types of greater capacity than primitive types (BIG_DECIMAL
andBIG_INTEGER
) have higher enumeration values.Fraction
is considered as a kind of floating point value.
 See Also:
 Constant Field Values

OTHER
public static final byte OTHER
Constant of value 0 used inswitch
statements or as index in arrays. This enumeration provides the following guarantees (some Apache SIS codes rely on them):OTHER
value is 0. Primitive types are enumerated in this exact order
(from lower value to higher value, but not necessarily as consecutive values):
BYTE
,SHORT
,INTEGER
,LONG
,FLOAT
,DOUBLE
. java.math
types of greater capacity than primitive types (BIG_DECIMAL
andBIG_INTEGER
) have higher enumeration values.Fraction
is considered as a kind of floating point value.
 See Also:
 Constant Field Values


Method Detail

isFloat
public static boolean isFloat(Class<?> type)
Returnstrue
if the giventype
is a floating point type. The floating point types areFloat
,float
,Double
,double
andBigDecimal
.Fraction
is also considered as a kind of floating point values. Parameters:
type
 the primitive type or wrapper class to test (can benull
). Returns:
true
iftype
is one of the known types capable to represent floating point numbers. See Also:
isInteger(Class)

isInteger
public static boolean isInteger(Class<?> type)
Returnstrue
if the giventype
is an integer type. The integer types areByte
,byte
,Short
,short
,Integer
,int
,Long
,long
andBigInteger
. Parameters:
type
 the primitive type or wrapper class to test (can benull
). Returns:
true
iftype
is an integer type. See Also:
isFloat(Class)

primitiveBitCount
public static int primitiveBitCount(Class<?> type) throws IllegalArgumentException
Returns the number of bits used by primitive of the specified type. The given type must be a primitive type or its wrapper class. Parameters:
type
 the primitive type (can benull
). Returns:
 the number of bits, or 0 if
type
is null.  Throws:
IllegalArgumentException
 if the given type is not one of the types supported by thisNumbers
class.

primitiveToWrapper
public static Class<?> primitiveToWrapper(Class<?> type)
Changes a primitive class to its wrapper (for exampleint
toInteger
). If the specified class is not a primitive type, then it is returned unchanged. Parameters:
type
 the primitive type (can benull
). Returns:
 the type as a wrapper.
 See Also:
wrapperToPrimitive(Class)

wrapperToPrimitive
public static Class<?> wrapperToPrimitive(Class<?> type)
Changes a wrapper class to its primitive (for exampleInteger
toint
). If the specified class is not a wrapper type, then it is returned unchanged. Parameters:
type
 the wrapper type (can benull
). Returns:
 the type as a primitive.
 See Also:
primitiveToWrapper(Class)

widestClass
public static Class<? extends Number> widestClass(Number n1, Number n2) throws IllegalArgumentException
Returns the widest type of two numbers. Numbersn1
andn2
can be instance ofByte
,Short
,Integer
,Long
,Float
,Double
,Fraction
,BigInteger
orBigDecimal
types.If one of the given argument is null, then this method returns the class of the nonnull argument. If both arguments are null, then this method returns
null
. Parameters:
n1
 the first number, ornull
.n2
 the second number, ornull
. Returns:
 the widest type of the given numbers, or
null
if bothn1
andn2
are null.  Throws:
IllegalArgumentException
 if a number is not an instance of a supported type. See Also:
widestClass(Number, Number)
,narrowestClass(Number, Number)

widestClass
public static Class<? extends Number> widestClass(Class<? extends Number> c1, Class<? extends Number> c2) throws IllegalArgumentException
Returns the widest of the given types. Classesc1
andc2
can beByte
,Short
,Integer
,Long
,Float
,Double
,Fraction
,BigInteger
orBigDecimal
types.If one of the given argument is null, then this method returns the nonnull argument. If both arguments are null, then this method returns
null
.Example: in the following code,type
is set toLong.class
:Class<?> type = widestClass(Short.class, Long.class);
 Parameters:
c1
 the first number type, ornull
.c2
 the second number type, ornull
. Returns:
 the widest of the given types, or
null
if bothc1
andc2
are null.  Throws:
IllegalArgumentException
 if one of the given types is not supported by thisNumbers
class. See Also:
widestClass(Class, Class)
,narrowestClass(Number, Number)

narrowestClass
public static Class<? extends Number> narrowestClass(Number n1, Number n2) throws IllegalArgumentException
Returns the narrowest type of two numbers. Numbersn1
andn2
can be instance ofByte
,Short
,Integer
,Long
,Float
,Double
,Fraction
,BigInteger
orBigDecimal
types. Parameters:
n1
 the first number, ornull
.n2
 the second number, ornull
. Returns:
 the narrowest type of the given numbers, or
null
if bothn1
andn2
are null.  Throws:
IllegalArgumentException
 if a number is not an instance of a supported type. See Also:
narrowestClass(Class, Class)
,widestClass(Class, Class)

narrowestClass
public static Class<? extends Number> narrowestClass(Class<? extends Number> c1, Class<? extends Number> c2) throws IllegalArgumentException
Returns the narrowest of the given types. Classesc1
andc2
can beByte
,Short
,Integer
,Long
,Float
,Double
,Fraction
,BigInteger
orBigDecimal
types.If one of the given argument is null, then this method returns the nonnull argument. If both arguments are null, then this method returns
null
.Example: in the following code,type
is set toShort.class
:Class<?> type = widestClass(Short.class, Long.class);
 Parameters:
c1
 the first number type, ornull
.c2
 the second number type, ornull
. Returns:
 the narrowest of the given types, or
null
if bothc1
andc2
are null.  Throws:
IllegalArgumentException
 if one of the given types is not supported by thisNumbers
class. See Also:
narrowestClass(Number, Number)
,widestClass(Class, Class)

narrowestClass
public static Class<? extends Number> narrowestClass(Number value)
Returns the smallest class capable to hold the specified value. This method applies the following choices, in that order: If the given value is
null
, then this method returnsnull
.  Otherwise if the given value can not be casted from
double
to another type without precision lost, returnDouble.class
.  Otherwise if the given value can not be casted from
float
to another type without precision lost, returnFloat.class
.  Otherwise if the given value is between 128 and
127, then this method returns
Byte.class
;  Otherwise if the given value is between 32768 and
32767, then this method returns
Short.class
;  Otherwise if the given value is between 2147483648 and
2147483647, then this method returns
Integer.class
;  Otherwise this method returns
Long.class
;
 Parameters:
value
 the value to be wrapped in a finer (if possible)Number
. Returns:
 the narrowest type capable to hold the given value.
 See Also:
narrowestNumber(Number)
 If the given value is

narrowestNumber
public static Number narrowestNumber(Number value)
Returns the given number wrapped in the smallest class capable to hold the specified value. This method is equivalent to the following code, in a slightly more efficient way:return cast(value, narrowestClass(value));
 Parameters:
value
 the value to be wrapped in a finer (if possible)Number
. Returns:
 the narrowest type capable to hold the given value.
 See Also:
narrowestClass(Number)
,cast(Number, Class)

narrowestNumber
public static Number narrowestNumber(String value) throws NumberFormatException
Returns the smallest number capable to hold the specified value. Parameters:
value
 the value to be wrapped in aNumber
. Returns:
 the narrowest type capable to hold the given value.
 Throws:
NumberFormatException
 if the given value can not be parsed as a number. See Also:
narrowestNumber(Number)

cast
public static <N extends Number> N cast(Number number, Class<N> type) throws IllegalArgumentException
Casts a number to the specified type. The target type can be one ofByte
,Short
,Integer
,Long
,Float
,Double
,Fraction
,BigInteger
orBigDecimal
. This method makes the following choice: If the given value is
null
or an instance of the given type, then it is returned unchanged.  Otherwise if the given type is
Double.class
, then this method returnsDouble.valueOf(number.doubleValue())
;  Otherwise if the given type is
Float.class
, then this method returnsFloat.valueOf(number.floatValue())
;  And likewise for all remaining known types.
widestClass(Class, Class)
ornarrowestClass(Number)
. If nevertheless the given type is not wide enough, then the behavior depends on the implementation of the correspondingNumber.fooValue()
method  typically, the value is just rounded or truncated. Type Parameters:
N
 the class to cast to. Parameters:
number
 the number to cast, ornull
.type
 the destination type. Returns:
 the number casted to the given type, or
null
if the given value was null.  Throws:
IllegalArgumentException
 if the given type is not supported by thisNumbers
class, or the type isFRACTION
and the given number can not be converted to that type.
 If the given value is

wrap
public static <N extends Number> N wrap(double value, Class<N> type) throws IllegalArgumentException
Wraps the given floatingpoint value in aNumber
of the specified class. The given type shall be one ofByte
,Short
,Integer
,Long
,Float
,Double
,Fraction
,BigInteger
andBigDecimal
classes. Furthermore, the given value shall be convertible to the given class without precision lost, otherwise anIllegalArgumentException
will be thrown. Type Parameters:
N
 the wrapper class. Parameters:
value
 the value to wrap.type
 the desired wrapper class. Returns:
 the value wrapped in an object of the given class.
 Throws:
IllegalArgumentException
 if the given type is not supported by thisNumbers
class, or if the given value can not be wrapped in an instance of the given class without precision lost.

wrap
public static <N extends Number> N wrap(long value, Class<N> type) throws IllegalArgumentException
Wraps the given integer value in aNumber
of the specified class. The given type shall be one ofByte
,Short
,Integer
,Long
,Float
,Double
,Fraction
,BigInteger
andBigDecimal
classes. Furthermore, the given value shall be convertible to the given class without precision lost, otherwise anIllegalArgumentException
will be thrown. Type Parameters:
N
 the wrapper class. Parameters:
value
 the value to wrap.type
 the desired wrapper class. Returns:
 the value wrapped in an object of the given class.
 Throws:
IllegalArgumentException
 if the given type is not supported by thisNumbers
class, or if the given value can not be wrapped in an instance of the given class without precision lost. Since:
 0.8

valueOf
public static <T> T valueOf(String value, Class<T> type) throws IllegalArgumentException, NumberFormatException
Converts the specified string into a value object. The value object can be an instance ofBigDecimal
,BigInteger
,Fraction
,Double
,Float
,Long
,Integer
,Short
,Byte
,Boolean
,Character
orString
according the specified type. This method makes the following choice: If the given type is
Double.class
, then this method returnsDouble.valueOf(value)
;  If the given type is
Float.class
, then this method returnsFloat.valueOf(value)
;  And likewise for all remaining known types.
 Type Parameters:
T
 the requested type. Parameters:
value
 the value to parse.type
 the requested type. Returns:
 the value object, or
null
ifvalue
was null.  Throws:
IllegalArgumentException
 iftype
is not a recognized type.NumberFormatException
 iftype
is a subclass ofNumber
and the string value is not parsable as a number of the specified type.
 If the given type is

valueOfNil
public static <T> T valueOfNil(Class<T> type)
Returns aNaN
, zero, empty ornull
value of the given type. This method tries to return the closest value that can be interpreted as "none", which is usually not the same than "zero". More specifically: If the given type is a floating point primitive type (
float
ordouble
), then this method returnsFloat.NaN
orDouble.NaN
depending on the given type.  If the given type is an integer primitive type or the character type
(
long
,int
,short
,byte
orchar
), then this method returns the zero value of the given type.  If the given type is the
boolean
primitive type, then this method returnsBoolean.FALSE
.  If the given type is an array or a collection, then this method returns an empty array or collection. The given type is honored on a best effort basis.
 For all other cases, including the wrapper classes of primitive types, this method
returns
null
.
Numbers
class, the scope of this method has been extended to array and collection types because those objects can also be seen as mathematical concepts. Type Parameters:
T
 the compiletime type of the requested object. Parameters:
type
 the type of the object for which to get a nil value. Returns:
 an object of the given type which represents a nil value, or
null
.  See Also:
NilObject
 If the given type is a floating point primitive type (

getEnumConstant
public static byte getEnumConstant(Class<?> type)
Returns a numeric constant for the given type. The constants areBIG_DECIMAL
,BIG_INTEGER
,FRACTION
,DOUBLE
,FLOAT
,LONG
,INTEGER
,SHORT
,BYTE
,CHARACTER
,BOOLEAN
, orOTHER
constants for the given type. This is a commodity for usage inswitch
statements. Parameters:
type
 a type (usually either a primitive type or its wrapper), ornull
. Returns:
 the constant for the given type, or
OTHER
if unknown.

