`hutool.core.util.strings`¶

Java Hutool StrUtil 的 Python 移植版。

包含字符和字符串工具类：CharPool、CharUtil、CharSequenceUtil、StrPool、StrUtil。

Module Contents¶

Classes¶

`CharPool`	常用字符常量。
`CharUtil`	字符工具类。
`CharSequenceUtil`	CharSequence 工具类，提供常用的字符串操作。
`StrPool`	常用字符串常量。
`StrUtil`	主字符串工具类。继承 `CharSequenceUtil` 和 `StrPool`，提供所有字符串操作的统一入口。

Data¶

__all__

API¶

hutool.core.util.strings.__all__ = ['CharPool', 'CharSequenceUtil', 'CharUtil', 'StrPool', 'StrUtil']¶

class hutool.core.util.strings.CharPool¶

常用字符常量。

EMPTY: str = <Multiline-String>¶

SPACE: str = ' '¶

TAB: str = '\t'¶

DOT: str = '.'¶

SLASH: str = '/'¶

BACKSLASH: str = '\\'¶

CR: str = '\r'¶

LF: str = '\n'¶

DASHED: str = '-'¶

UNDERLINE: str = '_'¶

COMMA: str = ','¶

DELIM_START: str = '{'¶

DELIM_END: str = '}'¶

BRACKET_START: str = '['¶

BRACKET_END: str = ']'¶

DOUBLE_QUOTES: str = '"'¶

SINGLE_QUOTE: str = "'"¶

AMP: str = '&'¶

COLON: str = ':'¶

AT: str = '@'¶

class hutool.core.util.strings.CharUtil¶

Bases: hutool.core.util.strings.CharPool

字符工具类。

static is_ascii(ch: str) → bool¶

判断字符是否为ASCII字符（0~127）。

参数:: ch – 待检查的字符
返回:: 是否为ASCII字符

static is_ascii_printable(ch: str) → bool¶

判断字符是否为可打印ASCII字符（32~126）。

参数:: ch – 待检查的字符
返回:: 是否为可打印ASCII字符

static is_ascii_control(ch: str) → bool¶

判断字符是否为ASCII控制字符（0~31和127）。

参数:: ch – 待检查的字符
返回:: 是否为控制字符

static is_letter(ch: str) → bool¶

判断字符是否为字母（A~Z或a~z）。

参数:: ch – 待检查的字符
返回:: 是否为字母

static is_letter_upper(ch: str) → bool¶

判断字符是否为大写字母（A~Z）。

参数:: ch – 待检查的字符
返回:: 是否为大写字母

static is_letter_lower(ch: str) → bool¶

判断字符是否为小写字母（a~z）。

参数:: ch – 待检查的字符
返回:: 是否为小写字母

static is_number(ch: str) → bool¶

判断字符是否为数字（0~9）。

参数:: ch – 待检查的字符
返回:: 是否为数字

static is_hex_char(ch: str) → bool¶

判断字符是否为十六进制字符（0~9, a~f, A~F）。

参数:: ch – 待检查的字符
返回:: 是否为十六进制字符

static is_letter_or_number(ch: str) → bool¶

判断字符是否为字母或数字（A~Z, a~z, 0~9）。

参数:: ch – 待检查的字符
返回:: 是否为字母或数字

static is_blank_char(ch: str) → bool¶

判断字符是否为空白字符。空白字符包括空格、制表符、全角空格和不间断空格。

参数:: ch – 待检查的字符
返回:: 是否为空白字符

static is_emoji(ch: str) → bool¶

判断字符是否为表情符号。

参数:: ch – 待检查的字符
返回:: 是否为表情符号

static is_file_separator(ch: str) → bool¶

判断字符是否为文件分隔符（’/’ 或 ‘'）。

参数:: ch – 待检查的字符
返回:: 是否为文件分隔符

static equals(ch1: str, ch2: str, case_insensitive: bool) → bool¶

比较两个字符是否相等。

参数:

ch1 – 第一个字符
ch2 – 第二个字符
case_insensitive – 是否忽略大小写

返回:

两个字符是否相等

static digit16(ch: str) → str¶

获取字符的十六进制值。

参数:: ch – 待转换的字符
返回:: 十六进制字符串表示

static to_close_char(ch: str) → str¶

将字母或数字转换为带圈字符形式。

Examples:

'1' -> '①' (①)
'A' -> 'Ⓐ' (Ⓐ)
'a' -> 'ⓐ' (ⓐ)

如果字符不支持转换，则返回原字符。

参数:: ch – 待转换的字符
返回:: 带圈字符，不支持时返回原字符

static to_close_by_number(number: int) → str¶

将数字（1~20）转换为带圈数字形式。

Examples:

-> '①' (①)
-> '⑫' (⑫)
-> '⑳' (⑳)

参数:: number – 待转换的数字（必须在1~20范围内）
返回:: 带圈数字字符
抛出:: ValueError – 数字不在[1, 20]范围内时抛出异常

class hutool.core.util.strings.CharSequenceUtil¶

CharSequence 工具类，提供常用的字符串操作。

static is_blank(string: Optional[str]) → bool¶

判断字符串是否为空白。当字符串为 None、空字符串（""）或全部由空白字符组成时，视为空白。

参数:: string – 待检查的字符串
返回:: 是否为空白字符串

static is_not_blank(string: Optional[str]) → bool¶

判断字符串是否不为空白（与 is_blank() 相反）。

参数:: string – 待检查的字符串
返回:: 是否不为空白字符串

static has_blank(*strings: Optional[str]) → bool¶

判断给定的多个字符串中是否存在空白字符串。当 strings 为空或其中任一元素为空白时返回 True。

参数:: strings – 一个或多个待检查的字符串
返回:: 是否存在空白字符串

static is_all_blank(*strings: Optional[str]) → bool¶

判断给定的多个字符串是否全部为空白。当 strings 为空或所有元素均为空白时返回 True。

参数:: strings – 一个或多个待检查的字符串
返回:: 是否全部为空白字符串

static is_empty(string: Optional[str]) → bool¶

判断字符串是否为空（None 或 ""）。

参数:: string – 待检查的字符串
返回:: 是否为 None 或空字符串

static is_not_empty(string: Optional[str]) → bool¶

判断字符串是否不为空（与 is_empty() 相反）。

参数:: string – 待检查的字符串
返回:: 是否不为 None 且不为空

static empty_if_none(string: Optional[str]) → str¶

如果 string 为 None 则返回空字符串，否则返回原字符串。

参数:: string – 待检查的字符串
返回:: 原字符串或 ""

static none_to_empty(string: Optional[str]) → str¶

将 None 转换为空字符串。

参数:: string – 待转换的字符串
返回:: string 为 None 时返回 ""，否则返回原字符串

static none_to_default(string: Optional[str], default: str) → str¶

如果 string 为 None 则返回 default，否则返回 str(string)。

参数:

string – 待转换的字符串
default – 默认值

返回:

字符串本身或默认值

static empty_to_default(string: Optional[str], default: str) → str¶

如果 string 为 None 或 "" 则返回 default，否则返回 str(string)。

参数:

