Module org.apache.sis.util

Package org.apache.sis.util

Class Numbers

Object

Static

Numbers

public final class Numbers
extends Static

Static methods working with Number objects, and a few primitive types by extension.

Since:

0.3

See Also:

• Math­Functions

Field Summary

Fields

Modifier and Type	Field	Description
static final byte	BIG_DECIMAL	Constant of value 0xb used in switch statements or as index in arrays.
static final byte	BIG_INTEGER	Constant of value 0xa used in switch statements or as index in arrays.
static final byte	BOOLEAN	Constant of value 0x1 used in switch statements or as index in arrays.
static final byte	BYTE	Constant of value 0x3 used in switch statements or as index in arrays.
static final byte	CHARACTER	Constant of value 0x2 used in switch statements or as index in arrays.
static final byte	DOUBLE	Constant of value 0x9 used in switch statements or as index in arrays.
static final byte	FLOAT	Constant of value 0x8 used in switch statements or as index in arrays.
static final byte	FRACTION	Constant of value 0x7 used in switch statements or as index in arrays.
static final byte	INTEGER	Constant of value 0x5 used in switch statements or as index in arrays.
static final byte	LONG	Constant of value 0x6 used in switch statements or as index in arrays.
static final byte	OTHER	Constant of value 0x0 used in switch statements or as index in arrays.
static final byte	SHORT	Constant of value 0x4 used in switch statements or as index in arrays.

Method Summary

Modifier and Type	Method	Description
static <N extends Number> N	cast(Number number, Class<N> type)	Casts a number to the specified type.
static byte	get­Enum­Constant(Class<?> type)	Returns a numeric constant for the given type.
static boolean	is­Float(Class<?> type)	Returns true if the given type is a floating point type.
static boolean	is­Integer(Class<?> type)	Returns true if the given type is an integer type.
static boolean	is­Na­N(Number value)	Returns true if the given number is null or NaN.
static boolean	is­Number(Class<?> type)	Returns true if the given type is a floating point or an integer type.
static Class<? extends Number>	narrowest­Class(Class<? extends Number> c1, Class<? extends Number> c2)	Returns the narrowest of the given types.
static Class<? extends Number>	narrowest­Class(Number value)	Returns the smallest class capable to hold the specified value.
static Class<? extends Number>	narrowest­Class(Number n1, Number n2)	Returns the narrowest type of two numbers.
static Number	narrowest­Number(Number value)	Returns the given number wrapped in the smallest class capable to hold the specified value.
static Number	narrowest­Number(String value)	Returns the smallest number capable to hold the specified value.
static int	primitive­Bit­Count(Class<?> type)	Returns the number of bits used by primitive of the specified type.
static <N> Class<N>	primitive­To­Wrapper(Class<N> type)	Changes a primitive class to its wrapper (for example int to Integer).
static long	round(Number value)	Returns the value of the given number rounded to nearest long integer.
static <T> T	value­Of(String value, Class<T> type)	Converts the specified string into a value object.
static <T> T	value­Of­Nil(Class<T> type)	Returns a Na­N, zero, empty or null value of the given type.
static Class<? extends Number>	widest­Class(Class<? extends Number> c1, Class<? extends Number> c2)	Returns the widest of the given types.
static Class<? extends Number>	widest­Class(Number n1, Number n2)	Returns the widest type of two numbers.
static <N extends Number> N	wrap(double value, Class<N> type)	Wraps the given floating-point value in a Number of the specified class.
static <N extends Number> N	wrap(long value, Class<N> type)	Wraps the given integer value in a Number of the specified class.
static <N> Class<N>	wrapper­To­Primitive(Class<N> type)	Changes a wrapper class to its primitive (for example Integer to int).

Methods inherited from class Object

clone, equals, finalize, get­Class, hash­Code, notify, notify­All, to­String, wait, wait, wait

Field Details

BIG_DECIMAL

public static final byte BIG_DECIMAL

Constant of value 0xb used in switch 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 and BIG_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 0xa used in switch 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 and BIG_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 0x7 used in switch 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 and BIG_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 0x9 used in switch 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 and BIG_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 0x8 used in switch 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 and BIG_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 0x6 used in switch 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 and BIG_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 0x5 used in switch 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 and BIG_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 0x4 used in switch 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 and BIG_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 0x3 used in switch 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 and BIG_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 0x2 used in switch 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 and BIG_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 0x1 used in switch 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 and BIG_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 0x0 used in switch 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 and BIG_INTEGER) have higher enumeration values.
• Fraction is considered as a kind of floating point value.

See Also:

• Constant Field Values

Method Details

isFloat

public static boolean isFloat(Class<?> type)

