Class NumberUtils

java.lang.Object
io.github.connellite.util.NumberUtils

public class NumberUtils extends Object
  • Constructor Details

    • NumberUtils

      public NumberUtils()
  • Method Details

    • toByte

      public static Byte toByte(String value)
      Converts the given string to a Byte.
      Parameters:
      value - the string to convert
      Returns:
      the parsed value, or null if the input is null, blank, or invalid
    • toByte

      public static Byte toByte(String value, Byte fallback)
      Converts the given string to a Byte, or returns fallback when parsing fails.
      Parameters:
      value - the string to convert
      fallback - value used when the input is null, blank, or invalid
      Returns:
      the parsed value, or fallback
    • toShort

      public static Short toShort(String value)
      Converts the given string to a Short.
      Parameters:
      value - the string to convert
      Returns:
      the parsed value, or null if the input is null, blank, or invalid
    • toShort

      public static Short toShort(String value, Short fallback)
      Converts the given string to a Short, or returns fallback when parsing fails.
      Parameters:
      value - the string to convert
      fallback - value used when the input is null, blank, or invalid
      Returns:
      the parsed value, or fallback
    • toInteger

      public static Integer toInteger(String value)
      Converts the given string to an Integer.
      Parameters:
      value - the string to convert
      Returns:
      the parsed value, or null if the input is null, blank, or invalid
    • toInteger

      public static Integer toInteger(String value, Integer fallback)
      Converts the given string to an Integer, or returns fallback when parsing fails.
      Parameters:
      value - the string to convert
      fallback - value used when the input is null, blank, or invalid
      Returns:
      the parsed value, or fallback
    • toInteger

      public static int toInteger(boolean value)
      Converts true to 1 and false to 0 (same mapping as a typical C int cast).
      Parameters:
      value - boolean to convert
      Returns:
      1 or 0, never null
    • toBoolean

      public static Boolean toBoolean(String value)
      Parses a string into a Boolean. Recognizes true/false, yes/no, on/off, y/n, t/f (case-insensitive) and 1/0 after trimming.
      Parameters:
      value - the string to convert
      Returns:
      the parsed value, or null if the input is null, blank, or not one of the supported literals
    • toBoolean

      public static Boolean toBoolean(String value, Boolean fallback)
      Parses a string into a Boolean, or returns fallback when parsing fails.
      Parameters:
      value - the string to convert
      fallback - value used when the input is null, blank, or not a supported literal
      Returns:
      the parsed value, or fallback
    • toBoolean

      public static boolean toBoolean(int value)
      C-style conversion from int to boolean: 0 is false, any non-zero value is true.
      Parameters:
      value - Boolean value
      Returns:
      false if value == 0, otherwise true
    • toBoolean

      public static boolean toBoolean(long value)
      C-style conversion from long to boolean: 0 is false, any non-zero value is true.
      Parameters:
      value - long value
      Returns:
      false if value == 0, otherwise true
    • toBoolean

      public static boolean toBoolean(float value)
      C-style conversion from float to boolean: 0.0f and -0.0f are false, any other value (including NaN and infinities) is true.
      Parameters:
      value - float value
      Returns:
      false if value is zero, otherwise true
    • toBoolean

      public static boolean toBoolean(double value)
      C-style conversion from double to boolean: 0.0d and -0.0d are false, any other value (including NaN and infinities) is true.
      Parameters:
      value - double value
      Returns:
      false if value is zero, otherwise true
    • toLong

      public static Long toLong(String value)
      Converts the given string to a Long.
      Parameters:
      value - the string to convert
      Returns:
      the parsed value, or null if the input is null, blank, or invalid
    • toLong

      public static Long toLong(String value, Long fallback)
      Converts the given string to a Long, or returns fallback when parsing fails.
      Parameters:
      value - the string to convert
      fallback - value used when the input is null, blank, or invalid
      Returns:
      the parsed value, or fallback
    • toFloat

      public static Float toFloat(String value)
      Converts the given string to a Float.
      Parameters:
      value - the string to convert
      Returns:
      the parsed value, or null if the input is null, blank, or invalid
    • toFloat

      public static Float toFloat(String value, Float fallback)
      Converts the given string to a Float, or returns fallback when parsing fails.
      Parameters:
      value - the string to convert
      fallback - value used when the input is null, blank, or invalid
      Returns:
      the parsed value, or fallback
    • toDouble

      public static Double toDouble(String value)
      Converts the given string to a Double.
      Parameters:
      value - the string to convert
      Returns:
      the parsed value, or null if the input is null, blank, or invalid
    • toDouble

      public static Double toDouble(String value, Double fallback)
      Converts the given string to a Double, or returns fallback when parsing fails.
      Parameters:
      value - the string to convert
      fallback - value used when the input is null, blank, or invalid
      Returns:
      the parsed value, or fallback
    • toBigInteger

      public static BigInteger toBigInteger(String value)
      Converts the given string to a BigInteger.
      Parameters:
      value - the string to convert
      Returns:
      the parsed value, or null if the input is null, blank, or invalid
    • toBigInteger

      public static BigInteger toBigInteger(String value, BigInteger fallback)
      Converts the given string to a BigInteger, or returns fallback when parsing fails.
      Parameters:
      value - the string to convert
      fallback - value used when the input is null, blank, or invalid
      Returns:
      the parsed value, or fallback
    • toBigDecimal

      public static BigDecimal toBigDecimal(String value)
      Converts the given string to a BigDecimal.
      Parameters:
      value - the string to convert
      Returns:
      the parsed value, or null if the input is null, blank, or invalid
    • toBigDecimal

      public static BigDecimal toBigDecimal(String value, BigDecimal fallback)
      Converts the given string to a BigDecimal, or returns fallback when parsing fails.
      Parameters:
      value - the string to convert
      fallback - value used when the input is null, blank, or invalid
      Returns:
      the parsed value, or fallback
    • parseNumber

      public static <T extends Number> T parseNumber(String text, Class<T> targetClass)
      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 parse
      targetClass - the target numeric type
      Returns:
      the parsed value, or null if the input is null, blank, invalid, or the target type is not supported
    • parseNumber

      public static <T extends Number> T parseNumber(String text, Class<T> targetClass, T fallback)
      Parses the given text into the requested numeric wrapper type, or returns fallback when parsing fails or the target type is not supported.
      Type Parameters:
      T - the numeric type
      Parameters:
      text - the string to parse
      targetClass - the target numeric type
      fallback - value used when the input is null, blank, invalid, or unsupported
      Returns:
      the parsed value, or fallback
    • narrowNumber

      public static Number narrowNumber(Number value, Class<?> targetClass)
      Narrows value to the requested numeric wrapper type without silent truncation.

      Integral targets (Byte, Short, Integer, Long, BigInteger) reject fractional values and out-of-range magnitudes with ArithmeticException. Float and Double use the usual widening conversions.

      Parameters:
      value - the source value, must not be null
      targetClass - the target numeric wrapper type, must not be null
      Returns:
      the narrowed value
      Throws:
      ArithmeticException - if an exact integral conversion is not possible
    • toByteExact

      public static byte toByteExact(Number value)
      Converts value to byte, rejecting fractional parts and out-of-range magnitudes.
      Parameters:
      value - the source value, must not be null
      Returns:
      the exact byte value
      Throws:
      ArithmeticException - if the value has a fractional part or does not fit in byte
    • toShortExact

      public static short toShortExact(Number value)
      Converts value to short, rejecting fractional parts and out-of-range magnitudes.
      Parameters:
      value - the source value, must not be null
      Returns:
      the exact short value
      Throws:
      ArithmeticException - if the value has a fractional part or does not fit in short
    • toIntExact

      public static int toIntExact(Number value)
      Converts value to int, rejecting fractional parts and out-of-range magnitudes.
      Parameters:
      value - the source value, must not be null
      Returns:
      the exact int value
      Throws:
      ArithmeticException - if the value has a fractional part or does not fit in int
    • toLongExact

      public static long toLongExact(Number value)
      Converts value to long, rejecting fractional parts and out-of-range magnitudes.
      Parameters:
      value - the source value, must not be null
      Returns:
      the exact long value
      Throws:
      ArithmeticException - if the value has a fractional part or does not fit in long
    • toBigIntegerExact

      public static BigInteger toBigIntegerExact(Number value)
      Converts value to BigInteger, rejecting fractional parts.
      Parameters:
      value - the source value, must not be null
      Returns:
      the exact BigInteger value
      Throws:
      ArithmeticException - if the value has a fractional part
    • toBigDecimal

      public static BigDecimal toBigDecimal(Number value)
      Converts value to BigDecimal.
      Parameters:
      value - the source value, must not be null
      Returns:
      the BigDecimal representation
    • bytesToObjectBytes

      public static Byte[] bytesToObjectBytes(byte[] bytes)
      Copies a primitive byte[] into a boxed Byte[] of the same length. Each element is autoboxed; the returned array is a new instance.
      Parameters:
      bytes - the source array, or null
      Returns:
      a new Byte[] with the same values and order, or null if bytes is null
    • objectBytesToBytes

      public static byte[] objectBytesToBytes(Byte[] bytes)
      Copies a boxed Byte[] into a primitive byte[] of the same length. Each element is unboxed; the returned array is a new instance.
      Parameters:
      bytes - the source array, or null
      Returns:
      a new byte[] with the same values and order, or null if bytes is null
      Throws:
      NullPointerException - if any element of bytes is null
    • shortsToObjectShorts

      public static Short[] shortsToObjectShorts(short[] shorts)
      Copies a primitive short[] into a boxed Short[] of the same length. Each element is autoboxed; the returned array is a new instance.
      Parameters:
      shorts - the source array, or null
      Returns:
      a new Short[] with the same values and order, or null if shorts is null
    • objectShortsToShorts

      public static short[] objectShortsToShorts(Short[] shorts)
      Copies a boxed Short[] into a primitive short[] of the same length. Each element is unboxed; the returned array is a new instance.
      Parameters:
      shorts - the source array, or null
      Returns:
      a new short[] with the same values and order, or null if shorts is null
      Throws:
      NullPointerException - if any element of shorts is null
    • intsToObjectIntegers

      public static Integer[] intsToObjectIntegers(int[] ints)
      Copies a primitive int[] into a boxed Integer[] of the same length. Each element is autoboxed; the returned array is a new instance.
      Parameters:
      ints - the source array, or null
      Returns:
      a new Integer[] with the same values and order, or null if ints is null
    • objectIntegersToInts

      public static int[] objectIntegersToInts(Integer[] ints)
      Copies a boxed Integer[] into a primitive int[] of the same length. Each element is unboxed; the returned array is a new instance.
      Parameters:
      ints - the source array, or null
      Returns:
      a new int[] with the same values and order, or null if ints is null
      Throws:
      NullPointerException - if any element of ints is null
    • longsToObjectLongs

      public static Long[] longsToObjectLongs(long[] longs)
      Copies a primitive long[] into a boxed Long[] of the same length. Each element is autoboxed; the returned array is a new instance.
      Parameters:
      longs - the source array, or null
      Returns:
      a new Long[] with the same values and order, or null if longs is null
    • objectLongsToLongs

      public static long[] objectLongsToLongs(Long[] longs)
      Copies a boxed Long[] into a primitive long[] of the same length. Each element is unboxed; the returned array is a new instance.
      Parameters:
      longs - the source array, or null
      Returns:
      a new long[] with the same values and order, or null if longs is null
      Throws:
      NullPointerException - if any element of longs is null
    • floatsToObjectFloats

      public static Float[] floatsToObjectFloats(float[] floats)
      Copies a primitive float[] into a boxed Float[] of the same length. Each element is autoboxed; the returned array is a new instance.
      Parameters:
      floats - the source array, or null
      Returns:
      a new Float[] with the same values and order, or null if floats is null
    • objectFloatsToFloats

      public static float[] objectFloatsToFloats(Float[] floats)
      Copies a boxed Float[] into a primitive float[] of the same length. Each element is unboxed; the returned array is a new instance.
      Parameters:
      floats - the source array, or null
      Returns:
      a new float[] with the same values and order, or null if floats is null
      Throws:
      NullPointerException - if any element of floats is null
    • doublesToObjectDoubles

      public static Double[] doublesToObjectDoubles(double[] doubles)
      Copies a primitive double[] into a boxed Double[] of the same length. Each element is autoboxed; the returned array is a new instance.
      Parameters:
      doubles - the source array, or null
      Returns:
      a new Double[] with the same values and order, or null if doubles is null
    • objectDoublesToDoubles

      public static double[] objectDoublesToDoubles(Double[] doubles)
      Copies a boxed Double[] into a primitive double[] of the same length. Each element is unboxed; the returned array is a new instance.
      Parameters:
      doubles - the source array, or null
      Returns:
      a new double[] with the same values and order, or null if doubles is null
      Throws:
      NullPointerException - if any element of doubles is null
    • charsToObjectCharacters

      public static Character[] charsToObjectCharacters(char[] chars)
      Copies a primitive char[] into a boxed Character[] of the same length. Each element is autoboxed; the returned array is a new instance.
      Parameters:
      chars - the source array, or null
      Returns:
      a new Character[] with the same values and order, or null if chars is null
    • objectCharactersToChars

      public static char[] objectCharactersToChars(Character[] chars)
      Copies a boxed Character[] into a primitive char[] of the same length. Each element is unboxed; the returned array is a new instance.
      Parameters:
      chars - the source array, or null
      Returns:
      a new char[] with the same values and order, or null if chars is null
      Throws:
      NullPointerException - if any element of chars is null
    • isNumeric

      public static boolean isNumeric(String str)
      Equivalent to isNumeric(str, Locale.ROOT); see isNumeric(String, Locale) for full rules.
      Parameters:
      str - the text to check, must not be null
      Returns:
      true if a root-locale NumberFormat parses the entire str
      Throws:
      NullPointerException - if str is null
    • isNumeric

      public static boolean isNumeric(String str, Locale locale)
      Returns whether str is consumed in full as a number by NumberFormat.getInstance(locale). The result depends on locale: decimal separators, grouping symbols, and digit shapes follow that locale's NumberFormat rules.
      Parameters:
      str - the text to check, must not be null
      locale - the locale whose number format to use, must not be null
      Returns:
      true if the locale's NumberFormat parses the entire str
      Throws:
      NullPointerException - if str or locale is null
    • equals

      public static boolean equals(double a, double b, double epsilon)
      Compares two double values using a tolerance.

      Values are considered equal when Math.abs(a - b) <= epsilon. For special values this method follows intuitive equality: two NaN values are equal, and infinities are equal only when they have the same sign.

      Parameters:
      a - the first value
      b - the second value
      epsilon - allowed absolute difference (must be non-negative and finite)
      Returns:
      true if values are equal within epsilon
      Throws:
      IllegalArgumentException - if epsilon is negative, NaN, or infinite
    • equals

      public static boolean equals(double a, double b)
      Compares two double values using a default tolerance of 1e-9.
      Parameters:
      a - the first value
      b - the second value
      Returns:
      true if values are equal within the default tolerance
    • equals

      public static boolean equals(float a, float b, float epsilon)
      Compares two float values using a tolerance.

      Values are considered equal when Math.abs(a - b) <= epsilon. For special values this method follows intuitive equality: two NaN values are equal, and infinities are equal only when they have the same sign.

      Parameters:
      a - the first value
      b - the second value
      epsilon - allowed absolute difference (must be non-negative and finite)
      Returns:
      true if values are equal within epsilon
      Throws:
      IllegalArgumentException - if epsilon is negative, NaN, or infinite
    • equals

      public static boolean equals(float a, float b)
      Compares two float values using a default tolerance of 1e-6.
      Parameters:
      a - the first value
      b - the second value
      Returns:
      true if values are equal within the default tolerance
    • isZero

      public static boolean isZero(double a)
      Returns whether the given double is effectively zero using the default double tolerance.
      Parameters:
      a - the value to test
      Returns:
      true if a is equal to 0.0 within the default epsilon
    • isZero

      public static boolean isZero(double a, double epsilon)
      Returns whether the given double is effectively zero using a custom tolerance.
      Parameters:
      a - the value to test
      epsilon - allowed absolute difference from zero (must be non-negative and finite)
      Returns:
      true if a is equal to 0.0 within epsilon
      Throws:
      IllegalArgumentException - if epsilon is negative, NaN, or infinite
    • isZero

      public static boolean isZero(float a)
      Returns whether the given float is effectively zero using the default float tolerance.
      Parameters:
      a - the value to test
      Returns:
      true if a is equal to 0.0f within the default epsilon
    • isZero

      public static boolean isZero(float a, float epsilon)
      Returns whether the given float is effectively zero using a custom tolerance.
      Parameters:
      a - the value to test
      epsilon - allowed absolute difference from zero (must be non-negative and finite)
      Returns:
      true if a is equal to 0.0f within epsilon
      Throws:
      IllegalArgumentException - if epsilon is negative, NaN, or infinite