string – 待转换的字符串
default – 默认值

返回:

字符串本身或默认值

static blank_to_default(string: Optional[str], default: str) → str¶

如果 string 为 None、空字符串或空白字符串则返回 default，否则返回 str(string)。

参数:

string – 待转换的字符串
default – 默认值

返回:

字符串本身或默认值

static empty_to_none(string: Optional[str]) → Optional[str]¶

将空字符串转换为 None。

参数:: string – 待转换的字符串
返回:: string 为空时返回 None，否则返回原字符串

static has_empty(*strings: Optional[str]) → bool¶

判断给定的多个字符串中是否存在空字符串（None 或 ""）。当 strings 为空或其中任一元素为空时返回 True。

参数:: strings – 一个或多个待检查的字符串
返回:: 是否存在空字符串

static is_all_empty(*strings: Optional[str]) → bool¶

判断给定的多个字符串是否全部为空。当 strings 为空或所有元素均为空时返回 True。

参数:: strings – 一个或多个待检查的字符串
返回:: 是否全部为空字符串

static is_all_not_empty(*strings: Optional[str]) → bool¶

判断给定的多个字符串是否全部不为空。

参数:: strings – 一个或多个待检查的字符串
返回:: 是否没有空字符串

static is_all_not_blank(*strings: Optional[str]) → bool¶

判断给定的多个字符串是否全部不为空白。

参数:: strings – 一个或多个待检查的字符串
返回:: 是否没有空白字符串

static is_none_or_undefined(string: Optional[str]) → bool¶

判断 string 是否为 None、""、"None" 或 "undefined"。

参数:: string – 待检查的字符串
返回:: 是否匹配哨兵值

static is_empty_or_undefined(string: Optional[str]) → bool¶

判断 string 是否为空或等于 "None" / "undefined"。

参数:: string – 待检查的字符串
返回:: 是否为空或哨兵值

static is_blank_or_undefined(string: Optional[str]) → bool¶

判断 string 是否为空白或等于 "None" / "undefined"。

参数:: string – 待检查的字符串
返回:: 是否为空白或哨兵值

static is_none_or_undefined_str(string: str) → bool¶

不做 None 检查，直接判断 string 去除空白后是否等于 "None" 或 "undefined"。

参数:: string – 待检查的字符串
返回:: 是否为 "None" 或 "undefined"

static trim(string: Optional[str], mode: int = 0, predicate: Callable[[str], bool] = CharUtil.is_blank_char) → Optional[str]¶

根据 predicate 从字符串的头部和/或尾部裁剪字符。

参数:

string – 待裁剪的字符串
mode – -1 = 仅裁剪头部，0 = 两端都裁剪，1 = 仅裁剪尾部
predicate – 返回 True 时表示该字符应被移除的函数

返回:

裁剪后的字符串，string 为 None 时返回 None

static trim_to_empty(string: Optional[str]) → str¶

裁剪两端空白。string 为 None 时返回 ""。

参数:: string – 待裁剪的字符串
返回:: 裁剪后的字符串或 ""

static trim_to_none(string: Optional[str]) → Optional[str]¶

裁剪两端空白。string 为 None 或结果为空字符串时返回 None。

参数:: string – 待裁剪的字符串
返回:: 裁剪后的字符串或 None

static trim_start(string: Optional[str]) → Optional[str]¶

仅裁剪字符串头部的空白。

参数:: string – 待裁剪的字符串
返回:: 裁剪后的字符串，string 为 None 时返回 None

static trim_end(string: Optional[str]) → Optional[str]¶

仅裁剪字符串尾部的空白。

参数:: string – 待裁剪的字符串
返回:: 裁剪后的字符串，string 为 None 时返回 None

static start_with(string: Optional[str], prefix: Optional[str], ignore_case: bool = False, ignore_equals: bool = False) → bool¶

判断 string 是否以 prefix 开头。

参数:

string – 待检查的字符串
prefix – 前缀
ignore_case – 是否忽略大小写
ignore_equals – 字符串相等时是否返回 False

返回:

是否以指定前缀开头

static start_with_ignore_equals(string: Optional[str], prefix: Optional[str]) → bool¶

判断 string 是否以 prefix 开头且不相等。

参数:

string – 待检查的字符串
prefix – 前缀

返回:

是否以指定前缀开头且两者不同

static start_with_ignore_case(string: Optional[str], prefix: Optional[str]) → bool¶

判断 string 是否以 prefix 开头，忽略大小写。

参数:

string – 待检查的字符串
prefix – 前缀

返回:

是否以指定前缀开头（不区分大小写）

static start_with_any(string: Optional[str], *prefixes: Optional[str]) → bool¶

判断 string 是否以给定的任一 prefixes 开头。

参数:

string – 待检查的字符串
prefixes – 前缀列表

返回:

是否匹配任一前缀

static start_with_any_ignore_case(string: Optional[str], *prefixes: Optional[str]) → bool¶

判断 string 是否以给定的任一 prefixes 开头，忽略大小写。

参数:

string – 待检查的字符串
prefixes – 前缀列表

返回:

是否匹配任一前缀（不区分大小写）

static end_with(string: Optional[str], suffix: Optional[str], ignore_case: bool = False, ignore_equals: bool = False) → bool¶

判断 string 是否以 suffix 结尾。

参数:

string – 待检查的字符串
suffix – 后缀
ignore_case – 是否忽略大小写
ignore_equals – 字符串相等时是否返回 False

返回:

是否以指定后缀结尾

static end_with_ignore_equals(string: Optional[str], suffix: Optional[str]) → bool¶

判断 string 是否以 suffix 结尾且不相等。

参数:

string – 待检查的字符串
suffix – 后缀

返回:

是否以指定后缀结尾且两者不同

static end_with_ignore_case(string: Optional[str], prefix: Optional[str]) → bool¶

判断 string 是否以 prefix 结尾，忽略大小写。

参数:

string – 待检查的字符串
prefix – 后缀

返回:

是否以指定后缀结尾（不区分大小写）

static end_with_any(string: Optional[str], *prefixes: Optional[str]) → bool¶

判断 string 是否以给定的任一 prefixes 结尾。

参数:

string – 待检查的字符串
prefixes – 后缀列表

返回:

是否匹配任一后缀

static end_with_any_ignore_case(string: Optional[str], *prefixes: Optional[str]) → bool¶

判断 string 是否以给定的任一 prefixes 结尾，忽略大小写。

参数:

string – 待检查的字符串
prefixes – 后缀列表

返回:

是否匹配任一后缀（不区分大小写）

static contains(string: Optional[str], search: Optional[str]) → bool¶

判断 string 是否包含 search。

参数:

string – 待搜索的字符串
search – 待查找的子串

返回:

是否包含该子串

static contains_any(string: Optional[str], *test_strings: Optional[str]) → bool¶

判断 string 是否包含给定的任一子串。

参数:

string – 待搜索的字符串
test_strings – 待查找的子串列表

返回:

是否包含任一子串

static contains_all(string: Optional[str], *test_strings: Optional[str]) → bool¶

判断 string 是否包含所有给定的子串。

参数:

string – 待搜索的字符串
test_strings – 待查找的子串列表

返回:

是否包含所有子串

static contains_blank(string: Optional[str]) → bool¶

判断 string 是否包含空白字符。 string 为 None 或空字符串时返回 False。

参数:: string – 待检查的字符串
返回:: 是否包含空白字符

static get_contains_str(string: Optional[str], *test_strings: Optional[str]) → Optional[str]¶

查找 test_strings 中第一个被 string 包含的子串。

参数:

string – 待搜索的字符串
test_strings – 待查找的子串列表

返回:

第一个匹配的子串，或 None

static contains_ignore_case(string: Optional[str], test_string: Optional[str]) → bool¶

判断 string 是否包含 test_string，忽略大小写。两者均为 None 时返回 True。

参数:

string – 待搜索的字符串
test_string – 待查找的子串

返回:

是否包含该子串（不区分大小写）

static contains_any_ignore_case(string: Optional[str], *test_strings: Optional[str]) → bool¶

判断 string 是否包含给定的任一子串，忽略大小写。

参数:

string – 待搜索的字符串
test_strings – 待查找的子串列表

返回:

是否包含任一子串（不区分大小写）

static get_contains_str_ignore_case(string: Optional[str], *test_strings: Optional[str]) → Optional[str]¶

查找 test_strings 中第一个被 string 包含的子串，忽略大小写。

参数:

string – 待搜索的字符串
test_strings – 待查找的子串列表

返回:

第一个匹配的子串，或 None

static index_of(text: Optional[str], search_string: Optional[str], start: Optional[int] = None, end: Optional[int] = None, ignore_case: bool = False) → int¶

在 text 的可选范围 [start, end) 内查找 search_string 的索引。

参数:

text – 待搜索的字符串
search_string – 待查找的子串
start – 可选的起始位置
end – 可选的结束位置
ignore_case – 是否忽略大小写

返回:

索引值，未找到时返回 -1

static index_of_ignore_case(text: Optional[str], search_string: Optional[str], start: Optional[int] = None, end: Optional[int] = None) → int¶

在 text 中查找 search_string 的索引，忽略大小写。

参数:

text – 待搜索的字符串
search_string – 待查找的子串
start – 可选的起始位置
end – 可选的结束位置

返回:

索引值，未找到时返回 -1

static last_index_of(text: Optional[str], search_string: Optional[str], start: Optional[int] = None, end: Optional[int] = None, ignore_case: bool = False) → int¶

在 text 的可选范围 [start, end) 内查找 search_string 最后一次出现的索引。

参数:

text – 待搜索的字符串
search_string – 待查找的子串
start – 可选的起始位置
end – 可选的结束位置
ignore_case – 是否忽略大小写

返回:

索引值，未找到时返回 -1

static last_index_of_ignore_case(text: Optional[str], search_string: Optional[str], start: Optional[int] = None, end: Optional[int] = None) → int¶

在 text 中查找 search_string 最后一次出现的索引，忽略大小写。

参数:

text – 待搜索的字符串
search_string – 待查找的子串
start – 可选的起始位置
end – 可选的结束位置

返回:

索引值，未找到时返回 -1

static ordinal_index_of(text: Optional[str], search_string: Optional[str], ordinal: int) → int¶

返回 search_string 在 text 中第 ordinal 次出现的索引。

参数:

text – 待搜索的字符串
search_string – 待查找的子串
ordinal – 出现次数（从1开始）

返回:

索引值，未找到时返回 -1

static remove_all(string: Optional[str], string_to_remove: Optional[str]) → Optional[str]¶

从 string 中移除所有 string_to_remove 的出现。

参数:

string – 源字符串
string_to_remove – 待移除的子串

返回:

移除后的字符串

static remove_any(string: Optional[str], *strings_to_remove: Optional[str]) → Optional[str]¶

从 string 中移除 strings_to_remove 中每个子串的所有出现。

参数:

string – 源字符串
strings_to_remove – 待移除的子串列表

返回:

移除后的字符串

static remove_all_line_breaks(string: Optional[str]) → Optional[str]¶

从 string 中移除所有换行符（\r 和 \n）。

参数:: string – 源字符串
返回:: 不含换行符的字符串

static remove_pre_and_lower_first(string: Optional[str], pre_or_length: Union[int, str]) → Optional[str]¶

从 string 中移除前缀，并将剩余字符串的首字母小写。

参数:

string – 源字符串
pre_or_length – 要移除的前缀字符串，或从头部移除的字符数

返回:

处理后的字符串，string 为 None 时返回 None

static remove_prefix(string: Optional[str], prefix: Optional[str]) → Optional[str]¶

如果 string 以 prefix 开头则移除该前缀。

参数:

string – 源字符串
prefix – 待移除的前缀

返回:

移除前缀后的字符串

static remove_prefix_ignore_case(string: Optional[str], prefix: Optional[str]) → Optional[str]¶

如果 string 以 prefix 开头则移除该前缀（忽略大小写）。

参数:

string – 源字符串
prefix – 待移除的前缀

返回:

移除前缀后的字符串

static remove_suffix(string: Optional[str], suffix: Optional[str]) → Optional[str]¶

如果 string 以 suffix 结尾则移除该后缀。

参数:

string – 源字符串
suffix – 待移除的后缀

返回:

移除后缀后的字符串

static remove_suffix_and_lower_first(string: Optional[str], suffix: Optional[str]) → Optional[str]¶

从 string 中移除后缀并将首字母小写。

参数:

string – 源字符串
suffix – 待移除的后缀

返回:

处理后的字符串

static remove_suffix_ignore_case(string: Optional[str], suffix: Optional[str]) → Optional[str]¶

如果 string 以 suffix 结尾则移除该后缀（忽略大小写）。

参数:

string – 源字符串
suffix – 待移除的后缀

返回:

移除后缀后的字符串

static clean_blank(string: Optional[str]) → Optional[str]¶

移除 string 中的所有空白字符。

参数:: string – 源字符串
返回:: 不含空白字符的字符串

static strip(string: Optional[str], prefix: str, suffix: Optional[str] = None) → Optional[str]¶

从 string 头部去除 prefix，尾部去除 suffix。若 suffix 为 None，则两端均去除 prefix。

参数:

string – 源字符串
prefix – 待去除的前缀
suffix – 待去除的后缀（默认为 prefix）

返回:

去除后的字符串

static strip_ignore_case(string: Optional[str], prefix: str, suffix: Optional[str] = None) → Optional[str]¶

从 string 头部去除 prefix，尾部去除 suffix，忽略大小写。

参数:

string – 源字符串
prefix – 待去除的前缀
suffix – 待去除的后缀（默认为 prefix）

返回:

去除后的字符串

static add_prefix_if_not(string: Optional[str], prefix: Optional[str]) → Optional[str]¶

如果 string 不以 prefix 开头则添加该前缀。

参数:

string – 源字符串
prefix – 待添加的前缀

返回:

确保有前缀的字符串

static add_suffix_if_not(string: Optional[str], suffix: Optional[str]) → Optional[str]¶

如果 string 不以 suffix 结尾则添加该后缀。

参数:

string – 源字符串
suffix – 待添加的后缀

返回:

确保有后缀的字符串

static cut(string: Optional[str], part_length: int) → List[str]¶

将 string 按 part_length 个字符一组进行分割。

参数:

string – 源字符串
part_length – 每组的长度

返回:

分割后的字符串列表

static equals(string1: Optional[str], string2: Optional[str], ignore_case: bool = False) → bool¶

比较两个字符串是否相等。

参数:

string1 – 第一个字符串
string2 – 第二个字符串
ignore_case – 是否忽略大小写

返回:

两个字符串是否相等（或均为 None）

static equals_ignore_case(string1: Optional[str], string2: Optional[str]) → bool¶

比较两个字符串是否相等，忽略大小写。

参数:

string1 – 第一个字符串
string2 – 第二个字符串

返回:

两个字符串是否相等（不区分大小写）

static append_if_missing(string: Optional[str], suffix: Optional[str], *suffixes: Optional[str], ignore_case: bool = False) → Optional[str]¶

如果 string 不以指定后缀结尾，则追加 suffix。

参数:

string – 源字符串
suffix – 待追加的后缀
suffixes – 额外的待检查后缀
ignore_case – 检查时是否忽略大小写

返回:

确保有后缀的字符串

static append_if_missing_ignore_case(string: Optional[str], suffix: Optional[str], *suffixes: Optional[str]) → Optional[str]¶

如果 string 不以 suffix 结尾则追加（忽略大小写）。

参数:

string – 源字符串
suffix – 待追加的后缀
suffixes – 额外的待检查后缀

返回:

确保有后缀的字符串

static prepend_if_missing(string: Optional[str], prefix: Optional[str], *prefixes: Optional[str], ignore_case: bool = False) → Optional[str]¶

如果 string 不以指定前缀开头，则前置 prefix。

参数:

string – 源字符串
prefix – 待前置的前缀
prefixes – 额外的待检查前缀
ignore_case – 检查时是否忽略大小写

返回:

确保有前缀的字符串

static prepend_if_missing_ignore_case(string: Optional[str], prefix: Optional[str], *prefixes: Optional[str]) → Optional[str]¶

如果 string 不以 prefix 开头则前置（忽略大小写）。

参数:

string – 源字符串
prefix – 待前置的前缀
prefixes – 额外的待检查前缀

返回:

确保有前缀的字符串

static upper_first_and_add_pre(string: Optional[str], pre_string: Optional[str]) → Optional[str]¶

将 string 首字母大写并前置 pre_string。

参数:

string – 源字符串
pre_string – 待前置的前缀

返回:

处理后的字符串，任一参数为 None 时返回 None

static upper_first(string: Optional[str]) → Optional[str]¶

将 string 的首字母大写。

参数:: string – 源字符串
返回:: 首字母大写后的字符串

static lower_first(string: Optional[str]) → Optional[str]¶

将 string 的首字母小写。

参数:: string – 源字符串
返回:: 首字母小写后的字符串

static filter(string: Optional[str], filter_func: Callable[[str], bool]) → Optional[str]¶

使用 filter_func 过滤 string 中的字符。仅保留 filter_func 返回 True 的字符。

参数:

string – 源字符串
filter_func – 过滤函数

返回:

过滤后的字符串

static sub_suf(string: Optional[str], from_index: int) → Optional[str]¶

返回从 from_index 到末尾的子串。

参数:

string – 源字符串
from_index – 起始索引（包含）

返回:

子串，string 为 None 时返回 None

static sub_pre(string: Optional[str], to_index: int) → Optional[str]¶

返回从开头到末尾减去 to_index 个字符处的子串。

参数:

string – 源字符串
to_index – 从末尾排除的字符数

返回:

子串，string 为 None 时返回 None

static sub(string: Optional[str], start: int, end: Optional[int] = None) → Optional[str]¶

提取子串，支持从末尾开始计数的负索引（类似 Python 切片）。

参数:

string – 源字符串
start – 起始索引（包含）。负值表示从末尾开始计数。
end – 结束索引（不包含）。负值表示从末尾开始计数。为 None 时返回到字符串末尾。

返回:

子串，string 为 None 时返回 None

static sub_before(string: Optional[str], separator: str, is_last: bool = False) → Optional[str]¶

返回第一个（或最后一个）*separator* 出现之前的子串。

未找到 separator 时返回整个字符串。

参数:

string – 源字符串
separator – 分隔符字符串
is_last – 是否使用最后一个分隔符

返回:

分隔符之前的子串

static sub_after(string: Optional[str], separator: str, is_last: bool = False) → Optional[str]¶

返回第一个（或最后一个）*separator* 出现之后的子串。

未找到 separator 时返回整个字符串。

参数:

string – 源字符串
separator – 分隔符字符串
is_last – 是否使用最后一个分隔符

返回:

分隔符之后的子串

static sub_between(string: Optional[str], prefix: str, suffix: str) → Optional[str]¶

返回 string 中第一个 prefix 之后、下一个 suffix 之前的文本。

string 为 None/空，或找不到 prefix/suffix 时返回 None。

参数:

string – 源字符串
prefix – 前标记
suffix – 后标记

返回:

prefix 和 suffix 之间的文本，或 None

static sub_between_all(string: Optional[str], prefix: str, suffix: str) → List[str]¶

返回 string 中所有 prefix 和 suffix 之间的不重叠子串。

参数:

string – 源字符串
prefix – 前标记
suffix – 后标记

返回:

prefix 和 suffix 之间的子串列表

static count(string: Optional[str], char_or_start: str, end: Optional[str] = None) → int¶

统计字符或子串的出现次数。

两种调用方式（与 Java Hutool 对齐）：

count(str, char) – 统计 char 在 str 中出现的次数。
count(str, start, end) – 统计 str 中 start 和 end 标记之间的子串数量。

参数:

string – 源字符串
char_or_start – 待统计的字符/子串，或当提供 end 时作为起始标记
end – 结束标记。提供时 char_or_start 视为起始标记

返回:

统计次数

static replace(string: Optional[str], search_str: str, replacement: str, count: int = -1) → Optional[str]¶

将 string 中的 search_str 替换为 replacement。

参数:

string – 源字符串
search_str – 待查找的字符串
replacement – 替换字符串
count – 最大替换次数。-1 表示全部替换（默认）

返回:

替换后的字符串

static replace_chars(string: Optional[str], chars: str, replacement: str) → Optional[str]¶

将 string 中出现在 chars 里的每个字符替换为 replacement。

参数:

string – 源字符串
chars – 包含待替换字符的字符串
replacement – 每个匹配字符的替换字符串

返回:

替换后的字符串

static replace_first(string: Optional[str], search_str: str, replacement: str, ignore_case: bool = False) → Optional[str]¶

替换 string 中 search_str 的第一个匹配项为 replacement。

注意：search_str 视为字面量（非正则表达式）。

参数:

string – 源字符串
search_str – 待替换的字面量字符串
replacement – 替换字符串
ignore_case – 是否忽略大小写，默认 False

返回:

替换后的字符串

static replace_all(string: Optional[str], regex: str, replacement: str) → Optional[str]¶

替换 string 中 regex 的所有匹配项为 replacement。

参数:

string – 源字符串
regex – 正则表达式模式
replacement – 替换字符串（可包含反向引用如 \1）

返回:

替换所有正则匹配后的字符串

static join(sep: str, *args: Any) → str¶

将 args 用 sep 连接成一个字符串。

每个元素通过 str() 转换为字符串。None 值表示为 ""。

参数:

sep – 分隔符
args – 待连接的值

返回:

连接后的字符串

static join_array(array: list, conjunction: str) → str¶

将 array 的元素用 conjunction 连接成一个字符串。

参数:

array – 待连接的值列表
conjunction – 分隔符

返回:

连接后的字符串

static split(string: Optional[str], separator: str, limit: int = -1, is_trim: bool = False, ignore_empty: bool = False) → List[str]¶

按 separator 分割 string，支持可选的裁剪和空元素移除。

参数:

string – 源字符串
separator – 分隔符字符串
limit – 最大分割份数（类似 str.split(sep, n)）。-1 表示不限制
is_trim – 是否裁剪每个部分
ignore_empty – 是否移除空部分

返回:

分割后的字符串列表

static pad(string: Optional[str], size: int, pad_str: str = ' ', is_right: bool = True) → str¶

使用 pad_str 将 string 填充到 size 个字符。

如果字符串已经至少 size 个字符，则原样返回。

参数:

string – 源字符串
size – 目标长度
pad_str – 填充字符串（默认 " "）
is_right – True = 右侧填充（左对齐），False = 左侧填充（右对齐）

返回:

填充后的字符串

static center(string: Optional[str], size: int, pad_str: str = ' ') → str¶

使用 pad_str 将 string 居中对齐到 size 个字符。

支持多字符 pad_str。如果 size 小于字符串长度，返回原字符串。

Examples:

CharSequenceUtil.center("a", 4, "yz")   # "yazy"
CharSequenceUtil.center("abc", 7, " ")    # "  abc  "
CharSequenceUtil.center("ab", 4, " ")     # " ab "

参数:

string – 源字符串
size – 目标长度
pad_str – 填充字符串（默认 " "）

返回:

居中对齐后的字符串

static repeat(string: Optional[str], count: int) → str¶

将 string 重复 count 次。

参数:

string – 待重复的字符串
count – 重复次数

返回:

重复后的字符串

static repeat_and_join(string: Optional[str], count: int, conjunction: str) → str¶

将 string 重复 count 次，每次重复之间用 conjunction 连接。

参数:

string – 待重复的字符串
count – 重复次数
conjunction – 重复之间的分隔符

返回:

重复并连接后的字符串

static to_camel_case(string: Optional[str]) → Optional[str]¶

将字符串转换为 camelCase（驼峰命名法）。

支持 snake_case、kebab-case 和空格分隔的输入。

Examples:

"hello_world"  -> "helloWorld"
"hello-world"  -> "helloWorld"
"HELLO_WORLD"  -> "helloWorld"

参数:: string – 源字符串
返回:: 驼峰命名的字符串

static to_snake_case(string: Optional[str]) → Optional[str]¶

将字符串转换为 snake_case（蛇形命名法）。

支持 camelCase、PascalCase、kebab-case 和空格分隔的输入。

Examples:

"helloWorld"   -> "hello_world"
"HelloWorld"   -> "hello_world"
"hello-world"  -> "hello_world"

参数:: string – 源字符串
返回:: 蛇形命名的字符串

static to_under_score_case(string: Optional[str]) → Optional[str]¶

to_snake_case() 的别名。

参数:: string – 源字符串
返回:: 蛇形命名的字符串

static similar(str1: Optional[str], str2: Optional[str], is_ignore_case: bool = False) → float¶

使用 Python 的 difflib.SequenceMatcher 计算两个字符串的相似度。返回 [0.0, 1.0] 之间的浮点数。

参数:

str1 – 第一个字符串
str2 – 第二个字符串
is_ignore_case – 是否忽略大小写

返回:

相似度比率（0.0 到 1.0）

static format_with_map(template: str, map_: dict, ignore_null: bool = False) → str¶

通过将 {key} 占位符替换为 map_ 中的值来格式化 template。

如果 ignore_null 为 False 且键不存在，占位符保持不变。如果 ignore_null 为 True，缺失的键将被替换为空字符串。

参数:

template – 包含 {key} 占位符的模板字符串
map – 映射键到替换值的字典
ignore_null – 为 True 时，缺失的键替换为 ""

返回:

格式化后的字符串

static is_numeric(string: Optional[str]) → bool¶

判断 string 是否全部由数字字符组成。允许前导 - 号（与 Java Hutool 的 StrUtil.isNumeric 对齐）。

参数:: string – 待检查的字符串
返回:: 是否为数字字符串

static is_number(string: Optional[str]) → bool¶

判断 string 是否表示有效的数字（整数或浮点数）。

参数:: string – 待检查的字符串
返回:: 是否为有效数字

static is_alpha(string: Optional[str]) → bool¶

判断 string 是否全部由字母组成。

参数:: string – 待检查的字符串
返回:: 是否全部为字母

static is_alpha_upper(string: Optional[str]) → bool¶

判断 string 是否全部由大写字母组成。

参数:: string – 待检查的字符串
返回:: 是否全部为大写字母

static is_alpha_lower(string: Optional[str]) → bool¶

判断 string 是否全部由小写字母组成。

参数:: string – 待检查的字符串
返回:: 是否全部为小写字母

static only_digits(string: Optional[str]) → Optional[str]¶

移除字符串中所有非数字字符，仅保留数字。

参数:: string – 源字符串
返回:: 仅包含数字的字符串，输入为 None 时返回 None

static de_umlaut(text: str) → str¶

将德语变音符号（äöüß等）转换为 ASCII 等价形式。

例如 ä → ae，ö → oe，ü → ue，ß → ss。

参数:: text – 包含德语变音符号的文本
返回:: 转换后的 ASCII 文本
抛出:: ValueError – 文本无法转换为 ASCII 时

static full_to_half_width(text: str) → str¶

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

仅转换 ASCII 可见字符范围（0x21~0x7E）和全角空格（0x3000）。

Examples:

"ＨｅｌｌｏＷｏｒｌｄ" -> "HelloWorld"
"１２３" -> "123"

参数:: text – 包含全角字符的文本
返回:: 转换后的半角文本

static half_to_full_width(text: str) → str¶

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

仅转换 ASCII 可见字符范围（0x21~0x7E）和空格（0x20）。

Examples:

"Hello" -> "Ｈｅｌｌｏ"
"123" -> "１２３"

参数:: text – 包含半角字符的文本
返回:: 转换后的全角文本

static levenshtein_distance(s: str, t: str) → int¶

计算两个字符串的 Levenshtein 编辑距离。

编辑距离是指将一个字符串变换为另一个字符串所需的最少单字符编辑（插入、删除、替换）操作数。

参数:

s – 第一个字符串
t – 第二个字符串

返回:

编辑距离（非负整数）

static filter_chinese(text: str) → str¶

移除字符串中的所有中文字符（Unicode 范围 \u4e00-\u9fa5）。

参数:: text – 源字符串
返回:: 移除中文字符后的字符串

static filter_chinese_punctuations(text: str) → str¶

移除字符串中的中英文标点符号和多余空白。

移除范围包括：英文标点 !@#$%^&*() 等，中文标点 ！，。？、（）：；《》"" 等，以及制表符。

参数:: text – 源字符串
返回:: 移除标点后的字符串

static left_space_count(text: str) → int¶

计算字符串前导空白字符数。

空格计 1，Tab 计 4。

参数:: text – 待检查的字符串
返回:: 前导空白字符数（等效空格数）

>>> StrUtil.left_space_count('  hello')
2
>>> StrUtil.left_space_count('\thello')
4

static find_all_indices(text: str, sub: str) → List[int]¶

查找子串在文本中所有出现的起始索引。

无匹配时返回空列表。

参数:

text – 待搜索的文本
sub – 待查找的子串

返回:

起始索引列表

>>> StrUtil.find_all_indices('abcabc', 'b')
[1, 4]
>>> StrUtil.find_all_indices('abcabc', 'x')
[]

static equals_any(string: Optional[str], *candidates: Optional[str]) → bool¶

判断 string 是否等于候选中的任一个。

参数:

string – 待比较的字符串
candidates – 候选字符串

返回:

匹配任一候选返回 True

static equals_any_ignore_case(string: Optional[str], *candidates: Optional[str]) → bool¶

判断 string 是否等于候选中的任一个（忽略大小写）。

参数:

string – 待比较的字符串
candidates – 候选字符串

返回:

匹配任一候选返回 True

static equals_char_at(string: Optional[str], index: int, char: str) → bool¶

判断 string 的第 index 个字符是否为 char。

参数:

string – 待检查的字符串
index – 字符索引
char – 期望的字符

返回:

是否匹配

static contains_only(string: Optional[str], chars: str) → bool¶

判断 string 是否全部由 chars 中的字符组成。

参数:

string – 待检查的字符串
chars – 允许的字符集

返回:

是否全部由指定字符组成

static has_letter(string: Optional[str]) → bool¶

判断 string 是否包含至少一个字母。

参数:: string – 待检查的字符串
返回:: 是否包含字母

static is_sub_equals(string: Optional[str], sub: Optional[str], from_index: int = 0, ignore_case: bool = False) → bool¶

判断从 from_index 开始的子串是否等于 sub。

参数:

string – 待检查的字符串
sub – 期望的子串
from_index – 起始索引
ignore_case – 是否忽略大小写

返回:

是否匹配

static is_surround(string: Optional[str], prefix: str, suffix: str) → bool¶

判断 string 是否以 prefix 开头且以 suffix 结尾。

参数:

string – 待检查的字符串
prefix – 前缀
suffix – 后缀

返回:

是否包裹

static is_wrap(string: Optional[str], wrap: str) → bool¶

判断 string 是否被 wrap 包裹（前后相同）。

参数:

string – 待检查的字符串
wrap – 包裹字符/串

返回:

是否被包裹

static is_lower_case(string: Optional[str]) → bool¶

判断 string 是否全部为小写（至少一个字母）。

参数:: string – 待检查的字符串
返回:: 是否全小写

static is_upper_case(string: Optional[str]) → bool¶

判断 string 是否全部为大写（至少一个字母）。

参数:: string – 待检查的字符串
返回:: 是否全大写

static is_all_char_match(string: Optional[str], match_func: Callable[[str], bool]) → bool¶

判断 string 的所有字符是否都满足 match_func。

参数:

string – 待检查的字符串
match_func – 匹配函数

返回:

是否全部匹配

static common_prefix(*strings: Optional[str]) → str¶

返回多个字符串的最长公共前缀。

参数:: strings – 字符串列表
返回:: 公共前缀

static common_suffix(*strings: Optional[str]) → str¶

返回多个字符串的最长公共后缀。

参数:: strings – 字符串列表
返回:: 公共后缀

static compare(string1: Optional[str], string2: Optional[str], null_is_greater: bool = False) → int¶

null-safe 的字符串比较。

参数:

string1 – 字符串1
string2 – 字符串2
null_is_greater – None 是否视为更大

返回:

负数/0/正数

static compare_ignore_case(string1: Optional[str], string2: Optional[str], null_is_greater: bool = False) → int¶

null-safe 忽略大小写的字符串比较。

参数:

string1 – 字符串1
string2 – 字符串2
null_is_greater – None 是否视为更大

返回:

负数/0/正数

static concat(*strings: Optional[str]) → str¶

拼接多个字符串，None 视为空串。

参数:: strings – 字符串列表
返回:: 拼接结果

static brief(string: Optional[str], max_length: int) → Optional[str]¶

截断 string 到 max_length，超出部分用 ... 替代。总长度不超过 max_length。

参数:

string – 待截断的字符串
max_length – 最大总长度（含省略号）

返回:

截断后的字符串

static max_length(string: Optional[str], max_length: int) → Optional[str]¶

截断 string 到 max_length 长度，超出时追加 "..."。

总长度恰好为 max_length （含后缀 "..."）。与 Java Hutool 行为一致。

参数:

string – 待截断的字符串
max_length – 最大长度（含后缀）

返回:

截断后的字符串

抛出:

ValueError – max_length 小于等于 0 时

static fix_length(string: Optional[str], fixed_length: int, pad_char: str = ' ') → str¶

将 string 填充或截断到 fixed_length。

长度不足时右侧用 pad_char 填充
长度超出时截断

参数:

string – 待处理的字符串
fixed_length – 固定长度
pad_char – 填充字符

返回:

固定长度的字符串

static hide(string: Optional[str], start: int, end: int) → Optional[str]¶

隐藏 string 中 start 到 end 索引的字符，用 * 替代。

参数:

string – 待处理的字符串
start – 起始索引（含）
end – 结束索引（不含）

返回:

隐藏后的字符串

static move(string: Optional[str], start: int, end: int, move_length: int) → Optional[str]¶

移动 string 中 start 到 end 区间的字符 move_length 位。正数右移，负数左移。

参数:

string – 待处理的字符串
start – 起始索引（含）
end – 结束索引（不含）
move_length – 移动长度

返回:

移动后的字符串

static normalize(string: Optional[str]) → Optional[str]¶

合并连续空白为单个空格，并去除首尾空白。

参数:: string – 待规范化的字符串
返回:: 规范化后的字符串

static total_length(*strings: Optional[str]) → int¶

计算多个字符串的总长度。

参数:: strings – 字符串列表
返回:: 总长度

static indexed_format(template: str, *args: Any) → str¶

使用索引格式化模板，如 "{0} + {1} = {2}"。

参数:

template – 模板字符串
args – 位置参数

返回:

格式化后的字符串

static wrap(string: Optional[str], prefix: str, suffix: Optional[str] = None) → Optional[str]¶

包裹 string。如果只传一个包裹参数，前后相同。

参数:

string – 待包裹的字符串
prefix – 前缀
suffix – 后缀（默认同前缀）

返回:

包裹后的字符串