Returns true if the given type is a floating point type. The floating point types are Float, float, Double, double and Big­Decimal. Fraction is also considered as a kind of floating point values.

Parameters:

type - the primitive type or wrapper class to test (can be null).

Returns:

true if type is one of the known types capable to represent floating point numbers.

See Also:

• is­Integer(Class)

isInteger

public static boolean isInteger(Class<?> type)

Returns true if the given type is an integer type. The integer types are Byte, byte, Short, short, Integer, int, Long, long and Big­Integer.

Parameters:

type - the primitive type or wrapper class to test (can be null).

Returns:

true if type is an integer type.

See Also:

• is­Float(Class)
• round(Number)

isNumber

public static boolean isNumber(Class<?> type)

Returns true if the given type is a floating point or an integer type. This method returns true if either is­Float(Class) or is­Integer(Class) returns true for the given argument, or if the type is assignable to Number.

Parameters:

type - the primitive type or wrapper class to test (can be null).

Returns:

true if type is a Number or a primitive floating point or integer type.

Since:

1.1

See Also:

• is­Float(Class)
• is­Integer(Class)

isNaN

public static boolean isNaN(Number value)

Returns true if the given number is null or NaN. Current implementation recognizes Float, Double and Fraction types.

Parameters:

value - the number to test (may be null).

Returns:

true if the given number is null or NaN.

Since:

1.1

See Also:

• Float.is­Na­N()
• Double.is­Na­N()
• Fraction.is­Na­N()

round

public static long round(Number value)

Returns the value of the given number rounded to nearest long integer. This method is intended for calculations where fractional parts are rounding errors. An Arithmetic­Exception is thrown in the following cases:

• If the floating point value is NaN or positive or negative infinity.
• If the value overflows the capacity of 64 bits integers.
• If the number is a Big­Decimal with a non-zero fractional part.

The justification for the last case is that Big­Decimal is used when calculations should be exact in base 10. In such case, a fractional part would not be a rounding error.

Parameters:

value - the value to return as a long integer.

Returns:

the value rounded to nearest long integer.

Throws:

Null­Pointer­Exception - if the given number is null.

Arithmetic­Exception - if the value cannot be represented as a long integer.

Since:

1.4

See Also:

• Math.round(double)
• Big­Decimal.long­Value­Exact()
• Big­Integer.long­Value­Exact()

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 be null).

Returns:

the number of bits, or 0 if type is null.

Throws:

Illegal­Argument­Exception - if the given type is not one of the types supported by this Numbers class.

primitiveToWrapper

public static <N> Class<N> primitiveToWrapper(Class<N> type)

Changes a primitive class to its wrapper (for example int to Integer). 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 be null).

Returns:

the type as a wrapper.

See Also:

• wrapper­To­Primitive(Class)

wrapperToPrimitive

public static <N> Class<N> wrapperToPrimitive(Class<N> type)

Changes a wrapper class to its primitive (for example Integer to int). 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 be null).

Returns:

the type as a primitive.

See Also:

• primitive­To­Wrapper(Class)

widestClass

public static Class<? extends Number> widestClass(Number n1,
 Number n2)
                                           throws IllegalArgumentException

Returns the widest type of two numbers. Numbers n1 and n2 can be instance of Byte, Short, Integer, Long, Float, Double, Fraction, Big­Integer or Big­Decimal types.

If one of the given argument is null, then this method returns the class of the non-null argument. If both arguments are null, then this method returns null.

Parameters:

n1 - the first number, or null.

n2 - the second number, or null.

Returns:

the widest type of the given numbers, or null if both n1 and n2 are null.

Throws:

Illegal­Argument­Exception - if a number is not an instance of a supported type.

See Also:

