ch.jalu.typeresolver.numbers

Interface NumberType<N>

Type Parameters:

N - the number type of this instance

All Known Implementing Classes:

StandardNumberType

public interface NumberType<N>

Utility for a type that represents numerical values, e.g. to convert a number to another type or to query some data about the values the type can represent.

Standard implementations for basic Java number types are available at StandardNumberType and MoreNumberTypes.

See Also:

StandardNumberType, NumberTypes.from(Class)

Method Summary

Modifier and Type	Method and Description
ValueRangeComparison	compareToValueRange(Number number) Compares the given value to this type's value range, indicating whether it can be represented by this type without loss of magnitude, or why it cannot.
default Optional<N>	convertIfNoLossOfMagnitude(Number number) Converts the number to this type only if no loss of magnitude and meaning occurs, otherwise returns an empty optional.
N	convertToBounds(Number numberToConvert) Returns a value of this type that is the closest to the given number.
N	convertUnsafe(Number number) Converts the given number to this type without considering underflow or overflow.
Class<N>	getType()
ValueRange<N>	getValueRange() Returns information about the value range this type can represent.
default boolean	supportsAllValuesOf(NumberType<?> other) Convenience method for ValueRange.supportsAllValuesOf(ch.jalu.typeresolver.numbers.ValueRange<?>).

Method Detail

getType

Class<N> getType()

Returns:

the type this instance describes and can convert to

convertToBounds

N convertToBounds(Number numberToConvert)

Returns a value of this type that is the closest to the given number. The implementations of this library can convert every instantiable Number class of the JDK (e.g. Integer, AtomicLong, BigDecimal, LongAdder). An IllegalArgumentException is thrown if the number type is unknown.
If the given number exceeds the value range of this type, the minimum or maximum value is returned. Other special cases:

• Float and Double NaN is converted to 0 if the type does not support the NaN value.
• Negative infinity is converted to the type's minimum value if it does not support infinity; positive infinity converts to the maximum value in such cases.
• When converting to BigDecimal or BigInteger, 0 is used for infinity because no minimum or maximum value exists for these types.

Examples from StandardNumberType:

   T_INTEGER.convertToBounds(new BigDecimal("1234.6")); // returns `1234`
   T_DOUBLE.convertToBounds(new AtomicLong(-800)); // returns `-800.0`
   T_BYTE.convertToBounds(200); // returns `(byte) 127`, the max value of Byte
   T_SHORT.convertToBounds(Double.NEGATIVE_INFINITY); // returns `(short) -32768`, the min value of Short
   T_BIG_DECIMAL.convertToBounds(Double.NEGATIVE_INFINITY); // returns `0`
   T_LONG.convertToBounds(Double.NEGATIVE_INFINITY); // returns `Long.MIN_VALUE`
 

To catch NaN and infinity before this method, it is possible to use ValueRangeComparison.getErrorForNonFiniteValue(Number).

Other conversion methods on this interface are convertIfNoLossOfMagnitude(java.lang.Number) and convertUnsafe(java.lang.Number).

Parameters:

numberToConvert - the number to convert (not null)

Returns:

value of this type that is closest to the given number, never null

convertIfNoLossOfMagnitude

default Optional<N> convertIfNoLossOfMagnitude(Number number)

Converts the number to this type only if no loss of magnitude and meaning occurs, otherwise returns an empty optional. For example, BYTE.convertIfNoLossOfMagnitude(200) returns an empty Optional (as 200 exceeds the max value of the Byte type, 127), while BYTE.convertIfNoLossOfMagnitude(12) would return an Optional with (byte) 12 as value.

Examples:

   T_SHORT.convertIfNoLossOfMagnitude(40); // Optional.of((short) 40)
   T_SHORT.convertIfNoLossOfMagnitude(100_000L); // Optional.empty()
   T_FLOAT.convertIfNoLossOfMagnitude(Double.NaN); // Optional.of(Float.NaN)
   T_LONG.convertIfNoLossOfMagnitude(Double.NaN); // Optional.empty()
 

