Class Numbers

java.lang.Object
org.apache.sis.util.Static
org.apache.sis.util.Numbers

public final class Numbers extends Static
Static methods working with Number objects, and a few primitive types by extension.
Since:
0.3
Version:
1.3
See Also:
  • Field Summary

    Fields
    Modifier and Type
    Field
    Description
    static final byte
    Constant of value 0xb used in switch statements or as index in arrays.
    static final byte
    Constant of value 0xa used in switch statements or as index in arrays.
    static final byte
    Constant of value 0x1 used in switch statements or as index in arrays.
    static final byte
    Constant of value 0x3 used in switch statements or as index in arrays.
    static final byte
    Constant of value 0x2 used in switch statements or as index in arrays.
    static final byte
    Constant of value 0x9 used in switch statements or as index in arrays.
    static final byte
    Constant of value 0x8 used in switch statements or as index in arrays.
    static final byte
    Constant of value 0x7 used in switch statements or as index in arrays.
    static final byte
    Constant of value 0x5 used in switch statements or as index in arrays.
    private final char
    The internal form of the primitive name.
    private final boolean
    true for floating point number.
    private final boolean
    true for integer number.
    static final byte
    Constant of value 0x6 used in switch statements or as index in arrays.
    private static final Map<Class<?>,Numbers>
    Mapping between a primitive type and its wrapper, if any.
    private final Object
    The null, NaN, 0 or false value.
    private final byte
    Constant to be used in switch statement.
    static final byte
    Constant of value 0x0 used in switch statements or as index in arrays.
    private final Class<?>
    The primitive type.
    static final byte
    Constant of value 0x4 used in switch statements or as index in arrays.
    private final byte
    The size in bits, or -1 if variable.
    private final Class<?>
    The wrapper for the primitive type.
  • Constructor Summary

    Constructors
    Modifier
    Constructor
    Description
    private
    Numbers(Class<?> type, boolean isFloat, boolean isInteger, byte ordinal)
    Creates an entry for a type which is not a primitive type.
    private
    Numbers(Class<?> primitive, Class<?> wrapper, boolean isFloat, boolean isInteger, byte size, byte ordinal, char internal, Object nullValue)
    Creates a mapping between a primitive type and its wrapper.
  • 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
    Returns a numeric constant for the given type.
    (package private) static char
    getInternal(Class<?> type)
    Returns the Java letter used for the internal representation of this given primitive type.
    static boolean
    isFloat(Class<?> type)
    Returns true if the given type is a floating point type.
    static boolean
    isInteger(Class<?> type)
    Returns true if the given type is an integer type.
    static boolean
    isNaN(Number value)
    Returns true if the given number is null or NaN.
    static boolean
    isNumber(Class<?> type)
    Returns true if the given type is a floating point or 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>
    Returns the smallest class capable to hold the specified value.
    static Class<? extends Number>
    Returns the narrowest type of two numbers.
    static Number
    Returns the given number wrapped in the smallest class capable to hold the specified value.
    static Number
    Returns the smallest number capable to hold the specified value.
    static int
    Returns the number of bits used by primitive of the specified type.
    static <N> Class<N>
    Changes a primitive class to its wrapper (for example int to Integer).
    unknownType(Class<?> type)
    Returns an exception for an unknown type.
    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 a NaN, zero, empty or null 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>
    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>
    Changes a wrapper class to its primitive (for example Integer to int).

    Methods inherited from class java.lang.Object

    clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, 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:
    • 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:
    • 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:
    • 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:
    • 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:
    • 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:
    • 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:
    • 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:
    • 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:
    • 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:
    • 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:
    • 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:
    • MAPPING

      private static final Map<Class<?>,Numbers> MAPPING
      Mapping between a primitive type and its wrapper, if any.
      Implementation note: In the particular case of Class keys, IdentityHashMap and HashMap have identical behavior since Class is final and does not override the equals(Object) and hashCode() methods. The IdentityHashMap Javadoc claims that it is faster than the regular HashMap. But maybe the most interesting property is that it allocates less objects since IdentityHashMap implementation does not need the chain of objects created by HashMap.
    • primitive

      private final Class<?> primitive
      The primitive type.
    • wrapper

      private final Class<?> wrapper
      The wrapper for the primitive type.
    • isFloat

      private final boolean isFloat
      true for floating point number.
    • isInteger

      private final boolean isInteger
      true for integer number.
    • size

      private final byte size
      The size in bits, or -1 if variable.
    • ordinal

      private final byte ordinal
      Constant to be used in switch statement.
    • internal

      private final char internal
      The internal form of the primitive name.
    • nullValue

      private final Object nullValue
      The null, NaN, 0 or false value.
  • Constructor Details

    • Numbers

      private Numbers(Class<?> type, boolean isFloat, boolean isInteger, byte ordinal)
      Creates an entry for a type which is not a primitive type.
    • Numbers

      private Numbers(Class<?> primitive, Class<?> wrapper, boolean isFloat, boolean isInteger, byte size, byte ordinal, char internal, Object nullValue)
      Creates a mapping between a primitive type and its wrapper.
  • Method Details

    • getInternal

      static char getInternal(Class<?> type)
      Returns the Java letter used for the internal representation of this given primitive type.
    • 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 BigDecimal. 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:
    • 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 BigInteger.
      Parameters:
      type - the primitive type or wrapper class to test (can be null).
      Returns:
      true if type is an integer type.
      See Also:
    • 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 isFloat(Class) or isInteger(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:
    • isNaN

      public static boolean isNaN(Number value)
      Returns true if the given number is null or NaN. Current implementation recognizes Float and Double 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:
    • 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:
      IllegalArgumentException - 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:
    • 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:
    • 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, BigInteger or BigDecimal 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:
      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. Classes c1 and c2 can be Byte, Short, Integer, Long, Float, Double, Fraction, BigInteger or BigDecimal 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:
      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:
      IllegalArgumentException - if one of the given types is not supported by this Numbers class.
      See Also:
    • 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, BigInteger or BigDecimal 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:
      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. Classes c1 and c2 can be Byte, Short, Integer, Long, Float, Double, Fraction, BigInteger or BigDecimal 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:
      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:
      IllegalArgumentException - if one of the given types is not supported by this Numbers class.
      See Also:
    • 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:
    • 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:
      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

      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:
      NumberFormatException - if the given value cannot 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 of Byte, Short, Integer, Long, Float, Double, Fraction, BigInteger or BigDecimal. 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.valueOf(number.doubleValue());
      • Otherwise if the given type is Float.class, then this method returns Float.valueOf(number.floatValue());
      • 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 widestClass(Class, Class) or narrowestClass(Number). If nevertheless the given type is not wide enough, then the behavior depends on the implementation of the corresponding Number.fooValue() 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:
      IllegalArgumentException - if the given type is not supported by this Numbers class, or the number cannot be converted to the specified type (e.g. Double.NaN cannot be converted to BigDecimal).
    • 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, BigInteger and BigDecimal classes. Furthermore, the given value shall be convertible to the given class without precision lost, otherwise an IllegalArgumentException 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 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, BigInteger and BigDecimal classes. Furthermore, the given value shall be convertible to the given class without precision lost, otherwise an IllegalArgumentException 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 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 BigDecimal, BigInteger, 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.valueOf(value);
      • If the given type is Float.class, then this method returns Float.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 if value was null.
      Throws:
      IllegalArgumentException - if type is not a recognized type.
      NumberFormatException - 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 NaN, 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.NaN or Double.NaN 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:
    • 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.
    • unknownType

      private static IllegalArgumentException unknownType(Class<?> type)
      Returns an exception for an unknown type.