# Enum Class NumberType

Object
Enum<NumberType>
NumberType

All Implemented Interfaces:
  `Serializable, Comparable<NumberType>, 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:

- The ordinal value of the `VOID` value is 0.
- Primitive types are enumerated in this exact order, but not necessarily as consecutive values: `BYTE`, `SHORT`, `INTEGER`, `LONG`, `FLOAT`, `DOUBLE`.
- `BIG_INTEGER` and `BIG_DECIMAL` are ordered after primitive types.

Since:
  1.6
See Also:
  - `Numbers`
  - `DataType`

- ## Nested Class Summary

  ### Nested classes/interfaces inherited from class Enum

  `Enum​.EnumDesc<E>`

- ## Enum Constant Summary

  Enum Constants
  Enum Constant
  Description
  `BIG_DECIMAL`
  The `BigDecimal` class.
  `BIG_INTEGER`
  The `BigInteger` class.
  `BOOLEAN`
  The `boolean` primitive type or its wrapper class.
  `BYTE`
  The `byte` primitive type or its wrapper class.
  `CHARACTER`
  The `char` primitive type or its wrapper class.
  `DOUBLE`
  The `double` primitive type or its wrapper class.
  `FLOAT`
  The `float` primitive type or its wrapper class.
  `FRACTION`
  The `Fraction` class.
  `INTEGER`
  The `int` primitive type or its wrapper class.
  `LONG`
  The `long` primitive type or its wrapper class.
  `NULL`
  The null type, used when a `Class` argument is `null`.
  `NUMBER`
  Any `Number` class not recognized by Apache SIS.
  `SHORT`
  The `short` primitive type or its wrapper class.
  `VOID`
  The void type, viewed as if it was a numeric type with a size of 0 bit.

- ## Method Summary

  Modifier and Type
  Method
  Description
  `Number`
  `cast(Number number)`
  Casts a value to the specified type without checking whether is would cause precision lost.
  `final Class<?>`
  `classOfValues(boolean primitive)`
  Returns the primitive or wrapper class represented by this enumeration value.
  `static Optional<NumberType>`
  `forClass(Class<?> type)`
  Returns the enumeration value for the given class.
  `static Optional<NumberType>`
  `forClasses(Class<?>... types)`
  Returns an enumeration value capable to represent at least approximately all the given classes.
  `static NumberType`
  `forNumberClass(Class<?> type)`
  Returns the enumeration value for the given numeric class.
  `static NumberType`
  `forNumberClasses(Class<?>... types)`
  Returns an enumeration value capable to represent at least approximately all the given numeric classes.
  `boolean`
  `isConversionLossless(NumberType target)`
  Returns whether conversion of values from this type to the specified type would be lossless.
  `final boolean`
  `isConvertible()`
  Returns whether this type supports the `cast(…)` and `wrap(…)` methods.
  `final boolean`
  `isFractional()`
  Returns `true` if this type is capable to store fractional digits.
  `static boolean`
  `isFractional(Class<?> type)`
  Returns `true` if the argument is one of the types known to SIS as capable to store fractional digits.
  `final boolean`
  `isInteger()`
  Returns `true` if this type is an integer type.
  `static boolean`
  `isInteger(Class<?> type)`
  Returns `true` if the argument is one of the integer types known to SIS.
  `boolean`
  `isNarrowerThan(NumberType other)`
  Returns whether this type is considered narrower than the specified type.
  `final boolean`
  `isReal()`
  Returns `true` if this type is any type of real numbers.
  `static boolean`
  `isReal(Class<?> type)`
  Returns `true` if the argument is one of the real number types known to SIS.
  `boolean`
  `isWiderThan(NumberType other)`
  Returns whether this type is considered wider than the specified type.
  `Comparable<?>`
  `nilValue()`
  Returns the closest value that can be interpreted as no data, which is not the same as zero.
  `Comparable<?>`
  `parse(String text)`
  Converts the specified string into a value object.
  `static <N> Class<N>`
  `primitiveToWrapper(Class<N> type)`
  Changes a primitive class to its wrapper (for example `int` to `Integer`).
  `final OptionalInt`
  `size()`
  Returns the number of bits used in the representation of this type.
  `static NumberType`
  `valueOf(String name)`
  Returns the enum constant of this class with the specified name.
  `static NumberType[]`
  `values()`
  Returns an array containing the constants of this enum class, in the order they are declared.
  `Number`
  `wrapExact(double number)`
  Wraps the given floating-point value in an object of the type represented by this enumeration value.
  `Number`
  `wrapExact(long number)`
  Wraps the given integer value in an object of the type represented by this enumeration value.
  `static <N> Class<N>`
  `wrapperToPrimitive(Class<N> type)`
  Changes a wrapper class to its primitive (for example `Integer` to `int`).

  ### Methods inherited from class Enum

  `clone, compareTo, describeConstable, equals, finalize, getDeclaringClass, hashCode, name, ordinal, toString, valueOf`

  ### Methods inherited from class Object

  `getClass, notify, notifyAll, wait, wait, wait`

- ## 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 `BigInteger` class.

  - ### BIG_DECIMAL

    public static final NumberType BIG_DECIMAL
    The `BigDecimal` 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 `classOfValues(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:
      `IllegalArgumentException` - if this enum class has no constant with the specified name
      `NullPointerException` - 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 `forClass(type)​.orElseThrow()` except that the exception is an `IllegalArgumentException`. 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:
      `IllegalArgumentException` - 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

        forClass

    (types)​.orElseThrow()` except that the exception is an `IllegalArgumentException`. 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:
      `IllegalArgumentException` - 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 `BigInteger`.

    This method is mutually exclusive with `isFractional()`: 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 `isInteger()`: 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 `BigDecimal`.
    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:
      - `Class​.isPrimitive()`

  - ### 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(Class)`
      - `Class​.isPrimitive()`

  - ### 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:
      - `primitiveToWrapper(Class)`
      - `Class​.isPrimitive()`

  - ### 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​.valueOf(number​.doubleValue())`;
    - Otherwise if this type is `FLOAT`, then this method returns `Float​.valueOf(number​.floatValue())`;
    - 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​.fooValue()` 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:
      `UnsupportedOperationException` - if this type cannot cast numbers.
      `NullPointerException` - if `number` is null.
      `IllegalArgumentException` - if the number cannot be converted to this type (e.g., `Double​.NaN` cannot be converted to `BigDecimal`).
    See Also:
      - `Numbers​.cast(Number, Class)`

  - ### 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 ``classOfValues`(false)`. The given value shall be convertible to that type without precision lost, otherwise an `ArithmeticException` 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​.NaN`).

    Parameters:
      `number` - the number to wrap.
    Returns:
      the value wrapped in an object of the wrapper class represented by this enumeration value.
    Throws:
      `UnsupportedOperationException` - if this type cannot wrap numbers.
      `ArithmeticException` - if the given value cannot be converted without precision lost.
    See Also:
      - `Numbers​.wrap(double, Class)`

  - ### 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 ``classOfValues`(false)`. The given value shall be convertible to that type without precision lost, otherwise an `ArithmeticException` 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:
      `UnsupportedOperationException` - if this type cannot wrap numbers.
      `ArithmeticException` - if the given value cannot be converted without precision lost.
    See Also:
      - `Numbers​.wrap(long, Class)`

  - ### 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 ``classOfValues`(false)`.
    - If this type is `DOUBLE`, then this method returns `Double​.valueOf(value)`;
    - If this type is `FLOAT`, then this method returns `Float​.valueOf(value)`;
    - And likewise for all other known types.
    Parameters:
      `text` - the value to parse.
    Returns:
      the value object.
    Throws:
      `UnsupportedOperationException` - if this type does not support parsing.
      `NullPointerException` - if `text` is null.
      `IllegalArgumentException` - if `text` is not parsable as a value of this type.
    See Also:
      - `Numbers​.valueOf(String, Class)`

  - ### 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 `NaN`, `0` or `false` or `null`, in this preference order. The returned value is an instance of the wrapper class returned by ``classOfValues`(false)`.
    Returns:
      the `NaN`, `0` or `false` or `null` value, in this preference order.
    See Also:
      - `Numbers​.valueOfNil(Class)`