Class Numbers

Object

Numbers

public final class Numbers
extends Object

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

Since:

0.3

See Also:

• Math­Functions

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 boolean	is­Na­N(Number value)	Returns true if the given number is null or NaN.
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 long	round(Number value)	Returns the value of the given number rounded to nearest long integer.
static <T> T	value­Of(String text, 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.

Methods inherited from class Object

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

Method Details

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()

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 arguments 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 arguments 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, the result stored in type will be Long.class:

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

Accuracy

Note that conversions to the widest class are not guaranteed to be lossless. For example, double is considered a wider class than long, but conversion from long to double can nevertheless loose accuracy.

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.

If one of the given arguments 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 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 arguments 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, the result stored in type will be Short.class:

Class<?> type = narrowestClass(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 cast from double to another type without precision lost, return Double.class.
• Otherwise if the given value cannot be cast 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(Number, Number) 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 cast 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).

See Also:

• Number­Type.cast(Number)

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.

See Also:

• Number­Type.wrap­Exact(double)

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

See Also:

• Number­Type.wrap­Exact(long)

valueOf

public static <T> T valueOf(String text,
 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:

text - the text 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.

See Also:

• Number­Type.parse(String)

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

• Number­Type.nil­Value()
• Nil­Object