`hutool.core.util.number`¶

Python port of Java Hutool’s NumberUtil.

提供精确的加减乘除运算、四舍五入、数字格式化、数字判断等常用数字工具方法。

Module Contents¶

Classes¶

NumberUtil

数字工具类

Data¶

`__all__`
`DEFAULT_NUMBER_PARAM`

API¶

hutool.core.util.number.__all__ = ['NumberUtil']¶

hutool.core.util.number.DEFAULT_NUMBER_PARAM = 'DefaultParam(...)'¶

class hutool.core.util.number.NumberUtil¶

数字工具类

DEFAULT_DIV_SCALE: Final[int] = 10¶

ZERO: Final[decimal.Decimal] = 'Decimal(...)'¶

_BASE62_ALPHABET = '0123456789ABCDEFGHIJKLMNOPQRSTUVWXYZabcdefghijklmnopqrstuvwxyz'¶

_BASE62_REVERSE = None¶

static add(*values: Union[int, float, str, None, decimal.Decimal]) → decimal.Decimal¶: 提供精确的加法运算如果传入多个值为None或者空，则返回0 :param values: 多个被加值 :return: 和

static sub(*values: Union[int, float, str, None, decimal.Decimal]) → decimal.Decimal¶: 提供精确的减法运算如果传入多个值为None或者空，则返回0 :param values: 多个被减值 :return: 差

static mul(*values: Union[int, float, str, None, decimal.Decimal]) → decimal.Decimal¶

提供精确的乘法运算

如果传入多个值为None或者空，则返回0

参数:: values – 多个被乘值
返回:: 积

static div(v1: Union[int, float, str, None, decimal.Decimal], v2: Union[int, float, str, decimal.Decimal], scale: Union[int, decimal.Decimal] = DEFAULT_DIV_SCALE, rounding: str = decimal.ROUND_HALF_UP) → decimal.Decimal¶: 提供(相对)精确的除法运算,当发生除不尽的情况时,由scale指定精确度 :param v1: 被除数 :param v2: 除数 :param scale: 精确度，如果为负值，取绝对值, 如果为Decimal, 需要为Decimal(‘0.00’)格式 :param rounding: 保留小数的模式 :return: 两个参数的商

static ceil_div(v1: int, v2: int) → int¶: 除法, 向上取整 :param v1: 被除数 :param v2: 除数 :return: 两个参数的商

static round(number: Union[int, float, str, None, decimal.Decimal], scale: Union[int, decimal.Decimal], rounding: str = decimal.ROUND_HALF_UP) → decimal.Decimal¶: 保留固定位数小数 :param number: 数字值 :param scale: 精确度，如果为负值，取绝对值, 如果为Decimal, 需要为Decimal(‘0.00’)格式 :param rounding: 保留小数的模式 :return: 新值

static round_str(number: Union[int, float, str, None, decimal.Decimal], scale: Union[int, decimal.Decimal], rounding: str = decimal.ROUND_HALF_UP) → str¶: 保留固定位数小数 :param number: 数字值 :param scale: 精确度，如果为负值，取绝对值, 如果为Decimal, 需要为Decimal(‘0.00’)格式 :param rounding: 保留小数的模式 :return: 新值

static round_half_even(number: Union[int, float, str, None, decimal.Decimal], scale: Union[int, decimal.Decimal]) → decimal.Decimal¶: 四舍六入五成双计算法四舍六入五成双是一种比较精确比较科学的计数保留法，是一种数字修约规则。算法规则: 四舍六入五考虑，五后非零就进一，五后皆零看奇偶，五前为偶应舍去，五前为奇要进一。 :param number: 需要科学计算的数据 :param scale: 精确度，如果为负值，取绝对值, 如果为Decimal, 需要为Decimal(‘0.00’)格式 :return: 结果

static round_down(number: Union[int, float, str, None, decimal.Decimal], scale: Union[int, decimal.Decimal]) → decimal.Decimal¶: 保留固定小数位数，舍去多余位数 :param number: 需要科学计算的数据 :param scale: 保留的小数位 :return: 结果

static decimal_format(pattern: str, value: Union[int, float, str, None, decimal.Decimal]) → str¶

格式化

参数:

pattern –
格式，例如:
- '{:.2f}' 保留两位小数
- '{:.0f}' 取所有整数部分
- '{:.2%}' 以百分比方式计数，并取两位小数
- '{:.5e}' 显示为科学计数法，并取五位小数
- '{:,}' 每三位以逗号进行分隔
value – 值

