Class OpenNumber

java.lang.Object
cloud.opencode.base.core.OpenNumber
public final class OpenNumber extends Object
Number Utility Class - Validation, parsing, conversion, formatting and arithmetic operations 数值工具类 - 验证、解析、转换、格式化和算术运算

Provides comprehensive number operations including validation, parsing, conversion, formatting and range control.

提供全面的数值操作，包括验证、解析、转换、格式化和范围控制。参考 Guava Ints/Longs、Commons NumberUtils。

Features | 主要功能:

  • Validation (isNumber, isInteger, isDouble, isParsable) - 验证
  • Parsing with default value (toInt, toLong, toDouble) - 带默认值解析
  • Safe parsing with Optional (tryParseInt, tryParseLong) - 安全解析
  • Overflow-safe conversion (saturatedCast, checkedCast) - 溢出安全转换
  • Range control (clamp, inRange) - 范围控制
  • High-precision arithmetic (add, subtract, multiply, divide) - 高精度运算
  • Formatting (format, formatPercent, formatMoney) - 格式化

Usage Examples | 使用示例:

// Validation - 验证
boolean isNum = OpenNumber.isNumber("123.45");

// Parsing - 解析
int value = OpenNumber.toInt("123", 0);
OptionalInt opt = OpenNumber.tryParseInt("123");

// Range control - 范围控制
int clamped = OpenNumber.clamp(value, 0, 100);

// High-precision arithmetic - 高精度运算
BigDecimal result = OpenNumber.add(a, b, c);

Security | 安全性:

  • Thread-safe: Yes (stateless) - 线程安全: 是 (无状态)
  • Null-safe: Yes - 空值安全: 是
