Package org.apache.sis.util
Class Numbers
Static methods working with
Number
objects, and a few primitive types by extension. Since:
 0.3
 See Also:
Defined in the sisutility
module

Field Summary
Modifier and TypeFieldDescriptionstatic final byte
Constant of value 0xb used inswitch
statements or as index in arrays.static final byte
Constant of value 0xa used inswitch
statements or as index in arrays.static final byte
Constant of value 0x1 used inswitch
statements or as index in arrays.static final byte
Constant of value 0x3 used inswitch
statements or as index in arrays.static final byte
Constant of value 0x2 used inswitch
statements or as index in arrays.static final byte
Constant of value 0x9 used inswitch
statements or as index in arrays.static final byte
Constant of value 0x8 used inswitch
statements or as index in arrays.static final byte
Constant of value 0x7 used inswitch
statements or as index in arrays.static final byte
Constant of value 0x5 used inswitch
statements or as index in arrays.static final byte
Constant of value 0x6 used inswitch
statements or as index in arrays.static final byte
Constant of value 0x0 used inswitch
statements or as index in arrays.static final byte
Constant of value 0x4 used inswitch
statements or as index in arrays. 
Method Summary
Modifier and TypeMethodDescriptionstatic <N extends Number>
NCasts a number to the specified type.static byte
getEnumConstant
(Class<?> type) Returns a numeric constant for the given type.static boolean
Returnstrue
if the giventype
is a floating point type.static boolean
isInteger
(Class<?> type) Returnstrue
if the giventype
is an integer type.static boolean
Returnstrue
if the given number is null or NaN.static boolean
Returnstrue
if the giventype
is a floating point or an integer type.narrowestClass
(Class<? extends Number> c1, Class<? extends Number> c2) Returns the narrowest of the given types.narrowestClass
(Number value) Returns the smallest class capable to hold the specified value.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 <N> Class<N>
primitiveToWrapper
(Class<N> type) Changes a primitive class to its wrapper (for exampleint
toInteger
).static <T> T
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.widestClass
(Class<? extends Number> c1, Class<? extends Number> c2) Returns the widest of the given types.widestClass
(Number n1, Number n2) Returns the widest type of two numbers.static <N extends Number>
NWraps the given floatingpoint value in aNumber
of the specified class.static <N extends Number>
NWraps the given integer value in aNumber
of the specified class.static <N> Class<N>
wrapperToPrimitive
(Class<N> type) Changes a wrapper class to its primitive (for exampleInteger
toint
).

Field Details

BIG_DECIMAL
public static final byte BIG_DECIMALConstant of value 0xb 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:

BIG_INTEGER
public static final byte BIG_INTEGERConstant of value 0xa 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:

FRACTION
public static final byte FRACTIONConstant of value 0x7 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:

DOUBLE
public static final byte DOUBLEConstant of value 0x9 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:

FLOAT
public static final byte FLOATConstant of value 0x8 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:

LONG
public static final byte LONGConstant of value 0x6 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:

INTEGER
public static final byte INTEGERConstant of value 0x5 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:

SHORT
public static final byte SHORTConstant of value 0x4 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:

BYTE
public static final byte BYTEConstant of value 0x3 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:

CHARACTER
public static final byte CHARACTERConstant of value 0x2 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:

BOOLEAN
public static final byte BOOLEANConstant of value 0x1 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:

OTHER
public static final byte OTHERConstant of value 0x0 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:


Method Details

isFloat
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
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:

isNumber
Returnstrue
if the giventype
is a floating point or an integer type. This method returnstrue
if eitherisFloat(Class)
orisInteger(Class)
returnstrue
for the given argument. Parameters:
type
 the primitive type or wrapper class to test (can benull
). Returns:
true
iftype
is a floating point or an integer type. Since:
 1.1
 See Also:

isNaN
Returnstrue
if the given number is null or NaN. Current implementation recognizesFloat
andDouble
types. Parameters:
value
 the number to test (may benull
). Returns:
true
if the given number is null or NaN. Since:
 1.1
 See Also:

primitiveBitCount
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
Changes a primitive class to its wrapper (for exampleint
toInteger
). If the specified class is not a primitive type, then it is returned unchanged. Type Parameters:
N
 the primitive and wrapper type (both have the same parametric declaration). Parameters:
type
 the primitive type (can benull
). Returns:
 the type as a wrapper.
 See Also:

wrapperToPrimitive
Changes a wrapper class to its primitive (for exampleInteger
toint
). If the specified class is not a wrapper type, then it is returned unchanged. Type Parameters:
N
 the primitive and wrapper type (both have the same parametric declaration). Parameters:
type
 the wrapper type (can benull
). Returns:
 the type as a primitive.
 See Also:

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
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:

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
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
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 0x80 and
0x7f, 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:
 If the given value is

narrowestNumber
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:

narrowestNumber
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:

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 number can not be converted to the specified type (e.g.Double.NaN
can not be converted toBigDecimal
).
 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
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
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:
 If the given type is a floating point primitive type (

getEnumConstant
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.