返回:

格式化后的值

static decimal_format_money(value: float) → str¶: 格式化金额输出，每三位用逗号分隔 :param value: 金额 :return: 格式化后的值

static format_percent(number: float, scale: int) → str¶: 格式化百分比，小数采用四舍五入方式 :param number: 值 :param scale: 保留小数位数 :return: 百分比

static is_number(string: str) → bool¶: 是否为数字，支持包括： 1、10进制 2、16进制数字（0x开头, 0x1aF） 3、科学计数法形式（1234E3） 4、正负数标识形式（+123、-234） :param string: 字符串值 :return: 是否为数字

static is_int(string: Union[str, None]) → bool¶: 判断string是否是整数 :param string: 字符串值 :return: 是否为整数

static is_float(string: str) → bool¶: 判断字符串是否是浮点数 :param string: 字符串值 :return: 是否是浮点数

static is_primes(n: int) → bool¶: 是否是质数（素数）质数表的质数又称素数。指整数在一个大于1的自然数中,除了1和此整数自身外,没法被其他自然数整除的数。 :param n: 数字 :return: 是否是质数

static generate_random_number(begin: int, end: int, size: int, seed: Optional[int] = None) → List[int]¶: 生成不重复随机数根据给定的最小数字和最大数字，以及随机数的个数，产生指定的不重复的列表 :param begin: 最小数字（包含该数） :param end: 最大数字（不包含该数） :param size: 指定产生随机数的个数 :param seed: 随机种子 :return: 随机int列表

static factorial(start: int, end: int = 0) → int¶: 计算阶乘 factorial(start, end) = start * (start - 1) * … * (end + 1) :param start: 阶乘起始（包含） :param end: 阶乘结束，必须小于起始（不包括） :return: 结果

static divisor(m: int, n: int) → int¶: 最大公约数 :param m: 第一个值 :param n: 第二个值 :return: 最大公约数

static multiple(m: int, n: int) → int¶: 最小公倍数 :param m: 第一个值 :param n: 第二个值 :return: 最小公倍数

static get_binary_str(number: int) → str¶: 获得数字对应的二进制字符串 :param number: 数字 :return: 二进制字符串

static binary_to_int(binary_str: str) → int¶: 二进制转int :param binary_str: 二进制字符串 :return: int

static compare(num1: Union[int, float, str, decimal.Decimal], num2: Union[int, float, str, decimal.Decimal]) → int¶: 比较两个值的大小 :param num1: 第一个值 :param num2: 第二个值 :return: x==y返回0，x<y返回小于0的数，x>y返回大于0的数

static is_greater(num1: Union[int, float, str, decimal.Decimal], num2: Union[int, float, str, decimal.Decimal]) → bool¶: 比较大小，参数1 > 参数2 返回True :param num1: 数字1 :param num2: 数字2 :return: 是否大于

static is_greater_or_equal(num1: Union[int, float, str, decimal.Decimal], num2: Union[int, float, str, decimal.Decimal]) → bool¶: 比较大小，参数1 >= 参数2 返回True :param num1: 数字1 :param num2: 数字2 :return: 是否大于等于

static is_less(num1: Union[int, float, str, decimal.Decimal], num2: Union[int, float, str, decimal.Decimal]) → bool¶: 比较大小，参数1 < 参数2 返回True :param num1: 数字1 :param num2: 数字2 :return: 是否小于

static is_less_or_equal(num1: Union[int, float, str, decimal.Decimal], num2: Union[int, float, str, decimal.Decimal]) → bool¶: 比较大小，参数1 <= 参数2 返回True :param num1: 数字1 :param num2: 数字2 :return: 是否小于等于

static is_in(value: Union[int, float, str, decimal.Decimal], min_include: Union[int, float, str, decimal.Decimal], max_include: Union[int, float, str, decimal.Decimal]) → bool¶: 检查值是否在指定范围内 :param value: 值 :param min_include: 最小值（包含） :param max_include: 最大值（包含） :return: 经过检查后的值

static equals(num1: Union[int, float, str, decimal.Decimal], num2: Union[int, float, str, decimal.Decimal]) → bool¶: 比较大小，值相等返回True :param num1: 数字1 :param num2: 数字2 :return: 是否相等

static min(*numbers: Union[int, float, str, decimal.Decimal]) → decimal.Decimal¶: 取最小值 :param numbers: 数字数组 :return: 最小值

