Package io.github.connellite.util
Class NumberUtils
java.lang.Object
io.github.connellite.util.NumberUtils
-
Nested Class Summary
Nested Classes -
Constructor Summary
Constructors -
Method Summary
Modifier and TypeMethodDescriptionstatic Byte[]bytesToObjectBytes(byte[] bytes) static Character[]charsToObjectCharacters(char[] chars) static Double[]doublesToObjectDoubles(double[] doubles) static booleanequals(double a, double b) Compares twodoublevalues using a default tolerance of1e-9.static booleanequals(double a, double b, double epsilon) Compares twodoublevalues using a tolerance.static booleanequals(float a, float b) Compares twofloatvalues using a default tolerance of1e-6.static booleanequals(float a, float b, float epsilon) Compares twofloatvalues using a tolerance.static Float[]floatsToObjectFloats(float[] floats) static Integer[]intsToObjectIntegers(int[] ints) static booleanEquivalent toisNumeric(str, Locale.ROOT); seeisNumeric(String, Locale)for full rules.static booleanstatic booleanisZero(double a) Returns whether the givendoubleis effectively zero using the defaultdoubletolerance.static booleanisZero(double a, double epsilon) Returns whether the givendoubleis effectively zero using a custom tolerance.static booleanisZero(float a) Returns whether the givenfloatis effectively zero using the defaultfloattolerance.static booleanisZero(float a, float epsilon) Returns whether the givenfloatis effectively zero using a custom tolerance.static Long[]longsToObjectLongs(long[] longs) static NumbernarrowNumber(Number value, Class<?> targetClass) Narrowsvalueto the requested numeric wrapper type without silent truncation.static byte[]objectBytesToBytes(Byte[] bytes) static char[]objectCharactersToChars(Character[] chars) static double[]objectDoublesToDoubles(Double[] doubles) static float[]objectFloatsToFloats(Float[] floats) static int[]objectIntegersToInts(Integer[] ints) static long[]objectLongsToLongs(Long[] longs) static short[]objectShortsToShorts(Short[] shorts) static <T extends Number>
TparseNumber(String text, Class<T> targetClass) Parses the given text into the requested numeric wrapper type.static <T extends Number>
TparseNumber(String text, Class<T> targetClass, T fallback) Parses the given text into the requested numeric wrapper type, or returnsfallbackwhen parsing fails or the target type is not supported.static Short[]shortsToObjectShorts(short[] shorts) static BigDecimaltoBigDecimal(Number value) ConvertsvaluetoBigDecimal.static BigDecimaltoBigDecimal(String value) Converts the given string to aBigDecimal.static BigDecimaltoBigDecimal(String value, BigDecimal fallback) Converts the given string to aBigDecimal, or returnsfallbackwhen parsing fails.static BigIntegertoBigInteger(String value) Converts the given string to aBigInteger.static BigIntegertoBigInteger(String value, BigInteger fallback) Converts the given string to aBigInteger, or returnsfallbackwhen parsing fails.static BigIntegertoBigIntegerExact(Number value) ConvertsvaluetoBigInteger, rejecting fractional parts.static booleantoBoolean(double value) C-style conversion fromdoubleto boolean:0.0dand-0.0darefalse, any other value (includingNaNand infinities) istrue.static booleantoBoolean(float value) C-style conversion fromfloatto boolean:0.0fand-0.0farefalse, any other value (includingNaNand infinities) istrue.static booleantoBoolean(int value) C-style conversion fromintto boolean:0isfalse, any non-zero value istrue.static booleantoBoolean(long value) C-style conversion fromlongto boolean:0isfalse, any non-zero value istrue.static BooleanParses a string into aBoolean.static BooleanParses a string into aBoolean, or returnsfallbackwhen parsing fails.static ByteConverts the given string to aByte.static ByteConverts the given string to aByte, or returnsfallbackwhen parsing fails.static bytetoByteExact(Number value) Convertsvaluetobyte, rejecting fractional parts and out-of-range magnitudes.static DoubleConverts the given string to aDouble.static DoubleConverts the given string to aDouble, or returnsfallbackwhen parsing fails.static FloatConverts the given string to aFloat.static FloatConverts the given string to aFloat, or returnsfallbackwhen parsing fails.static inttoInteger(boolean value) Convertstrueto1andfalseto0(same mapping as a typical Cintcast).static IntegerConverts the given string to anInteger.static IntegerConverts the given string to anInteger, or returnsfallbackwhen parsing fails.static inttoIntExact(Number value) Convertsvaluetoint, rejecting fractional parts and out-of-range magnitudes.static LongConverts the given string to aLong.static LongConverts the given string to aLong, or returnsfallbackwhen parsing fails.static longtoLongExact(Number value) Convertsvaluetolong, rejecting fractional parts and out-of-range magnitudes.static ShortConverts the given string to aShort.static ShortConverts the given string to aShort, or returnsfallbackwhen parsing fails.static shorttoShortExact(Number value) Convertsvaluetoshort, rejecting fractional parts and out-of-range magnitudes.
-
Constructor Details
-
NumberUtils
public NumberUtils()
-
-
Method Details
-
toByte
Converts the given string to aByte.- Parameters:
value- the string to convert- Returns:
- the parsed value, or
nullif the input isnull, blank, or invalid
-
toByte
Converts the given string to aByte, or returnsfallbackwhen parsing fails.- Parameters:
value- the string to convertfallback- value used when the input isnull, blank, or invalid- Returns:
- the parsed value, or
fallback
-
toShort
Converts the given string to aShort.- Parameters:
value- the string to convert- Returns:
- the parsed value, or
nullif the input isnull, blank, or invalid
-
toShort
Converts the given string to aShort, or returnsfallbackwhen parsing fails.- Parameters:
value- the string to convertfallback- value used when the input isnull, blank, or invalid- Returns:
- the parsed value, or
fallback
-
toInteger
Converts the given string to anInteger.- Parameters:
value- the string to convert- Returns:
- the parsed value, or
nullif the input isnull, blank, or invalid
-
toInteger
Converts the given string to anInteger, or returnsfallbackwhen parsing fails.- Parameters:
value- the string to convertfallback- value used when the input isnull, blank, or invalid- Returns:
- the parsed value, or
fallback
-
toInteger
public static int toInteger(boolean value) Convertstrueto1andfalseto0(same mapping as a typical Cintcast).- Parameters:
value- boolean to convert- Returns:
1or0, nevernull
-
toBoolean
Parses a string into aBoolean. Recognizestrue/false,yes/no,on/off,y/n,t/f(case-insensitive) and1/0after trimming.- Parameters:
value- the string to convert- Returns:
- the parsed value, or
nullif the input isnull, blank, or not one of the supported literals
-
toBoolean
Parses a string into aBoolean, or returnsfallbackwhen parsing fails.- Parameters:
value- the string to convertfallback- value used when the input isnull, blank, or not a supported literal- Returns:
- the parsed value, or
fallback
-
toBoolean
public static boolean toBoolean(int value) C-style conversion fromintto boolean:0isfalse, any non-zero value istrue.- Parameters:
value- Boolean value- Returns:
falseifvalue == 0, otherwisetrue
-
toBoolean
public static boolean toBoolean(long value) C-style conversion fromlongto boolean:0isfalse, any non-zero value istrue.- Parameters:
value- long value- Returns:
falseifvalue == 0, otherwisetrue
-
toBoolean
public static boolean toBoolean(float value) C-style conversion fromfloatto boolean:0.0fand-0.0farefalse, any other value (includingNaNand infinities) istrue.- Parameters:
value- float value- Returns:
falseif value is zero, otherwisetrue
-
toBoolean
public static boolean toBoolean(double value) C-style conversion fromdoubleto boolean:0.0dand-0.0darefalse, any other value (includingNaNand infinities) istrue.- Parameters:
value- double value- Returns:
falseif value is zero, otherwisetrue
-
toLong
Converts the given string to aLong.- Parameters:
value- the string to convert- Returns:
- the parsed value, or
nullif the input isnull, blank, or invalid
-
toLong
Converts the given string to aLong, or returnsfallbackwhen parsing fails.- Parameters:
value- the string to convertfallback- value used when the input isnull, blank, or invalid- Returns:
- the parsed value, or
fallback
-
toFloat
Converts the given string to aFloat.- Parameters:
value- the string to convert- Returns:
- the parsed value, or
nullif the input isnull, blank, or invalid
-
toFloat
Converts the given string to aFloat, or returnsfallbackwhen parsing fails.- Parameters:
value- the string to convertfallback- value used when the input isnull, blank, or invalid- Returns:
- the parsed value, or
fallback
-
toDouble
Converts the given string to aDouble.- Parameters:
value- the string to convert- Returns:
- the parsed value, or
nullif the input isnull, blank, or invalid
-
toDouble
Converts the given string to aDouble, or returnsfallbackwhen parsing fails.- Parameters:
value- the string to convertfallback- value used when the input isnull, blank, or invalid- Returns:
- the parsed value, or
fallback
-
toBigInteger
Converts the given string to aBigInteger.- Parameters:
value- the string to convert- Returns:
- the parsed value, or
nullif the input isnull, blank, or invalid
-
toBigInteger
Converts the given string to aBigInteger, or returnsfallbackwhen parsing fails.- Parameters:
value- the string to convertfallback- value used when the input isnull, blank, or invalid- Returns:
- the parsed value, or
fallback
-
toBigDecimal
Converts the given string to aBigDecimal.- Parameters:
value- the string to convert- Returns:
- the parsed value, or
nullif the input isnull, blank, or invalid
-
toBigDecimal
Converts the given string to aBigDecimal, or returnsfallbackwhen parsing fails.- Parameters:
value- the string to convertfallback- value used when the input isnull, blank, or invalid- Returns:
- the parsed value, or
fallback
-
parseNumber
Parses the given text into the requested numeric wrapper type.Supported target classes are:
Byte,Short,Integer,Long,Float,Double,BigInteger,BigDecimal.- Type Parameters:
T- the numeric type- Parameters:
text- the string to parsetargetClass- the target numeric type- Returns:
- the parsed value, or
nullif the input isnull, blank, invalid, or the target type is not supported
-
parseNumber
Parses the given text into the requested numeric wrapper type, or returnsfallbackwhen parsing fails or the target type is not supported.- Type Parameters:
T- the numeric type- Parameters:
text- the string to parsetargetClass- the target numeric typefallback- value used when the input isnull, blank, invalid, or unsupported- Returns:
- the parsed value, or
fallback
-
narrowNumber
Narrowsvalueto the requested numeric wrapper type without silent truncation.Integral targets (
Byte,Short,Integer,Long,BigInteger) reject fractional values and out-of-range magnitudes withArithmeticException.FloatandDoubleuse the usual widening conversions.- Parameters:
value- the source value, must not benulltargetClass- the target numeric wrapper type, must not benull- Returns:
- the narrowed value
- Throws:
ArithmeticException- if an exact integral conversion is not possible
-
toByteExact
Convertsvaluetobyte, rejecting fractional parts and out-of-range magnitudes.- Parameters:
value- the source value, must not benull- Returns:
- the exact
bytevalue - Throws:
ArithmeticException- if the value has a fractional part or does not fit inbyte
-
toShortExact
Convertsvaluetoshort, rejecting fractional parts and out-of-range magnitudes.- Parameters:
value- the source value, must not benull- Returns:
- the exact
shortvalue - Throws:
ArithmeticException- if the value has a fractional part or does not fit inshort
-
toIntExact
Convertsvaluetoint, rejecting fractional parts and out-of-range magnitudes.- Parameters:
value- the source value, must not benull- Returns:
- the exact
intvalue - Throws:
ArithmeticException- if the value has a fractional part or does not fit inint
-
toLongExact
Convertsvaluetolong, rejecting fractional parts and out-of-range magnitudes.- Parameters:
value- the source value, must not benull- Returns:
- the exact
longvalue - Throws:
ArithmeticException- if the value has a fractional part or does not fit inlong
-
toBigIntegerExact
ConvertsvaluetoBigInteger, rejecting fractional parts.- Parameters:
value- the source value, must not benull- Returns:
- the exact
BigIntegervalue - Throws:
ArithmeticException- if the value has a fractional part
-
toBigDecimal
ConvertsvaluetoBigDecimal.- Parameters:
value- the source value, must not benull- Returns:
- the
BigDecimalrepresentation
-
bytesToObjectBytes
Copies a primitivebyte[]into a boxedByte[]of the same length. Each element is autoboxed; the returned array is a new instance.- Parameters:
bytes- the source array, ornull- Returns:
- a new
Byte[]with the same values and order, ornullifbytesisnull
-
objectBytesToBytes
Copies a boxedByte[]into a primitivebyte[]of the same length. Each element is unboxed; the returned array is a new instance.- Parameters:
bytes- the source array, ornull- Returns:
- a new
byte[]with the same values and order, ornullifbytesisnull - Throws:
NullPointerException- if any element ofbytesisnull
-
shortsToObjectShorts
Copies a primitiveshort[]into a boxedShort[]of the same length. Each element is autoboxed; the returned array is a new instance.- Parameters:
shorts- the source array, ornull- Returns:
- a new
Short[]with the same values and order, ornullifshortsisnull
-
objectShortsToShorts
Copies a boxedShort[]into a primitiveshort[]of the same length. Each element is unboxed; the returned array is a new instance.- Parameters:
shorts- the source array, ornull- Returns:
- a new
short[]with the same values and order, ornullifshortsisnull - Throws:
NullPointerException- if any element ofshortsisnull
-
intsToObjectIntegers
Copies a primitiveint[]into a boxedInteger[]of the same length. Each element is autoboxed; the returned array is a new instance.- Parameters:
ints- the source array, ornull- Returns:
- a new
Integer[]with the same values and order, ornullifintsisnull
-
objectIntegersToInts
Copies a boxedInteger[]into a primitiveint[]of the same length. Each element is unboxed; the returned array is a new instance.- Parameters:
ints- the source array, ornull- Returns:
- a new
int[]with the same values and order, ornullifintsisnull - Throws:
NullPointerException- if any element ofintsisnull
-
longsToObjectLongs
Copies a primitivelong[]into a boxedLong[]of the same length. Each element is autoboxed; the returned array is a new instance.- Parameters:
longs- the source array, ornull- Returns:
- a new
Long[]with the same values and order, ornulliflongsisnull
-
objectLongsToLongs
Copies a boxedLong[]into a primitivelong[]of the same length. Each element is unboxed; the returned array is a new instance.- Parameters:
longs- the source array, ornull- Returns:
- a new
long[]with the same values and order, ornulliflongsisnull - Throws:
NullPointerException- if any element oflongsisnull
-
floatsToObjectFloats
Copies a primitivefloat[]into a boxedFloat[]of the same length. Each element is autoboxed; the returned array is a new instance.- Parameters:
floats- the source array, ornull- Returns:
- a new
Float[]with the same values and order, ornulliffloatsisnull
-
objectFloatsToFloats
Copies a boxedFloat[]into a primitivefloat[]of the same length. Each element is unboxed; the returned array is a new instance.- Parameters:
floats- the source array, ornull- Returns:
- a new
float[]with the same values and order, ornulliffloatsisnull - Throws:
NullPointerException- if any element offloatsisnull
-
doublesToObjectDoubles
Copies a primitivedouble[]into a boxedDouble[]of the same length. Each element is autoboxed; the returned array is a new instance.- Parameters:
doubles- the source array, ornull- Returns:
- a new
Double[]with the same values and order, ornullifdoublesisnull
-
objectDoublesToDoubles
Copies a boxedDouble[]into a primitivedouble[]of the same length. Each element is unboxed; the returned array is a new instance.- Parameters:
doubles- the source array, ornull- Returns:
- a new
double[]with the same values and order, ornullifdoublesisnull - Throws:
NullPointerException- if any element ofdoublesisnull
-
charsToObjectCharacters
Copies a primitivechar[]into a boxedCharacter[]of the same length. Each element is autoboxed; the returned array is a new instance.- Parameters:
chars- the source array, ornull- Returns:
- a new
Character[]with the same values and order, ornullifcharsisnull
-
objectCharactersToChars
Copies a boxedCharacter[]into a primitivechar[]of the same length. Each element is unboxed; the returned array is a new instance.- Parameters:
chars- the source array, ornull- Returns:
- a new
char[]with the same values and order, ornullifcharsisnull - Throws:
NullPointerException- if any element ofcharsisnull
-
isNumeric
Equivalent toisNumeric(str, Locale.ROOT); seeisNumeric(String, Locale)for full rules.- Parameters:
str- the text to check, must not benull- Returns:
trueif a root-localeNumberFormatparses the entirestr- Throws:
NullPointerException- ifstrisnull
-
isNumeric
Returns whetherstris consumed in full as a number byNumberFormat.getInstance(locale). The result depends onlocale: decimal separators, grouping symbols, and digit shapes follow that locale'sNumberFormatrules.- Parameters:
str- the text to check, must not benulllocale- the locale whose number format to use, must not benull- Returns:
trueif the locale'sNumberFormatparses the entirestr- Throws:
NullPointerException- ifstrorlocaleisnull
-
equals
public static boolean equals(double a, double b, double epsilon) Compares twodoublevalues using a tolerance.Values are considered equal when
Math.abs(a - b) <= epsilon. For special values this method follows intuitive equality: twoNaNvalues are equal, and infinities are equal only when they have the same sign.- Parameters:
a- the first valueb- the second valueepsilon- allowed absolute difference (must be non-negative and finite)- Returns:
trueif values are equal withinepsilon- Throws:
IllegalArgumentException- ifepsilonis negative,NaN, or infinite
-
equals
public static boolean equals(double a, double b) Compares twodoublevalues using a default tolerance of1e-9.- Parameters:
a- the first valueb- the second value- Returns:
trueif values are equal within the default tolerance
-
equals
public static boolean equals(float a, float b, float epsilon) Compares twofloatvalues using a tolerance.Values are considered equal when
Math.abs(a - b) <= epsilon. For special values this method follows intuitive equality: twoNaNvalues are equal, and infinities are equal only when they have the same sign.- Parameters:
a- the first valueb- the second valueepsilon- allowed absolute difference (must be non-negative and finite)- Returns:
trueif values are equal withinepsilon- Throws:
IllegalArgumentException- ifepsilonis negative,NaN, or infinite
-
equals
public static boolean equals(float a, float b) Compares twofloatvalues using a default tolerance of1e-6.- Parameters:
a- the first valueb- the second value- Returns:
trueif values are equal within the default tolerance
-
isZero
public static boolean isZero(double a) Returns whether the givendoubleis effectively zero using the defaultdoubletolerance.- Parameters:
a- the value to test- Returns:
trueifais equal to0.0within the default epsilon
-
isZero
public static boolean isZero(double a, double epsilon) Returns whether the givendoubleis effectively zero using a custom tolerance.- Parameters:
a- the value to testepsilon- allowed absolute difference from zero (must be non-negative and finite)- Returns:
trueifais equal to0.0withinepsilon- Throws:
IllegalArgumentException- ifepsilonis negative,NaN, or infinite
-
isZero
public static boolean isZero(float a) Returns whether the givenfloatis effectively zero using the defaultfloattolerance.- Parameters:
a- the value to test- Returns:
trueifais equal to0.0fwithin the default epsilon
-
isZero
public static boolean isZero(float a, float epsilon) Returns whether the givenfloatis effectively zero using a custom tolerance.- Parameters:
a- the value to testepsilon- allowed absolute difference from zero (must be non-negative and finite)- Returns:
trueifais equal to0.0fwithinepsilon- Throws:
IllegalArgumentException- ifepsilonis negative,NaN, or infinite
-