• widest­Class(Number, Number)
• narrowest­Class(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. Classes c1 and c2 can be Byte, Short, Integer, Long, Float, Double, Fraction, Big­Integer or Big­Decimal types.

If one of the given argument is null, then this method returns the non-null argument. If both arguments are null, then this method returns null.

Example

in the following code, type is set to Long.class:

Class<?> type = widestClass(Short.class, Long.class);

Parameters:

c1 - the first number type, or null.

c2 - the second number type, or null.

Returns:

the widest of the given types, or null if both c1 and c2 are null.

Throws:

Illegal­Argument­Exception - if one of the given types is not supported by this Numbers class.

See Also:

• widest­Class(Class, Class)
• narrowest­Class(Number, Number)

narrowestClass

public static Class<? extends Number> narrowestClass(Number n1,
 Number n2)
                                              throws IllegalArgumentException

Returns the narrowest type of two numbers. Numbers n1 and n2 can be instance of Byte, Short, Integer, Long, Float, Double, Fraction, Big­Integer or Big­Decimal types.

Parameters:

n1 - the first number, or null.

n2 - the second number, or null.

Returns:

the narrowest type of the given numbers, or null if both n1 and n2 are null.

Throws:

Illegal­Argument­Exception - if a number is not an instance of a supported type.

See Also:

• narrowest­Class(Class, Class)
• widest­Class(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. Classes c1 and c2 can be Byte, Short, Integer, Long, Float, Double, Fraction, Big­Integer or Big­Decimal types.

If one of the given argument is null, then this method returns the non-null argument. If both arguments are null, then this method returns null.

Example

in the following code, type is set to Short.class:

Class<?> type = widestClass(Short.class, Long.class);

Parameters:

c1 - the first number type, or null.

c2 - the second number type, or null.

Returns:

the narrowest of the given types, or null if both c1 and c2 are null.

Throws:

Illegal­Argument­Exception - if one of the given types is not supported by this Numbers class.

See Also:

• narrowest­Class(Number, Number)
• widest­Class(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 returns null.
• Otherwise if the given value cannot be casted from double to another type without precision lost, return Double.class.
• Otherwise if the given value cannot be casted from float to another type without precision lost, return Float.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:

• narrowest­Number(Number)

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:

• narrowest­Class(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 a Number.

Returns:

the narrowest type capable to hold the given value.

Throws:

Number­Format­Exception - if the given value cannot be parsed as a number.

See Also:

• narrowest­Number(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 of Byte, Short, Integer, Long, Float, Double, Fraction, Big­Integer or Big­Decimal. 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 returns Double.value­Of(number.double­Value());
• Otherwise if the given type is Float.class, then this method returns Float.value­Of(number.float­Value());
• And likewise for all remaining known types.

This method does not verify if the given type is wide enough for the given value, because the type has typically been calculated by widest­Class(Class, Class) or narrowest­Class(Number). If nevertheless the given type is not wide enough, then the behavior depends on the implementation of the corresponding Number.foo­Value() method - typically, the value is just rounded or truncated.

Type Parameters:

N - the class to cast to.

Parameters:

number - the number to cast, or null.

type - the destination type.

Returns:

the number casted to the given type, or null if the given value was null.

Throws:

Illegal­Argument­Exception - if the given type is not supported by this Numbers class, or the number cannot be converted to the specified type (e.g. Double.Na­N cannot be converted to Big­Decimal).

wrap

public static <N extends Number> N wrap(double value,
 Class<N> type)
                                 throws IllegalArgumentException

Wraps the given floating-point value in a Number of the specified class. The given type shall be one of Byte, Short, Integer, Long, Float, Double, Fraction, Big­Integer and Big­Decimal classes. Furthermore, the given value shall be convertible to the given class without precision lost, otherwise an Illegal­Argument­Exception 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:

Illegal­Argument­Exception - if the given type is not supported by this Numbers class, or if the given value cannot 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 a Number of the specified class. The given type shall be one of Byte, Short, Integer, Long, Float, Double, Fraction, Big­Integer and Big­Decimal classes. Furthermore, the given value shall be convertible to the given class without precision lost, otherwise an Illegal­Argument­Exception 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:

Illegal­Argument­Exception - if the given type is not supported by this Numbers class, or if the given value cannot 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 of Big­Decimal, Big­Integer, Fraction, Double, Float, Long, Integer, Short, Byte, Boolean, Character or String according the specified type. This method makes the following choice:

• If the given type is Double.class, then this method returns Double.value­Of(value);
• If the given type is Float.class, then this method returns Float.value­Of(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 if value was null.

Throws:

Illegal­Argument­Exception - if type is not a recognized type.

Number­Format­Exception - if type is a subclass of Number and the string value is not parsable as a number of the specified type.

valueOfNil

public static <T> T valueOfNil(Class<T> type)

Returns a Na­N, zero, empty or null 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 or double), then this method returns Float.Na­N or Double.Na­N depending on the given type.
• If the given type is an integer primitive type or the character type (long, int, short, byte or char), then this method returns the zero value of the given type.
• If the given type is the boolean primitive type, then this method returns Boolean.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.

Despite being defined in the 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 compile-time 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:

• Nil­Object

getEnumConstant

public static byte getEnumConstant(Class<?> type)

Returns a numeric constant for the given type. The constants are BIG_DECIMAL, BIG_INTEGER, FRACTION, DOUBLE, FLOAT, LONG, INTEGER, SHORT, BYTE, CHARACTER, BOOLEAN, or OTHER constants for the given type. This is a commodity for usage in switch statements.

Parameters:

type - a type (usually either a primitive type or its wrapper), or null.

Returns:

the constant for the given type, or OTHER if unknown.