static max(*numbers: Union[int, float, str, decimal.Decimal]) → decimal.Decimal¶: 取最大值 :param numbers: 数字数组 :return: 最大值

static to_str(number: Union[int, float, decimal.Decimal], normalize: bool = True, default_value: Optional[str] = None) → str¶: 数字转字符串 :param number: 数字 :param normalize: 是否去除末尾多余0，例如5.0返回5 :param default_value: 如果number参数为None，返回此默认值 :return: 字符串

static to_decimal(number: Union[int, float, str, None, decimal.Decimal]) → decimal.Decimal¶: 转成Decimal float有精度问题，转换为字符串后再转换 None或””或空白符转换为0 :param number: 数字 :return: Decimal

static count(total: int, part: int) → int¶: 计算等份个数 :param total: 总数 :param part: 每份的个数 :return: 分成了几份

static none_to_zero(number: Union[int, float, str, decimal.Decimal]) → Union[int, float, str, decimal.Decimal]¶: 空转0 :param number: 参数 :return: 参数为空时返回0的值

static zero2one(value: int) → int¶: 如果给定值为0，返回1，否则返回原值 :param value: 值 :return: 1或非0值

static is_beside(number1: Union[int, float, str, decimal.Decimal], number2: Union[int, float, str, decimal.Decimal]) → bool¶: 判断两个数字是否相邻，例如1和2相邻，1和3不相邻判断方法为做差取绝对值判断是否为1 :param number1: 数字1 :param number2: 数字2 :return: 是否相邻

static part_value(total: int, part_count: int, is_plus_one_when_has_rem: bool = True) → int¶: 把给定的总数平均分成N份，返回每份的个数如果is_plus_one_when_has_rem为True，则当除以分数有余数时每份+1，否则丢弃余数部分 :param total: 总数 :param part_count: 份数 :param is_plus_one_when_has_rem: 在有余数时是否每份+1 :return: 每份的个数

static pow(number: Union[int, float, str, decimal.Decimal], n: int) → decimal.Decimal¶: 提供精确的幂运算 :param number: 底数 :param n: 指数 :return: 幂的积

static is_power_of_two(n: int) → bool¶: 判断一个整数是否是2的幂 :param n: 待验证的整数 :return: 如果n是2的幂返回True, 反之返回False

static parse_int(number_str: str, default_value: Union[int, hutool.core._base.DefaultParam, None] = DEFAULT_NUMBER_PARAM) → int¶: 解析转换数字字符串为int型数字，规则如下： 1、0x开头的视为16进制数字 2、0开头的忽略开头的0 3、其它情况按照10进制转换 4、空串返回默认值 5、.123形式返回0（按照小于0的小数对待） 6、123.56截取小数点之前的数字，忽略小数部分 7、返回默认值 :param number_str: 数字，支持0x开头、0开头和普通十进制 :param default_value: 返回默认值 :return: int

static parse_float(number_str: str, default_value: Union[int, hutool.core._base.DefaultParam, None] = DEFAULT_NUMBER_PARAM) → float¶: 解析转换数字字符串为float型数字，规则如下： 1、0开头的忽略开头的0 2、空串返回默认值 3、其它情况按照10进制转换 :param number_str: 数字，支持0x开头、0开头和普通十进制 :param default_value: 返回默认值 :return: float

static to_bytes(value: int, length: Optional[int] = None, byteorder: Literal[little, big] = 'big', signed: bool = True) → bytes¶: int值转bytes :param value: 值 :param length: bytes长度 :param byteorder: 默认大端字节序（高位字节在前，低位字节在后） :param signed: 是否带符号 :return: bytes

static to_int(value: bytes, byteorder: Literal[little, big] = 'big', signed: bool = True) → int¶: bytes转int :param value: bytes :param byteorder: 默认大端字节序（高位字节在前，低位字节在后） :param signed: 是否带符号 :return: int

static is_valid(number: Union[int, float, decimal.Decimal]) → bool¶: 检查是否为有效的数字检查是否为无限大，或者Not a Number :param number: 被检查的数字 :return: 检查结果，非数字类型和None将返回False

static is_odd(num: int) → bool¶: 检查是否为奇数 :param num: 被判断的数值 :return: 是否是奇数

static is_even(num: int) → bool¶: 检查是否为偶数 :param num: 被判断的数值 :return: 是否是偶数

static int_or_default(data: Any, default: int = 0) → int¶

安全地将数据转换为整数，失败时返回默认值。

支持 int、float、str、list/tuple（取第一个元素）等类型。 None、空容器直接返回默认值。