static wrap_if_missing(string: Optional[str], prefix: str, suffix: Optional[str] = None) → Optional[str]¶

仅在缺失时包裹 string。

参数:

string – 待检查的字符串
prefix – 前缀
suffix – 后缀（默认同前缀）

返回:

包裹后的字符串

static wrap_all(arr: Optional[list], prefix: str, suffix: Optional[str] = None) → Optional[list]¶

包裹列表中每个元素。

参数:

arr – 字符串列表
prefix – 前缀
suffix – 后缀（默认同前缀）

返回:

包裹后的列表

static wrap_all_if_missing(arr: Optional[list], prefix: str, suffix: Optional[str] = None) → Optional[list]¶

仅在缺失时包裹列表中每个元素。

参数:

arr – 字符串列表
prefix – 前缀
suffix – 后缀（默认同前缀）

返回:

包裹后的列表

static pad_after(string: Optional[str], length: int, pad_str: str = ' ') → Optional[str]¶

右填充 string 到 length。

支持多字符 pad_str。

参数:

string – 待填充的字符串
length – 目标长度
pad_str – 填充字符串

返回:

填充后的字符串

static pad_pre(string: Optional[str], length: int, pad_str: str = ' ') → Optional[str]¶

左填充 string 到 length。

支持多字符 pad_str。

参数:

string – 待填充的字符串
length – 目标长度
pad_str – 填充字符串

返回:

填充后的字符串

static _repeat_pad(pad_str: str, count: int) → str¶

重复 pad_str 直到达到 count 个字符（截取前 count 个字符）。

参数:

pad_str – 填充字符串
count – 目标字符数

返回:

填充字符串

static repeat_by_length(string: Optional[str], length: int) → Optional[str]¶

重复 string 直到达到 length 长度（截断多余部分）。

参数:

string – 待重复的字符串
length – 目标长度

返回:

重复后的字符串

static replace_ignore_case(string: Optional[str], search_str: str, replacement: str) → Optional[str]¶

忽略大小写替换所有匹配。

参数:

string – 待处理的字符串
search_str – 搜索字符串
replacement – 替换字符串

返回:

替换后的字符串

static replace_last(string: Optional[str], search_str: str, replacement: str, ignore_case: bool = False) → Optional[str]¶

替换 string 中 search_str 的最后一个匹配项为 replacement。

注意：search_str 视为字面量（非正则表达式）。

参数:

string – 待处理的字符串
search_str – 待替换的字面量字符串
replacement – 替换字符串
ignore_case – 是否忽略大小写，默认 False

返回:

替换后的字符串

static remove_all_prefix(string: Optional[str], prefix: Optional[str]) → Optional[str]¶

移除所有匹配的前缀（循环移除）。

参数:

string – 待处理的字符串
prefix – 前缀

返回:

移除前缀后的字符串

static remove_all_suffix(string: Optional[str], suffix: Optional[str]) → Optional[str]¶

移除所有匹配的后缀（循环移除）。

参数:

string – 待处理的字符串
suffix – 后缀

返回:

移除后缀后的字符串

static remove_suf_and_lower_first(string: Optional[str], suffix: Optional[str]) → Optional[str]¶

移除后缀并将首字母转为小写。

参数:

string – 待处理的字符串
suffix – 后缀

返回:

处理后的字符串

static split_trim(string: Optional[str], separator: str = ',') → List[str]¶

按 separator 分割 string 并 trim 每一部分。

参数:

string – 待分割的字符串
separator – 分隔符

返回:

分割并 trim 后的列表

static strip_all(*strings: Optional[str]) → List[Optional[str]]¶

对多个字符串执行 strip。

参数:: strings – 字符串列表
返回:: strip 后的列表

static swap_case(string: Optional[str]) → Optional[str]¶

大小写互转。

参数:: string – 待转换的字符串
返回:: 转换后的字符串

static to_symbol_case(string: Optional[str], symbol: str = '-') → Optional[str]¶

将驼峰命名转换为符号分隔命名（如 kebab-case）。

参数:

string – 待转换的字符串
symbol – 分隔符号

返回:

转换后的字符串

static trim_to_null(string: Optional[str]) → Optional[str]¶

trim 后如果为空返回 None。

参数:: string – 待处理的字符串
返回:: trim 后的字符串或 None

static empty_if_null(string: Optional[str]) → str¶

如果 string 为 None，返回空串。与 empty_if_none() 相同。

参数:: string – 待检查的字符串
返回:: 非 None 的字符串

static desensitized(string: Optional[str], start_len: int, end_len: int) → Optional[str]¶

脱敏：保留前 start_len 和后 end_len 个字符，中间用 * 替代。

参数:

string – 待脱敏的字符串
start_len – 前面保留的长度
end_len – 后面保留的长度

返回:

脱敏后的字符串

static compare_version(version1: Optional[str], version2: Optional[str]) → int¶

比较两个版本号字符串（如 “1.2.3” vs “1.2.4”）。

参数:

version1 – 版本号1
version2 – 版本号2

返回:

负数/0/正数

static sub_by_code_point(string: Optional[str], start: int, end: int) → Optional[str]¶

按 Unicode 码点截取子串（支持 emoji 等多码单元字符）。

参数:

string – 源字符串
start – 起始码点索引（含）
end – 结束码点索引（不含）

返回:

截取的子串

static sub_suf_by_length(string: Optional[str], length: int) → Optional[str]¶

取最后 length 个字符。

参数:

string – 源字符串
length – 期望长度

返回:

最后的 length 个字符

static sub_with_length(string: Optional[str], start: int, length: int) → Optional[str]¶

从 start 位置开始取 length 个字符。

参数:

string – 源字符串
start – 起始位置
length – 期望长度

返回:

子串

static sub_pre_gbk(string: Optional[str], max_bytes: int) → Optional[str]¶

按 GBK 字节长度截断字符串（中文算 2 字节，ASCII 算 1 字节）。

参数:

string – 源字符串
max_bytes – 最大字节数

返回:

截断后的字符串

static reverse_by_code_point(string: Optional[str]) → Optional[str]¶

按码点反转字符串（emoji 安全）。

参数:: string – 源字符串
返回:: 反转后的字符串

static byte_length(string: Optional[str], charset: str = 'utf-8') → int¶

获取字符串在指定编码下的字节长度。

参数:

string – 源字符串
charset – 编码名称，默认 "utf-8"

返回:

字节长度

static length(string: Optional[str]) → int¶

获取字符串长度，None 返回 0。

参数:: string – 源字符串
返回:: 字符串长度

static split_to_long(string: Optional[str], separator: str = ',') → List[int]¶

分割字符串为 long（int）数组。

参数:

string – 源字符串
separator – 分隔符，默认 ,

返回:

int 列表

static split_to_int(string: Optional[str], separator: str = ',') → List[int]¶

分割字符串为 int 数组（split_to_long 的别名）。

参数:

string – 源字符串
separator – 分隔符

返回:

int 列表

static split_by_length(string: Optional[str], length: int) → List[str]¶

按固定长度分割字符串。

参数:

string – 源字符串
length – 每段长度

返回:

分割后的字符串列表

