Enum Class NumberType

Object
Enum<NumberType>
NumberType
All Implemented Interfaces:
Serializable, Comparable<Number­Type>, Constable
public enum NumberType extends Enum<NumberType>
Type of numbers recognized by Apache SIS, together with primitive types by extension. This enumeration includes the standard Java numeric types together with subclasses of Number provided by SIS.

Order

Loosely speaking, enumeration values are ordered from narrowest type (with VOID viewed as if it was a numeric type of size 0) to widest type, with types of variable size ordered last. Some ambiguity exist, in particular between FRACTION, LONG and DOUBLE. Nevertheless, this enumeration provides the following guarantees:
Since:
1.6
See Also:

  • Enum Constant Details

    • VOID

      public static final NumberType VOID
      The void type, viewed as if it was a numeric type with a size of 0 bit.

    • BOOLEAN

      public static final NumberType BOOLEAN
      The boolean primitive type or its wrapper class. This is sometime handled as an integer value which accepts only the values 0 and 1. This is considered as a type with a size of 1 bit.

    • BYTE

      public static final NumberType BYTE
      The byte primitive type or its wrapper class.

    • CHARACTER

      public static final NumberType CHARACTER
      The char primitive type or its wrapper class. This is sometime handled as a 16 bits unsigned integer value. This enumeration value is defined for completeness but is rarely used by SIS.

    • SHORT

      public static final NumberType SHORT
      The short primitive type or its wrapper class.

    • INTEGER

      public static final NumberType INTEGER
      The int primitive type or its wrapper class.

    • FRACTION

      public static final NumberType FRACTION
      The Fraction class. This is a ratio of two INTEGER values.

    • LONG

      public static final NumberType LONG
      The long primitive type or its wrapper class.

    • FLOAT

      public static final NumberType FLOAT
      The float primitive type or its wrapper class.

    • DOUBLE

      public static final NumberType DOUBLE
      The double primitive type or its wrapper class.

    • BIG_INTEGER

      public static final NumberType BIG_INTEGER
      The Big­Integer class.

    • BIG_DECIMAL

      public static final NumberType BIG_DECIMAL
      The Big­Decimal class.

    • NUMBER

      public static final NumberType NUMBER
      Any Number class not recognized by Apache SIS.

    • NULL

      public static final NumberType NULL
      The null type, used when a Class argument is null. This is the only enumeration value for which class­Of­Values(boolean) returns null.

  • Method Details

    • values

      public static NumberType[] values()
      Returns an array containing the constants of this enum class, in the order they are declared.
      Returns:
      an array containing the constants of this enum class, in the order they are declared

    • valueOf

      public static NumberType valueOf(String name)
      Returns the enum constant of this class with the specified name. The string must match exactly an identifier used to declare an enum constant in this class. (Extraneous whitespace characters are not permitted.)
      Parameters:
      name - the name of the enum constant to be returned.
      Returns:
      the enum constant with the specified name
      Throws:
      Illegal­Argument­Exception - if this enum class has no constant with the specified name
      Null­Pointer­Exception - if the argument is null

    • forClass

      public static Optional<NumberType> forClass(Class<?> type)
      Returns the enumeration value for the given class. If the type argument is null, returns NULL. If the type is an unrecognized Number class, returns the generic NUMBER value. If the type is an unrecognized non-numerical class, returns an empty value.
      Parameters:
      type - the primitive type or Number class for which to get an enumeration value, or null.
      Returns:
      the enumeration value for the given type. May be NULL if the given value was null.

    • forNumberClass

      public static NumberType forNumberClass(Class<?> type)
      Returns the enumeration value for the given numeric class. This method is equivalent to for­Class(type)​.or­Else­Throw() except that the exception is an Illegal­Argument­Exception. The exception is never thrown if the given class is a primitive type, its wrapper, or a class assignable to Number.
      Parameters:
      type - the primitive type or Number class for which to get an enumeration value, or null.
      Returns:
      the enumeration value for the given type. Never null but may be NULL.
      Throws:
      Illegal­Argument­Exception - if the given class cannot be mapped to any enumeration value.

    • forClasses

      public static Optional<NumberType> forClasses(Class<?>... types)
      Returns an enumeration value capable to represent at least approximately all the given classes. Null elements are ignored. If the given array is null or does not contain at least one non-null element, then NULL is returned. If the array contains at least one element that cannot be mapped to an enumeration value, then an empty value is returned.

      Accuracy

      This method does not guarantee that conversions from the given classes to the returned type will be lossless. For example, conversions form long to double are not lossless. However, the results of those conversions should be reasonable approximations.
      Parameters:
      types - the primitive types or Number classes for which to get a common enumeration value.
      Returns:
      the enumeration value for the given types. May be NULL if all given values were null.

    • forNumberClasses

      public static NumberType forNumberClasses(Class<?>... types)
      Returns an enumeration value capable to represent at least approximately all the given numeric classes. This method is equivalent to
      invalid reference 
      for­Class
      (types)​.or­Else­Throw()       except that the exception is an Illegal­Argument­Exception. The exception is never thrown if all the given classes are primitive types, their wrappers, or classes assignable to Number.
      Parameters:
      types - the primitive types or Number classes for which to get a common enumeration value.
      Returns:
      the enumeration value for the given types. Never null but may be NULL.
      Throws:
      Illegal­Argument­Exception - if one of the given classes cannot be mapped to any enumeration value.

    • isInteger

      public final boolean isInteger()
      Returns true if this type is an integer type. Those types are BYTE, SHORT, INTEGER, LONG and BIG_INTEGER.
      Returns:
      whether this type is an integer type.

    • isInteger

      public static boolean isInteger(Class<?> type)
      Returns true if the argument is one of the integer types known to SIS. Those types are byte, Byte, short, Short, int, Integer, long, Long and Big­Integer.

      This method is mutually exclusive with is­Fractional(): only one of those two methods may return true. However, both methods may return false.

      Parameters:
      type - the primitive type or Number subclass to test (can be null).
      Returns:
      true if type is one of the known types used to represent integers.

    • isFractional

      public final boolean isFractional()
      Returns true if this type is capable to store fractional digits. Those types are FRACTION, FLOAT, DOUBLE and BIG_DECIMAL. Floating point types are considered as types or rational numbers where the denominator is a power of 2 or 10.

      This method is mutually exclusive with is­Integer(): only one of those two methods may return true. However, both methods may return false.

      Returns:
      whether this type is a rational or floating point type.

    • isFractional

      public static boolean isFractional(Class<?> type)
      Returns true if the argument is one of the types known to SIS as capable to store fractional digits. This method returns true for the following types: Fraction, float, Float, double, Double and Big­Decimal.
      Parameters:
      type - the primitive type or Number subclass to test (can be null).
      Returns:
      true if type is one of the known types capable to store fractional digits.

    • isReal

      public final boolean isReal()
      Returns true if this type is any type of real numbers. This method returns true for all integer and fractional types.
      Returns:
      whether this type is any type of real numbers.

    • isConvertible

      public final boolean isConvertible()
      Returns whether this type supports the cast(…) and wrap(…) methods. This is true for all real numbers except NUMBER.
      Returns:
      whether this type supports the cast(…) and wrap(…) methods.

    • isReal

      public static boolean isReal(Class<?> type)
      Returns true if the argument is one of the real number types known to SIS. This method returns true for all integer and fractional types.
      Parameters:
      type - the primitive type or Number subclass to test (can be null).
      Returns:
      true if type is one of the known types used to represent real numbers.

    • isNarrowerThan

      public boolean isNarrowerThan(NumberType other)
      Returns whether this type is considered narrower than the specified type. If one of the type is unknown, then this method conservatively returns false.

      Accuracy

      Note that conversions from the narrowest class are not guaranteed to be lossless. For example, long is considered a narrower class than double, but conversion from long to double can nevertheless loose accuracy. However, if this method returns true, then conversions to other type should produce at least a reasonable approximation of the original value.
      Parameters:
      other - the other type.
      Returns:
      whether this type is considered narrower than the specified type.

    • isWiderThan

      public boolean isWiderThan(NumberType other)
      Returns whether this type is considered wider than the specified type. If one of the type is unknown, then this method conservatively returns false.

      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. However, if this method returns true, then conversions to this type should produce at least a reasonable approximation of the original value.
      Parameters:
      other - the other type.
      Returns:
      whether this type is considered wider than the specified type.

    • isConversionLossless

      public boolean isConversionLossless(NumberType target)
      Returns whether conversion of values from this type to the specified type would be lossless. If this type supports negative zero and NaN values, then the target type must also supports these values for the conversion to be considered lossless.
      Parameters:
      target - the target type.
      Returns:
      whether conversions to the target type would be lossless, including negative zero and NaN.

    • classOfValues

      public final Class<?> classOfValues(boolean primitive)
      Returns the primitive or wrapper class represented by this enumeration value. If there is no primitive type, then this method always returns the class. The returned class is null in the particular case of the NULL type, and non-null for all other types.
      Parameters:
      primitive - true for the primitive type, or false for the wrapper class.
      Returns:
      the primitive or wrapper class represented by this enumeration value, or null.
      See Also:

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

    • size

      public final OptionalInt size()
      Returns the number of bits used in the representation of this type. This size is accurate for values objects such as primitive types. For other objects, the returned size does not include the space occupied by object headers and object references.
      Returns:
      the number of bits, or empty if the size is unknown or variable.

    • cast

      public Number cast(Number number)
      Casts a value to the specified type without checking whether is would cause precision lost. This method makes the following choice:
      • If this type is DOUBLE, then this method returns Double​.value­Of(number​.double­Value());
      • Otherwise if this type is FLOAT, then this method returns Float​.value­Of(number​.float­Value());
      • And likewise for other types in this enumeration.
      This method does not verify if this type is wide enough for the given number, If this 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.
      Parameters:
      number - the number to cast, or null.
      Returns:
      the number cast to this type, or null if the given number was null.
      Throws:
      Unsupported­Operation­Exception - if this type cannot cast numbers.
      Null­Pointer­Exception - if number is null.
      Illegal­Argument­Exception - if the number cannot be converted to this type (e.g., Double​.Na­N cannot be converted to Big­Decimal).
      See Also:

    • wrapExact

      public Number wrapExact(double number)
      Wraps the given floating-point value in an object of the type represented by this enumeration value. The returned value is an instance of the wrapper class returned by class­Of­Values(false). The given value shall be convertible to that type without precision lost, otherwise an Arithmetic­Exception will be thrown.

      This method does not guaranteed that the sign of zero is preserved (i.e., negative zero is considered equivalent to positive zero) and does not guaranteed that the various NaN values are preserved (i.e., NaN may be replaced by the canonical Double​.Na­N).

      Parameters:
      number - the number to wrap.
      Returns:
      the value wrapped in an object of the wrapper class represented by this enumeration value.
      Throws:
      Unsupported­Operation­Exception - if this type cannot wrap numbers.
      Arithmetic­Exception - if the given value cannot be converted without precision lost.
      See Also:

    • wrapExact

      public Number wrapExact(long number)
      Wraps the given integer value in an object of the type represented by this enumeration value. The returned value is an instance of the wrapper class returned by class­Of­Values(false). The given value shall be convertible to that type without precision lost, otherwise an Arithmetic­Exception will be thrown.
      Parameters:
      number - the number to wrap.
      Returns:
      the value wrapped in an object of the wrapper class represented by this enumeration value.
      Throws:
      Unsupported­Operation­Exception - if this type cannot wrap numbers.
      Arithmetic­Exception - if the given value cannot be converted without precision lost.
      See Also:

    • parse

      public Comparable<?> parse(String text)
      Converts the specified string into a value object. The returned value is an instance of the wrapper class returned by class­Of­Values(false).
      Parameters:
      text - the value to parse.
      Returns:
      the value object.
      Throws:
      Unsupported­Operation­Exception - if this type does not support parsing.
      Null­Pointer­Exception - if text is null.
      Illegal­Argument­Exception - if text is not parsable as a value of this type.
      See Also:

    • nilValue

      public Comparable<?> nilValue()
      Returns the closest value that can be interpreted as no data, which is not the same as zero. This method returns Na­N, 0 or false or null, in this preference order. The returned value is an instance of the wrapper class returned by class­Of­Values(false).
      Returns:
      the Na­N, 0 or false or null value, in this preference order.
      See Also: