`hutool.core.util.convert`¶

类型转换工具类

提供 bytes↔int、通用类型转换、中英文数字互转、全角半角互转等常用类型转换方法。

Module Contents¶

Classes¶

ConvertUtil

类型转换工具类。

API¶

class hutool.core.util.convert.ConvertUtil¶

类型转换工具类。

提供 bytes_to_int、int_to_bytes、to_str、convert、 number_to_chinese、digit_to_chinese、chinese_to_number、 number_to_word、chinese_money_to_number、number_to_simple、 to_sbc、to_dbc 等常用类型转换方法。

static bytes_to_int(data: bytes) → int¶

将 bytes 按大端序转换为 int。

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

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

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

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

参数:

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

返回:

字节数据

抛出:

ValueError – value 为负数时

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

static to_str(value: Any, encoding: str = 'utf-8') → str¶

安全地将值转换为字符串。

bytes/bytearray 类型使用 encoding 解码，其他类型使用 str() 转换。

参数:

value – 待转换的值
encoding – 字节解码编码，默认 "utf-8"

返回:

字符串

>>> ConvertUtil.to_str(b'hello')
'hello'
>>> ConvertUtil.to_str(123)
'123'
>>> ConvertUtil.to_str(None)
''

static convert(value: Any, target_type: type) → Any¶

将值转换为指定类型。

支持常见类型：int、float、str、bool、list、tuple、set。 None 输入返回 target_type() 的默认值。

参数:

value – 待转换的值
target_type – 目标类型

返回:

转换后的值

抛出:

ValueError – 无法转换时

>>> ConvertUtil.convert('123', int)
123
>>> ConvertUtil.convert(3.14, str)
'3.14'
>>> ConvertUtil.convert(None, str)
''

_SIMPLE_DIGITS = '零一二三四五六七八九'¶

_FORMAL_DIGITS = '零壹贰叁肆伍陆柒捌玖'¶

static number_to_chinese(number: float) → str¶

将数字转换为中文小写数字（一二三……）。

支持负数和小数，整数部分逐位转换，小数部分逐位读出。

参数:: number – 待转换的数字
返回:: 中文小写数字字符串

>>> ConvertUtil.number_to_chinese(123)
'一百二十三'
>>> ConvertUtil.number_to_chinese(-5)
'负五'
>>> ConvertUtil.number_to_chinese(3.14)
'三点一四'

static digit_to_chinese(number: float) → str¶

将数字转换为中文大写数字（壹贰叁……）。

支持负数和小数，整数部分逐位转换，小数部分逐位读出。

参数:: number – 待转换的数字
返回:: 中文大写数字字符串

>>> ConvertUtil.digit_to_chinese(123)
'壹佰贰拾叁'
>>> ConvertUtil.digit_to_chinese(-5)
'负伍'

static _number_to_chinese_impl(number: float, digits: str) → str¶: 内部实现：根据 digits 映射表将数字转为中文。

static chinese_to_number(chinese_str: str) → float¶

将中文数字字符串转回阿拉伯数字。

同时支持小写（一二三……）和大写（壹贰叁……）中文数字。

参数:: chinese_str – 中文数字字符串
返回:: 对应的数字

>>> ConvertUtil.chinese_to_number('一百二十三')
123
>>> ConvertUtil.chinese_to_number('壹佰贰拾叁')
123
>>> ConvertUtil.chinese_to_number('负五')
-5
>>> ConvertUtil.chinese_to_number('三点一四')
3.14

_ONES = ['zero', 'one', 'two', 'three', 'four', 'five', 'six', 'seven', 'eight', 'nine', 'ten', 'eleven', 't...¶

_TENS = ['', '', 'twenty', 'thirty', 'forty', 'fifty', 'sixty', 'seventy', 'eighty', 'ninety']¶

static number_to_word(number: int) → str¶

将非负整数（0–9999）转换为英文单词。

参数:: number – 0 到 9999 之间的整数
返回:: 英文单词
抛出:: ValueError – 超出支持范围或为负数时

>>> ConvertUtil.number_to_word(0)
'zero'
>>> ConvertUtil.number_to_word(123)
'one hundred twenty-three'
>>> ConvertUtil.number_to_word(2024)
'two thousand twenty-four'

static chinese_money_to_number(money_str: str) → int¶

将中文金额字符串转换为整数。

支持小写（零一二三四五六七八九十百千万亿）和大写（零壹贰叁肆伍陆柒捌玖拾佰仟萬億）。

参数:: money_str – 中文金额字符串
返回:: 对应的整数

>>> ConvertUtil.chinese_money_to_number('壹佰贰拾叁')
123
>>> ConvertUtil.chinese_money_to_number('一万二千三百四十五')
12345
>>> ConvertUtil.chinese_money_to_number('叁萬伍仟')
35000

static number_to_simple(number: float, precision: int = 1) → str¶

将大数字缩写为带单位的简短形式。

支持 K（千）、M（百万）、B（十亿）。

参数:

number – 待缩写的数字
precision – 小数精度，默认 1

返回:

缩写后的字符串

>>> ConvertUtil.number_to_simple(1234)
'1.2K'
>>> ConvertUtil.number_to_simple(3400000)
'3.4M'
>>> ConvertUtil.number_to_simple(5600000000)
'5.6B'
>>> ConvertUtil.number_to_simple(42)
'42'

static to_sbc(s: str) → str¶

将半角字符转换为全角字符。

ASCII 可见字符 0x21–0x7E 映射为 0xFF01–0xFF5E，空格 0x20 映射为 0x3000。

参数:: s – 输入字符串
返回:: 全角字符串

>>> ConvertUtil.to_sbc('ABC')
'ＡＢＣ'
>>> ConvertUtil.to_sbc('123')
'１２３'
>>> ConvertUtil.to_sbc(' ')
'　'

static to_dbc(s: str) → str¶

将全角字符转换为半角字符。

0xFF01–0xFF5E 映射为 ASCII 0x21–0x7E， 0x3000``（全角空格）映射为普通空格 ``0x20。

参数:: s – 输入字符串
返回:: 半角字符串

>>> ConvertUtil.to_dbc('ＡＢＣ')
'ABC'
>>> ConvertUtil.to_dbc('１２３')
'123'
>>> ConvertUtil.to_dbc('　')
' '

static dict_to_tabular(data: dict, headers: Optional[list] = None) → list¶

将 dict of dict 转换为二维列表（表格形式）。

参数:

data – 字典的字典，如 {"row1": {"a": 1, "b": 2}, "row2": {"a": 3, "b": 4}}
headers – 表头列表，为 None 时自动从第一个值中提取键

返回:

二维列表，第一行为表头

data = {"r1": {"a": 1, "b": 2}, "r2": {"a": 3, "b": 4}}
table = ConvertUtil.dict_to_tabular(data)
assert table[0] == ["a", "b"]
assert table[1] == [1, 2]

static list_to_tabular(data: list, headers: Optional[list] = None) → list¶

将 list of dict 转换为二维列表（表格形式）。

参数:

data – 字典列表
headers – 表头列表，为 None 时自动从第一个 dict 中提取键

返回:

二维列表，第一行为表头

data = [{"name": "Alice", "age": 30}, {"name": "Bob", "age": 25}]
table = ConvertUtil.list_to_tabular(data)
assert table[0] == ["name", "age"]
assert table[1] == ["Alice", 30]

hutool.core.util.convert¶

Module Contents¶

Classes¶

API¶

`hutool.core.util.convert`¶