参数:

data – 待转换的数据
default – 转换失败时的默认值，默认 0

返回:

整数值

static float_or_default(data: Any, default: float = 0.0) → float¶

安全地将数据转换为浮点数，失败时返回默认值。

None、空容器直接返回默认值。

参数:

data – 待转换的数据
default – 转换失败时的默认值，默认 0.0

返回:

浮点数值

static int_or_0(data: Any) → int¶

安全转 int，失败返回 0。

等价于 int_or_default(data, 0)，提供与 huTools 兼容的命名。

参数:: data – 待转换的值
返回:: int 值，转换失败返回 0

static float_or_0(data: Any) → float¶

安全转 float，失败返回 0.0。

等价于 float_or_default(data, 0.0)，提供与 huTools 兼容的命名。

参数:: data – 待转换的值
返回:: float 值，转换失败返回 0.0

static avg(data: Iterable) → float¶

计算数值列表的平均值。

空列表返回 0.0。

参数:: data – 数值可迭代对象
返回:: 平均值

static median(data: Iterable) → float¶

计算数值列表的中位数。

空列表返回 0.0。

参数:: data – 数值可迭代对象
返回:: 中位数

static robust_min(data: Iterable) → Optional[float]¶

安全取最小值，空列表返回 None。

与 CollUtil.safe_min 不同，本方法对空输入返回 None 而非抛出异常。

参数:: data – 数值可迭代对象
返回:: 最小值，空列表返回 None

static robust_max(data: Iterable) → Optional[float]¶

安全取最大值，空列表返回 None。

与 CollUtil.safe_max 不同，本方法对空输入返回 None 而非抛出异常。

参数:: data – 数值可迭代对象
返回:: 最大值，空列表返回 None

static robust_div(a: float, b: float, default: float = 0.0) → float¶

安全除法，除数为 0 时返回默认值（默认 0.0）。

参数:

a – 被除数
b – 除数
default – 除数为 0 时的返回值，默认 0.0

返回:

除法结果或默认值

static percent(part: float, total: float, default: float = 0.0) → float¶

百分比计算，total 为 0 时返回默认值。

计算公式：(part / total) * 100。

参数:

part – 部分值
total – 总值
default – total 为 0 时的返回值，默认 0.0

返回:

百分比值（如 25.0 表示 25%）

static num_encode(n: int) → str¶

将整数编码为 base62 字符串（字符集：0-9A-Za-z）。

负数会以 $ 前缀表示。

参数:: n – 待编码的整数
返回:: base62 编码字符串

static bytes_to_int(data: bytes) → int¶

将 bytes 按大端序转换为 int。

参数:: data – 字节数据
返回:: 转换后的整数

>>> NumberUtil.bytes_to_int(b'\x00\x00\x01\x00')
256
>>> NumberUtil.bytes_to_int(b'\xff')
255

static int_to_bytes(value: int, length: int = 4) → bytes¶

将 int 按大端序转换为指定长度的 bytes。

参数:

value – 整数值
length – 输出 bytes 的长度（字节数），默认 4

返回:

字节数据

>>> NumberUtil.int_to_bytes(256, 2)
b'\x01\x00'
>>> NumberUtil.int_to_bytes(0, 1)
b'\x00'

static num_decode(s: str) → int¶

将 base62 字符串解码为整数。

参数:: s – base62 编码字符串
返回:: 解码后的整数
抛出:: ValueError – 字符串包含非法字符时

static range_(start: int, end: int, step: int = 1) → List[int]¶

生成数字范围列表（含 start，不含 end）。

参数:

start – 起始值（含）
end – 结束值（不含）
step – 步长，默认 1

返回:

数字列表

static append_range(collection: List[int], start: int, end: int, step: int = 1) → List[int]¶

追加数字范围到列表。

参数:

collection – 目标列表
start – 起始值（含）
end – 结束值（不含）
step – 步长，默认 1

返回:

追加后的列表

static generate_by_set(count: int, min_val: int, max_val: int) → List[int]¶

生成 count 个 [min_val, max_val] 范围内的不重复随机数。

参数:

count – 个数
min_val – 最小值（含）
max_val – 最大值（含）

返回:

不重复随机数列表

抛出:

ValueError – 范围不足时

static calculate(expression: str) → float¶

计算数学表达式（仅支持安全的数字和运算符）。

支持: +, -, *, /, //, %, **, 括号。