Since:
JDK 25, opencode-base-core V1.0.0
Author:
Leon Soo www.LeonSoo.com
See Also:

  • Method Summary

    Modifier and Type
    Method
    Description
    static BigDecimal
    add(Number... values)
    High-precision addition of multiple Number values.
    static int
    checkedCast(long value)
    Converts a long to an int, throwing ArithmeticException on overflow.
    static double
    clamp(double value, double min, double max)
    Clamps the double value to the range [min, max].
    static int
    clamp(int value, int min, int max)
    Clamps the value to the range [min, max].
    static long
    clamp(long value, long min, long max)
    Clamps the long value to the range [min, max].
    static int
    compare(double x, double y)
    Compares two double values.
    static int
    compare(int x, int y)
    Compares two int values.
    static int
    compare(long x, long y)
    Compares two long values.
    static int
    constrainToRange(int value, int min, int max)
    Constrains the value to the range [min, max] (alias for clamp).
    static BigDecimal
    divide(BigDecimal a, BigDecimal b, int scale)
    High-precision division with half-up rounding.
    static BigDecimal
    divide(BigDecimal a, BigDecimal b, int scale, RoundingMode mode)
    High-precision division with specified rounding mode.
    static String
    format(double value, String pattern)
    Formats a double value using the given pattern.
    static String
    format(BigDecimal value, String pattern)
    Formats a BigDecimal value using the given pattern.
    static String
    formatMoney(BigDecimal value)
    Formats a BigDecimal value as a currency string using the JVM's default Locale.
    static String
    formatPercent(double value, int scale)
    Formats a double value as a percentage string with the given number of decimal places.
    static boolean
    inRange(int value, int min, int max)
    Returns true if the value is within the range [min, max].
    static boolean
    inRange(long value, long min, long max)
    Returns true if the long value is within the range [min, max].
    static boolean
    isCreatable(String str)
    Returns true if the string can be created as a Number (including hex and octal).
    static boolean
    isDouble(String str)
    Returns true if the string can be parsed as a double value.
    static boolean
    isInteger(String str)
    Returns true if the string represents a valid integer.
    static boolean
    isLong(String str)
    Returns true if the string can be parsed as a long value.
    static boolean
    isNumber(String str)
     
    static boolean
    isParsable(String str)
    Returns true if the string can be parsed as a decimal number (no hex/octal).
    static int
    max(int... array)
    Returns the maximum value in the int array.
    static long
    max(long... array)
    Returns the maximum value in the long array.
    static <T extends Comparable<T>>
    T
    max(T a, T b)
    Returns the larger of two Comparable values.
    static int
    min(int... array)
    Returns the minimum value in the int array.
    static long
    min(long... array)
    Returns the minimum value in the long array.
    static <T extends Comparable<T>>
    T
    min(T a, T b)
    Returns the smaller of two Comparable values.
    static BigDecimal
    multiply(BigDecimal a, BigDecimal b)
    High-precision multiplication.
    static double
    round(double value, int scale)
    Rounds the double value to the specified number of decimal places.
    static BigDecimal
    round(BigDecimal value, int scale)
    Rounds the BigDecimal value to the specified scale using half-up rounding.
    static BigDecimal
    round(BigDecimal value, int scale, RoundingMode mode)
    Rounds the BigDecimal value to the specified scale with the given rounding mode.
    static BigDecimal
    roundHalfEven(BigDecimal value, int scale)
    Rounds the BigDecimal value using banker's rounding (HALF_EVEN).
    static int
    saturatedCast(long value)
    Converts a long to an int, clamping to Integer.MAX_VALUE or Integer.MIN_VALUE on overflow.
    static int
    saturatedCast(BigDecimal value)
    Converts a BigDecimal to an int, clamping on overflow.
    static BigDecimal
    subtract(BigDecimal a, BigDecimal b)
    High-precision subtraction.
    static BigDecimal
    toBigDecimal(String str)
    Parses the string as a BigDecimal, returning null on failure.
    static BigDecimal
    toBigDecimal(String str, BigDecimal defaultValue)
    Parses the string as a BigDecimal, returning the default value on failure.
    static BigInteger
    toBigInteger(String str)
    Parses the string as a BigInteger, returning null on failure.
    static double
    toDouble(String str, double defaultValue)
    Parses the string as a double, returning the default value on failure.
    static float
    toFloat(String str, float defaultValue)
    Parses the string as a float, returning the default value on failure.
    static int
    toInt(String str, int defaultValue)
    Parses the string as an int, returning the default value on failure.
    static long
    toLong(String str, long defaultValue)
    Parses the string as a long, returning the default value on failure.
    static OptionalDouble
    tryParseDouble(String str)
    Tries to parse the string as a double, returning OptionalDouble.empty() on failure.
    static OptionalInt
    tryParseInt(String str)
    Tries to parse the string as an int, returning OptionalInt.empty() on failure.
    static OptionalLong
    tryParseLong(String str)
    Tries to parse the string as a long, returning OptionalLong.empty() on failure.

    Methods inherited from class Object

    clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

  • Method Details

    • isNumber

      public static boolean isNumber(String str)

    • isInteger

      public static boolean isInteger(String str)
      Returns true if the string represents a valid integer. 检查字符串是否为整数
      Parameters:
      str - the string | 字符串
      Returns:
      true if it is an integer | 如果是整数返回 true

    • isLong

      public static boolean isLong(String str)
      Returns true if the string can be parsed as a long value. 检查字符串是否为 long 类型整数
      Parameters:
      str - the string | 字符串
      Returns:
      true if parsable as long | 如果可解析为 long 返回 true

    • isDouble

      public static boolean isDouble(String str)
      Returns true if the string can be parsed as a double value. 检查字符串是否为 double 类型浮点数
      Parameters:
      str - the string | 字符串
      Returns:
      true if parsable as double | 如果可解析为 double 返回 true

    • isCreatable

      public static boolean isCreatable(String str)
      Returns true if the string can be created as a Number (including hex and octal). 检查字符串是否可以创建为 Number
      Parameters:
      str - the string | 字符串
      Returns:
      true if creatable as Number | 如果可以创建为 Number 返回 true

    • isParsable

      public static boolean isParsable(String str)
      Returns true if the string can be parsed as a decimal number (no hex/octal). 检查字符串是否可解析为数字
      Parameters:
      str - the string | 字符串
      Returns:
      true if parsable | 如果可以解析返回 true

    • toInt

      public static int toInt(String str, int defaultValue)
      Parses the string as an int, returning the default value on failure. 解析字符串为 int
      Parameters:
      str - the string | 字符串
      defaultValue - default value | 默认值
      Returns:
      parsed value or default | 解析结果或默认值

    • toLong

      public static long toLong(String str, long defaultValue)
      Parses the string as a long, returning the default value on failure. 解析字符串为 long
      Parameters:
      str - the string | 字符串
      defaultValue - default value | 默认值
      Returns:
      parsed value or default | 解析结果或默认值

    • toFloat

      public static float toFloat(String str, float defaultValue)
      Parses the string as a float, returning the default value on failure. 解析字符串为 float
      Parameters:
      str - the string | 字符串
      defaultValue - default value | 默认值
      Returns:
      parsed value or default | 解析结果或默认值

    • toDouble

      public static double toDouble(String str, double defaultValue)
      Parses the string as a double, returning the default value on failure. 解析字符串为 double
      Parameters:
      str - the string | 字符串
      defaultValue - default value | 默认值
      Returns:
      parsed value or default | 解析结果或默认值

    • toBigDecimal

      public static BigDecimal toBigDecimal(String str)
      Parses the string as a BigDecimal, returning null on failure. 解析字符串为 BigDecimal
      Parameters:
      str - the string | 字符串
      Returns:
      BigDecimal, or null if parsing fails | BigDecimal，如果解析失败返回 null

    • toBigDecimal

      public static BigDecimal toBigDecimal(String str, BigDecimal defaultValue)
      Parses the string as a BigDecimal, returning the default value on failure. 解析字符串为 BigDecimal
      Parameters:
      str - the string | 字符串
      defaultValue - default value | 默认值
      Returns:
      BigDecimal or default | BigDecimal 或默认值

    • toBigInteger

      public static BigInteger toBigInteger(String str)
      Parses the string as a BigInteger, returning null on failure. 解析字符串为 BigInteger
      Parameters:
      str - the string | 字符串
      Returns:
      BigInteger, or null if parsing fails | BigInteger，如果解析失败返回 null

    • tryParseInt

      public static OptionalInt tryParseInt(String str)
      Tries to parse the string as an int, returning OptionalInt.empty() on failure. 尝试解析为 int
      Parameters:
      str - the string | 字符串
      Returns:
      OptionalInt | OptionalInt

    • tryParseLong

      public static OptionalLong tryParseLong(String str)
      Tries to parse the string as a long, returning OptionalLong.empty() on failure. 尝试解析为 long
      Parameters:
      str - the string | 字符串
      Returns:
      OptionalLong | OptionalLong

    • tryParseDouble

      public static OptionalDouble tryParseDouble(String str)
      Tries to parse the string as a double, returning OptionalDouble.empty() on failure. 尝试解析为 double
      Parameters:
      str - the string | 字符串
      Returns:
      OptionalDouble | OptionalDouble

    • saturatedCast

      public static int saturatedCast(long value)
      Converts a long to an int, clamping to Integer.MAX_VALUE or Integer.MIN_VALUE on overflow. 将 long 转为 int，溢出时截断到 int 范围
      Parameters:
      value - long value | long 值
      Returns:
      int value, or Integer.MAX_VALUE / Integer.MIN_VALUE on overflow | int 值，溢出时返回 Integer.MAX_VALUE 或 Integer.MIN_VALUE

    • checkedCast

      public static int checkedCast(long value)
      Converts a long to an int, throwing ArithmeticException on overflow. 将 long 转为 int，溢出时抛出异常
      Parameters:
      value - long value | long 值
      Returns:
      int value | int 值
      Throws:
      ArithmeticException - if overflow | 如果溢出

    • saturatedCast

      public static int saturatedCast(BigDecimal value)
      Converts a BigDecimal to an int, clamping on overflow. 将 BigDecimal 转为 int，溢出时截断
      Parameters:
      value - BigDecimal value | BigDecimal 值
      Returns:
      int value | int 值

    • compare

      public static int compare(int x, int y)
      Compares two int values. 比较两个 int 值
      Parameters:
      x - first value | 值1
      y - second value | 值2
      Returns:
      comparison result | 比较结果

    • compare

      public static int compare(long x, long y)
      Compares two long values. 比较两个 long 值
      Parameters:
      x - first value | 值1
      y - second value | 值2
      Returns:
      comparison result | 比较结果

    • compare

      public static int compare(double x, double y)
      Compares two double values. 比较两个 double 值
      Parameters:
      x - first value | 值1
      y - second value | 值2
      Returns:
      comparison result | 比较结果

    • max

      public static <T extends Comparable<T>> T max(T a, T b)
      Returns the larger of two Comparable values. 返回两个值中的较大值
      Type Parameters:
      T - value type | 值类型
      Parameters:
      a - first value | 值1
      b - second value | 值2
      Returns:
      the larger value | 较大值

    • min

      public static <T extends Comparable<T>> T min(T a, T b)
      Returns the smaller of two Comparable values. 返回两个值中的较小值
      Type Parameters:
      T - value type | 值类型
      Parameters:
      a - first value | 值1
      b - second value | 值2
      Returns:
      the smaller value | 较小值

    • max

      public static int max(int... array)
      Returns the maximum value in the int array. 返回数组中的最大值
      Parameters:
      array - int array | int 数组
      Returns:
      maximum value | 最大值
      Throws:
      IllegalArgumentException - if array is empty | 如果数组为空

    • min

      public static int min(int... array)
      Returns the minimum value in the int array. 返回数组中的最小值
      Parameters:
      array - int array | int 数组
      Returns:
      minimum value | 最小值
      Throws:
      IllegalArgumentException - if array is empty | 如果数组为空

    • max

      public static long max(long... array)
      Returns the maximum value in the long array. 返回 long 数组中的最大值

    • min

      public static long min(long... array)
      Returns the minimum value in the long array. 返回 long 数组中的最小值

    • clamp

      public static int clamp(int value, int min, int max)
      Clamps the value to the range [min, max]. 限制值在指定范围内
      Parameters:
      value - the value | 值
      min - minimum value | 最小值
      max - maximum value | 最大值
      Returns:
      value clamped to range | 范围内的值

    • clamp

      public static long clamp(long value, long min, long max)
      Clamps the long value to the range [min, max]. 限制值在指定范围内

    • clamp

      public static double clamp(double value, double min, double max)
      Clamps the double value to the range [min, max]. 限制值在指定范围内

    • constrainToRange

      public static int constrainToRange(int value, int min, int max)
      Constrains the value to the range [min, max] (alias for clamp). 限制值在指定范围内（Guava 风格别名）

    • inRange

      public static boolean inRange(int value, int min, int max)
      Returns true if the value is within the range [min, max]. 检查值是否在范围内 [min, max]
      Parameters:
      value - the value | 值
      min - minimum value | 最小值
      max - maximum value | 最大值
      Returns:
      true if in range | 如果在范围内返回 true

    • inRange

      public static boolean inRange(long value, long min, long max)
      Returns true if the long value is within the range [min, max]. 检查值是否在范围内 [min, max]

    • add

      public static BigDecimal add(Number... values)
      High-precision addition of multiple Number values. 高精度加法
      Parameters:
      values - number values | 数值数组
      Returns:
      sum | 和

    • subtract

      public static BigDecimal subtract(BigDecimal a, BigDecimal b)
      High-precision subtraction. 高精度减法

    • multiply

      public static BigDecimal multiply(BigDecimal a, BigDecimal b)
      High-precision multiplication. 高精度乘法

    • divide

      public static BigDecimal divide(BigDecimal a, BigDecimal b, int scale)
      High-precision division with half-up rounding. 高精度除法
      Parameters:
      a - dividend | 被除数
      b - divisor | 除数
      scale - number of decimal places | 小数位数
      Returns:
      quotient | 商

    • divide

      public static BigDecimal divide(BigDecimal a, BigDecimal b, int scale, RoundingMode mode)
      High-precision division with specified rounding mode. 高精度除法
      Parameters:
      a - dividend | 被除数
      b - divisor | 除数
      scale - number of decimal places | 小数位数
      mode - rounding mode | 舍入模式
      Returns:
      quotient | 商

    • round

      public static BigDecimal round(BigDecimal value, int scale)
      Rounds the BigDecimal value to the specified scale using half-up rounding. 四舍五入
      Parameters:
      value - BigDecimal value | BigDecimal 值
      scale - number of decimal places | 小数位数
      Returns:
      rounded value | 四舍五入后的值

    • round

      public static BigDecimal round(BigDecimal value, int scale, RoundingMode mode)
      Rounds the BigDecimal value to the specified scale with the given rounding mode. 四舍五入
      Parameters:
      value - BigDecimal value | BigDecimal 值
      scale - number of decimal places | 小数位数
      mode - rounding mode | 舍入模式
      Returns:
      rounded value | 舍入后的值

    • round

      public static double round(double value, int scale)
      Rounds the double value to the specified number of decimal places. 四舍五入
      Parameters:
      value - double value | double 值
      scale - number of decimal places | 小数位数
      Returns:
      rounded value | 四舍五入后的值

    • roundHalfEven

      public static BigDecimal roundHalfEven(BigDecimal value, int scale)
      Rounds the BigDecimal value using banker's rounding (HALF_EVEN). 银行家舍入（四舍六入五成双）
      Parameters:
      value - BigDecimal value | BigDecimal 值
      scale - number of decimal places | 小数位数
      Returns:
      rounded value | 舍入后的值

    • format

      public static String format(double value, String pattern)
      Formats a double value using the given pattern. 格式化数值
      Parameters:
      value - double value | double 值
      pattern - format pattern | 格式模式
      Returns:
      formatted string | 格式化后的字符串

    • format

      public static String format(BigDecimal value, String pattern)
      Formats a BigDecimal value using the given pattern. 格式化数值
      Parameters:
      value - BigDecimal value | BigDecimal 值
      pattern - format pattern | 格式模式
      Returns:
      formatted string | 格式化后的字符串

    • formatPercent

      public static String formatPercent(double value, int scale)
      Formats a double value as a percentage string with the given number of decimal places. 格式化为百分比
      Parameters:
      value - double value | double 值
      scale - number of decimal places | 小数位数
      Returns:
      percentage string | 百分比字符串

    • formatMoney

      public static String formatMoney(BigDecimal value)
      Formats a BigDecimal value as a currency string using the JVM's default Locale. 使用 JVM 默认 Locale 将 BigDecimal 值格式化为货币字符串。
      Parameters:
      value - BigDecimal value | BigDecimal 值
      Returns:
      currency string | 货币字符串
      API Note:
      The output depends on the JVM's default Locale (Locale.getDefault()). Results may differ across servers with different Locale settings. For explicit Locale control, use NumberFormat.getCurrencyInstance(java.util.Locale). 输出取决于 JVM 默认 Locale，不同服务器上的结果可能不同。 如需显式指定 Locale，请使用 NumberFormat.getCurrencyInstance(java.util.Locale)。