static split_ignore_case(string: Optional[str], separator: str) → List[str]¶

忽略大小写分割字符串。

参数:

string – 源字符串
separator – 分隔符（忽略大小写匹配）

返回:

分割后的字符串列表

static replace_from(string: Optional[str], start: int, search_str: str, replacement: str, ignore_case: bool = False) → Optional[str]¶

从 start 位置开始搜索并替换第一个 search_str。

参数:

string – 源字符串
start – 起始搜索位置
search_str – 待搜索的字符串
replacement – 替换字符串
ignore_case – 是否忽略大小写

返回:

替换后的字符串

static to_lower_case(string: Optional[str]) → Optional[str]¶

转为小写，None 安全。

参数:: string – 源字符串
返回:: 小写字符串

static to_upper_case(string: Optional[str]) → Optional[str]¶

转为大写，None 安全。

参数:: string – 源字符串
返回:: 大写字符串

static first_non_null(*values: Optional[str]) → Optional[str]¶

返回第一个非 None 的值。

参数:: values – 候选值
返回:: 第一个非 None 值，全部为 None 则返回 None

static first_non_empty(*values: Optional[str]) → Optional[str]¶

返回第一个非空（非 None 且非 ""）的值。

参数:: values – 候选值
返回:: 第一个非空值

static first_non_blank(*values: Optional[str]) → Optional[str]¶

返回第一个非空白（非 None 且非纯空白）的值。

参数:: values – 候选值
返回:: 第一个非空白值

static unwrap(string: Optional[str], prefix: str, suffix: str) → Optional[str]¶

移除字符串的前缀和后缀（如果存在）。

参数:

string – 源字符串
prefix – 前缀
suffix – 后缀

返回:

移除包裹后的字符串

static is_char_equals(string: Optional[str]) → bool¶

检查字符串中所有字符是否相同。

参数:: string – 源字符串
返回:: 所有字符相同或为空时返回 True

static to_string(obj: Any) → str¶

将对象转为字符串，None 返回 "null"。

参数:: obj – 对象
返回:: 字符串表示

class hutool.core.util.strings.StrPool¶

Bases: hutool.core.util.strings.CharPool

常用字符串常量。

NONE: str = 'None'¶

DOUBLE_DOT: str = '..'¶

CRLF: str = '\r\n'¶

HTML_NBSP: str = ' '¶

HTML_AMP: str = '&'¶

HTML_QUOTE: str = '"'¶

HTML_APOS: str = '''¶

HTML_LT: str = '<'¶

HTML_GT: str = '>'¶

EMPTY_JSON: str = '{}'¶

class hutool.core.util.strings.StrUtil¶

Bases: hutool.core.util.strings.CharSequenceUtil, hutool.core.util.strings.StrPool

主字符串工具类。继承 CharSequenceUtil 和 StrPool，提供所有字符串操作的统一入口。

static is_blank_if_str(obj: Any) → bool¶

如果 obj 是字符串，判断其是否为空白。非字符串对象返回 False（None 返回 True）。

参数:: obj – 待检查的对象
返回:: obj 为 None 或为空白字符串时返回 True

static is_empty_if_str(obj: Any) → bool¶

如果 obj 是字符串，判断其是否为空。非字符串对象返回 False（None 返回 True）。

参数:: obj – 待检查的对象
返回:: obj 为 None 或为空字符串时返回 True

static trim(string: Union[List[str], str, None], mode: int = 0, predicate: Callable[[str], bool] = CharUtil.is_blank_char) → Union[str, None]¶

裁剪字符串，或就地裁剪字符串列表中的每个元素。

参数:

string – 字符串或字符串列表
mode – -1 = 仅裁剪头部，0 = 两端裁剪，1 = 仅裁剪尾部
predicate – 返回 True 时表示该字符应被移除的函数

返回:

裁剪后的字符串或 None

static to_str(obj: Any, charset: str = 'utf-8') → Optional[str]¶

将 obj 转换为字符串。

bytes/bytearray/array.array 使用 charset 解码。列表会递归转换。

参数:

obj – 待转换的对象
charset – 字符编码

返回:

字符串表示

static to_str_or_none(obj: Any) → Optional[str]¶

将 obj 转换为字符串，None 输入返回 None。

参数:: obj – 待转换的对象
返回:: 字符串表示或 None

static reverse(string: Optional[str]) → Optional[str]¶

反转 string。

参数:: string – 待反转的字符串
返回:: 反转后的字符串

static fill_before(string: Optional[str], filled_char: str, length: int) → Optional[str]¶

使用 filled_char 将 string 左侧填充到 length。

参数:

string – 待填充的字符串
filled_char – 单个填充字符
length – 目标长度

返回:

填充后的字符串

static fill_after(string: Optional[str], filled_char: str, length: int) → Optional[str]¶

使用 filled_char 将 string 右侧填充到 length。

参数:

string – 待填充的字符串
filled_char – 单个填充字符
length – 目标长度

返回:

填充后的字符串

static fill(string: Optional[str], filled_char: str, length: int, is_pre: bool) → Optional[str]¶

使用 filled_char 将 string 填充到 length，可选择左侧填充（is_pre=True）或右侧填充（is_pre=False）。

参数:

string – 待填充的字符串
filled_char – 单个填充字符
length – 目标长度
is_pre – 是否左侧填充

返回:

填充后的字符串

抛出:

TypeError – filled_char 不是单个字符时抛出异常

static format(template: str, *args: Any, **kwargs: Any) → str¶

使用 Python 的 str.format() 格式化 template。

参数:

template – 模板字符串
args – 位置参数
kwargs – 关键字参数

返回:

格式化后的字符串

static truncate_utf8(string: Optional[str], max_bytes: int) → Optional[str]¶

截断 string 使其 UTF-8 编码不超过 max_bytes。截断时会附加省略号（...）。

参数:

string – 待截断的字符串
max_bytes – 最大字节长度

返回:

截断后的字符串

static truncate_by_byte_length(string: Optional[str], charset: str, max_bytes: int, factor: int, append_dots: bool) → Optional[str]¶

截断 string 使其编码字节长度不超过 max_bytes。

factor 是速度估计除数（编码中单个字符的最大字节长度）。

参数:

string – 待截断的字符串
charset – 字符编码
max_bytes – 最大字节长度
factor – 速度估计除数
append_dots – 截断后是否附加 ...

返回:

截断后的字符串

static shrink_repeated(s: Optional[str], replacement: str = '') → Optional[str]¶

压缩连续重复字符。

例如 "aaa" → "a"，"aabb" → "ab"。当 replacement 为空字符串时，去除重复只保留一个；否则用替换串替代重复部分。

参数:

s – 待处理的字符串
replacement – 重复部分的替换值，默认 "" （去除重复）

返回:

压缩后的字符串

static sub_chinese_punctuations(s: Optional[str]) → Optional[str]¶

将中文标点替换为英文标点。

替换范围：，。？！；：””’’（）【】《》、

参数:: s – 待处理的字符串
返回:: 替换后的字符串

hutool.core.util.strings¶

Module Contents¶

Classes¶

Data¶

API¶

`hutool.core.util.strings`¶