参数:: expression – 数学表达式字符串
返回:: 计算结果
抛出:: ValueError – 表达式不安全时

static sqrt(x: Union[int, float, str, decimal.Decimal], scale: int = 10) → decimal.Decimal¶

精确平方根。

参数:

x – 待开方的数值
scale – 小数位数

返回:

平方根

static is_integer(s: Union[str, None]) → bool¶

判断字符串是否为整数（与 is_int 相同）。

参数:: s – 字符串
返回:: 是否为整数

static is_double(s: str) → bool¶

判断字符串是否为浮点数（与 is_float 相同）。

参数:: s – 字符串
返回:: 是否为浮点数

static parse_number(s: str) → Union[int, float]¶

解析字符串为数字，整数返回 int，小数返回 float。

参数:: s – 数字字符串
返回:: int 或 float
抛出:: ValueError – 解析失败时

static parse_long(number_str: str, default_value: int = 0) → int¶

解析字符串为长整数（Python int）。

参数:

number_str – 数字字符串
default_value – 解析失败时的默认值

返回:

长整数

static binary_to_long(binary_str: str) → int¶

二进制字符串转整数。

参数:: binary_str – 二进制字符串，如 "1010"
返回:: 对应的整数
抛出:: ValueError – 非法二进制字符串时

static to_big_integer(n: Union[int, str], radix: int = 10) → int¶

将数字或字符串转为大整数（Python int）。

参数:

n – 数字或字符串
radix – 进制，默认 10

返回:

大整数

static new_big_integer(s: str, radix: int = 10) → int¶

按指定进制解析字符串为大整数。

参数:

s – 数字字符串
radix – 进制（2、8、10、16 等）

返回:

大整数

static to_unsigned_byte_array(n: int) → bytes¶

将非负整数转为无符号字节数组（大端序）。

参数:: n – 非负整数
返回:: 字节串
抛出:: ValueError – n 为负数时

static from_unsigned_byte_array(data: bytes) → int¶

无符号字节数组（大端序）转整数。

参数:: data – 字节串
返回:: 整数

static integer_sqrt(x: int) → int¶

整数平方根（向下取整）。

使用牛顿迭代法，避免浮点精度问题。

参数:: x – 非负整数
返回:: 平方根的整数部分
抛出:: ValueError – x 为负数时

static process_multiple(n: int, m: int) → int¶

计算组合数 C(n, m)。

参数:

n – 总数
m – 选取数

返回:

组合数

抛出:

ValueError – 参数非法时

static parse_double(s: str, default_value: float = 0.0) → float¶

解析字符串为 float，失败返回默认值。

参数:

s – 数字字符串
default_value – 默认值

返回:

float 值

static range(start: int, end: int, step: int = 1) → List[int]¶

生成数字范围列表（含 start，不含 end）。

参数:

start – 起始值（含）
end – 结束值（不含）
step – 步长，默认 1

返回:

数字列表

static generate(count: int, min_val: int = 0, max_val: int = 100) → List[int]¶

生成指定个数的随机整数列表。

参数:

count – 个数
min_val – 最小值（含）
max_val – 最大值（不含）

返回:

随机整数列表

static null_to_zero(n: Optional[Union[int, float]]) → Union[int, float]¶

None 转为 0。

参数:: n – 数值
返回:: n 为 None 时返回 0，否则返回原值

static is_long(value: Any) → bool¶

判断值是否为长整数类型（Python int 类型）。

参数:: value – 待检查的值
返回:: 是否为 int 类型（排除 bool）

static is_valid_number(value: Any) → bool¶

判断值是否为有效数字（支持科学计数法）。

None、非数字类型返回 False。NaN 和 Inf 返回 False。

参数:: value – 待检查的值
返回:: 是否为有效数字

static to_float_safe(value: Any, default: float = 0.0) → float¶

安全地将值转为 float，失败返回默认值。

参数:

value – 待转换的值
default – 转换失败时的默认值，默认 0.0

返回:

float 值

static operator_exec(left: Any, operator: str, right: Any) → bool¶

执行运算符比较操作。

支持 ==、!=、>、>=、<、<= 六种比较运算符。用于需要动态指定比较运算符的场景。

参数:

left – 左操作数
operator – 运算符字符串（"=="、"!="、">"、">="、"<"、"<="）
right – 右操作数

返回:

比较结果

抛出:

ValueError – 不支持的运算符时

hutool.core.util.number¶

Module Contents¶

Classes¶

Data¶

API¶

`hutool.core.util.number`¶