Implementations by this library support all instantiable Number classes of the JDK as input. An IllegalArgumentException is thrown for other types.

Parameters:

number - the number to potentially convert (not null)

Returns:

optional with the value converted to this type, or empty if it cannot be represented in this type

convertUnsafe

N convertUnsafe(Number number)

Converts the given number to this type without considering underflow or overflow. Among primitive types, this method behaves like casting one type to another. For example, byte b = (byte) 200 assigns a value of -56 to b due to overflow. Similarly, BYTE.convertUnsafe(200) returns -56.

This method never returns null. When this type is a BigDecimal or BigInteger, NaN and infinity values from Float and Double are converted to 0. For instance, BIG_DECIMAL.convertUnsafe(Double.POSITIVE_INFINITY) returns BigDecimal.ZERO. For other types, the conversion follows the default behavior of Java: e.g., BYTE.convertUnsafe(Double.NaN) = (byte) Double.NaN = (byte) 0.

Use convertToBounds(java.lang.Number) to convert values that are beyond this type's range to the nearest possible value, or convertIfNoLossOfMagnitude(java.lang.Number) to only convert the number if it can be represented by the type.

Some implementations by this library throw an IllegalArgumentException if a number is provided that is not of an instantiable Number class of the JDK.

Examples:

   T_BYTE.convertUnsafe(-255); // returns (byte) 1, due to underflow
   T_LONG.convertUnsafe(200); // returns 200L
   T_FLOAT.convertUnsafe(Double.POSITIVE_INFINITY); // returns Float.POSITIVE_INFINITY
   T_INTEGER.convertUnsafe(Double.POSITIVE_INFINITY); // returns Integer.MAX_VALUE
   T_BIG_INTEGER.convertUnsafe(Double.POSITIVE_INFINITY); // returns BigInteger.ZERO
 

Parameters:

number - the number to cast (not null)

Returns:

the number cast to this type, never null

getValueRange

ValueRange<N> getValueRange()

Returns information about the value range this type can represent.

Returns:

this type's range of possible values

compareToValueRange

ValueRangeComparison compareToValueRange(Number number)

Compares the given value to this type's value range, indicating whether it can be represented by this type without loss of magnitude, or why it cannot. Use convertToBounds(java.lang.Number) if you want to convert the number to this type and use the closest possible value.

The comparison result represents the relationship between the given number and the set of possible values for this type, expressed through the ValueRangeComparison enum. Examples:

   ValueRangeComparison result1 = T_INTEGER.compareToValueRange(42L);
   // result1 = ValueRangeComparison.WITHIN_RANGE

   ValueRangeComparison result2 = T_INTEGER.compareToValueRange(Double.POSITIVE_INFINITY);
   // result2 = ValueRangeComparison.UNSUPPORTED_POSITIVE_INFINITY
 

Parameters:

number - the number to process

Returns:

the comparison result indicating the relationship between the number and this type's value range

supportsAllValuesOf

default boolean supportsAllValuesOf(NumberType<?> other)

Convenience method for ValueRange.supportsAllValuesOf(ch.jalu.typeresolver.numbers.ValueRange<?>). This method returns true if this type can represent all values of the other type without loss of magnitude or meaning. Support for decimals are not considered. See ValueRange.supportsAllValuesOf(ch.jalu.typeresolver.numbers.ValueRange<?>) for a more detailed description.

If this method returns true, then calling compareToValueRange(java.lang.Number) on this type with any number of the given other type will always return ValueRangeComparison.WITHIN_RANGE. This also means that convertIfNoLossOfMagnitude(java.lang.Number) will always return a non-empty Optional.

Parameters:

other - the number type to check

Returns:

true if all values of the given number type can be represented by this type, false otherwise

See Also:

ValueRange.supportsAllValuesOf(ch.jalu.typeresolver.numbers.ValueRange<?>)