hutool.core.coll

集合与列表工具类

对应 Java cn.hutool.core.collection.CollUtil 和 ListUtil

Module Contents

Classes

CollUtil	集合工具类，对应 Java cn.hutool.core.collection.CollUtil
ListUtil	列表工具类

Data

T
K
V

API

hutool.core.coll.T = 'TypeVar(...)'

hutool.core.coll.K = 'TypeVar(...)'

hutool.core.coll.V = 'TypeVar(...)'

class hutool.core.coll.CollUtil

集合工具类，对应 Java cn.hutool.core.collection.CollUtil

static is_empty(coll) → bool

集合是否为空，None 也视为空。

支持 list/tuple/set/dict/frozenset。

参数:

coll – 集合对象

返回:

是否为空

static is_not_empty(coll) → bool

集合是否为非空。

参数:

coll – 集合对象

返回:

是否为非空

static has_null(coll: Sequence) → bool

集合中是否有 None 元素。

参数:

coll – 序列对象

返回:

是否包含 None 元素

static contains(coll: Iterable, element: Any) → bool

是否包含指定元素。

参数:

• coll – 可迭代集合

• element – 待查找的元素

返回:

是否包含

static contains_any(coll: Iterable, *elements) → bool

是否包含任意一个指定元素。

参数:

• coll – 可迭代集合

• elements – 待查找的元素

返回:

是否包含任意一个

static contains_all(coll: Iterable, *elements) → bool

是否包含全部指定元素。

参数:

• coll – 可迭代集合

• elements – 待查找的元素

返回:

是否包含全部

static new_array_list(*args) → list

新建 ArrayList（Python list），可传入初始元素。

参数:

args – 初始元素

返回:

新列表

static new_hash_set(*args) → set

新建 HashSet（Python set），可传入初始元素。

参数:

args – 初始元素

返回:

新集合

static to_list(iterable: Iterable) → list

转为列表。

参数:

iterable – 可迭代对象

返回:

列表

static to_set(iterable: Iterable) → set

转为集合。

参数:

iterable – 可迭代对象

返回:

集合

static to_map(items: Sequence, key_func: Callable, value_func: Optional[Callable] = None) → dict

列表转 Map，通过 key_func 提取键，value_func 提取值（默认值为元素本身）

参数:

• items – 待转换的列表

• key_func – 键提取函数

• value_func – 值提取函数，默认为元素本身

返回:

字典

static group_by(coll: Iterable, key_func: Callable) → dict

按条件分组，返回 {key: [items]}

参数:

• coll – 待分组集合

• key_func – 分组键提取函数

返回:

分组字典

static partition(coll: List[hutool.core.coll.T], size: int) → List[List[hutool.core.coll.T]]

将列表按指定大小分割为子列表

参数:

• coll – 待分割列表

• size – 每个子列表的最大大小

返回:

分割后的二维列表

抛出:

ValueError – size 小于等于 0

static zip_list(keys: list, values: list) → dict

两个列表合并为字典

参数:

• keys – 键列表

• values – 值列表

返回:

合并后的字典

static add_all(coll: list, *elements) → list

添加所有元素到列表，返回新列表

参数:

• coll – 原列表

• elements – 要添加的元素

返回:

新列表

static remove_null(coll: list) → list

移除所有 None 元素，返回新列表

参数:

coll – 原列表

返回:

不含 None 的新列表

static filter(coll: List[hutool.core.coll.T], filter_func: Callable[[hutool.core.coll.T], bool]) → List[hutool.core.coll.T]

过滤集合

参数:

• coll – 待过滤列表

• filter_func – 过滤函数，返回 True 保留

返回:

过滤后的新列表

static map_list(coll: List[hutool.core.coll.T], map_func: Callable[[hutool.core.coll.T], hutool.core.coll.V]) → List[hutool.core.coll.V]

映射集合

参数:

• coll – 待映射列表

• map_func – 映射函数

返回:

映射后的新列表

static flat_map(coll: Iterable, map_func: Callable) → list

flatMap — 先映射再展平

参数:

• coll – 待处理集合

• map_func – 映射函数，返回可迭代对象

返回:

展平后的新列表

static distinct(coll: List[hutool.core.coll.T]) → List[hutool.core.coll.T]

去重，保持顺序

参数:

coll – 原列表

返回:

去重后的新列表

static sort(coll: List[hutool.core.coll.T], key_func: Optional[Callable] = None, reverse: bool = False) → List[hutool.core.coll.T]

排序，返回新列表

参数:

• coll – 待排序列表

• key_func – 排序键函数

• reverse – 是否降序

返回:

排序后的新列表

static reverse(coll: List[hutool.core.coll.T]) → List[hutool.core.coll.T]

反转，返回新列表

参数:

coll – 原列表

返回:

反转后的新列表

static shuffle(coll: List[hutool.core.coll.T]) → List[hutool.core.coll.T]

随机打乱，返回新列表

参数:

coll – 原列表

返回:

打乱后的新列表

static min_val(coll: Iterable) → Any

取最小值

参数:

coll – 可迭代集合

返回:

最小值

抛出:

ValueError – 集合为空

static max_val(coll: Iterable) → Any

取最大值

参数:

coll – 可迭代集合

返回:

最大值

抛出:

ValueError – 集合为空

static safe_min(coll: Iterable) → Optional[Any]

安全地获取集合最小值，空集合返回 None 而非抛出异常。

参数:

coll – 可迭代集合

返回:

最小值，集合为空或为 None 时返回 None

static safe_max(coll: Iterable) → Optional[Any]

安全地获取集合最大值，空集合返回 None 而非抛出异常。

参数:

coll – 可迭代集合

返回:

最大值，集合为空或为 None 时返回 None

static count(coll: Iterable, predicate: Callable) → int

统计满足条件的元素个数

参数:

• coll – 可迭代集合

• predicate – 判断条件

返回:

满足条件的元素数量

static find_first(coll: Iterable, predicate: Callable) → Optional[hutool.core.coll.T]

查找第一个满足条件的元素

参数:

• coll – 可迭代集合

• predicate – 判断条件

返回:

第一个满足条件的元素，未找到返回 None

static find_last(coll: List[hutool.core.coll.T], predicate: Callable[[hutool.core.coll.T], bool]) → Optional[hutool.core.coll.T]

查找最后一个满足条件的元素

参数:

• coll – 列表

• predicate – 判断条件

返回:

最后一个满足条件的元素，未找到返回 None

static any_match(coll: Iterable, predicate: Callable) → bool

是否任意一个匹配

参数:

• coll – 可迭代集合

• predicate – 判断条件

返回:

是否有任一元素满足条件

static all_match(coll: Iterable, predicate: Callable) → bool

是否全部匹配

参数:

• coll – 可迭代集合

• predicate – 判断条件

返回:

是否所有元素都满足条件

static none_match(coll: Iterable, predicate: Callable) → bool

是否无匹配

参数:

• coll – 可迭代集合

• predicate – 判断条件

返回:

是否没有元素满足条件

static join(coll: Iterable, separator: str = ',') → str

用连接符连接集合元素

参数:

• coll – 可迭代集合

• separator – 分隔符

返回:

连接后的字符串

static find_duplicates(lst: List[hutool.core.coll.T]) → List[hutool.core.coll.T]

查找列表中的重复元素，保留首次出现顺序。

Examples:

find_duplicates([1, 2, 3, 2, 4, 3]) -> [2, 3]

参数:

lst – 待查找列表

返回:

重复元素列表（保序）

static get_first(coll: Iterable) → Optional[hutool.core.coll.T]

获取第一个元素

参数:

coll – 可迭代集合

返回:

第一个元素，为空时返回 None

static get_last(coll: List[hutool.core.coll.T]) → Optional[hutool.core.coll.T]

获取最后一个元素

参数:

coll – 列表

返回:

最后一个元素，为空时返回 None

static sub_list(coll: List[hutool.core.coll.T], start: int, end: int) → List[hutool.core.coll.T]

获取子列表

参数:

• coll – 原列表

• start – 起始索引（包含）

• end – 结束索引（不包含）

返回:

子列表

static page(coll: List[hutool.core.coll.T], page_num: int, page_size: int) → List[hutool.core.coll.T]

分页，page_num 从 1 开始

参数:

• coll – 原列表

• page_num – 页码（从 1 开始）

• page_size – 每页大小

返回:

当前页数据

抛出:

ValueError – 参数非法

static for_each(coll: Iterable, consumer: Callable) → None

遍历集合并对每个元素执行操作

参数:

• coll – 可迭代集合

• consumer – 消费函数

static empty_if_none(coll) → list

None 转空列表

参数:

coll – 可能为 None 的集合

返回:

原集合或空列表

static default_if_empty(coll: list, default: list) → list

如果为空则返回默认值

参数:

• coll – 可能为空的列表

• default – 默认列表

返回:

原列表或默认列表

static is_sub(list1: list, list2: list) → bool

判断 list1 是否为 list2 的子集

参数:

• list1 – 候选子集

• list2 – 候选超集

返回:

是否为子集

static intersection(coll1: Iterable, coll2: Iterable) → list

求两个集合的交集，保持元素首次出现顺序

参数:

• coll1 – 第一个集合

• coll2 – 第二个集合

返回:

交集列表

static disjunction(coll1: Iterable, coll2: Iterable) → list

求两个集合的对称差集（在 coll1 或 coll2 中但不同时在两者中的元素）

参数:

• coll1 – 第一个集合

• coll2 – 第二个集合

返回:

对称差集列表

static union(*colls: Iterable) → list

合并多个集合（不去重）。

参数:

colls – 多个可迭代对象

返回:

合并后的列表

static union_distinct(*colls: Iterable) → list

合并多个集合并去重。

参数:

colls – 多个可迭代对象

返回:

去重后的列表（保持首次出现顺序）

static intersection_distinct(coll1: Iterable, coll2: Iterable) → list

求交集（去重）。

参数:

• coll1 – 集合1

• coll2 – 集合2

返回:

交集列表

static subtract(coll1: Iterable, coll2: Iterable) → list

求差集（coll1 有但 coll2 没有，不去重）。

参数:

• coll1 – 集合1

• coll2 – 集合2

返回:

差集列表

static safe_contains(coll, element: Any) → bool

安全地判断集合是否包含元素（None 安全）。

参数:

• coll – 集合（可为 None）

• element – 要查找的元素

返回:

是否包含

static contains_by_pred(coll: Iterable, predicate: Callable[[Any], bool]) → bool

判断集合中是否有满足条件的元素。

参数:

• coll – 可迭代对象

• predicate – 条件函数

返回:

是否有满足条件的元素

static count_map(coll: Iterable, key_func: Optional[Callable[[Any], Any]] = None) → dict

统计集合中各元素出现次数。

参数:

• coll – 可迭代对象

• key_func – 可选的键函数，用于分组统计

返回:

{元素: 出现次数}

static field_value_map(coll: Iterable, key_field: str, value_field: str) → dict

将集合转为 {key_field值: value_field值} 的映射。

参数:

• coll – 可迭代对象（元素为 dict 或对象）

• key_field – 作为键的字段名

• value_field – 作为值的字段名

返回:

字典映射

static to_map_list(coll: Iterable, key_func: Callable) → dict

按 key_func 分组，值为列表。

参数:

• coll – 可迭代对象

• key_func – 键函数

返回:

{key: [values]}

static group(coll: Iterable, key_func: Callable) → dict

按条件分组。

参数:

• coll – 可迭代对象

• key_func – 分组键函数

返回:

{key: [items]}

static group_by_field(coll: Iterable, field: str) → dict

按字段分组。

参数:

• coll – 可迭代对象（元素为 dict 或对象）

• field – 分组字段名

返回:

{field_value: [items]}

static sort_page_all(coll: Iterable, key_func: Optional[Callable] = None, reverse: bool = False) → list

排序后返回全部。

参数:

• coll – 可迭代对象

• key_func – 排序键函数

• reverse – 是否降序

返回:

排序后的列表

static pop_part(lst: list, count: int) → list

从列表头部弹出指定数量的元素。

参数:

• lst – 列表（会被修改）

• count – 弹出数量

返回:

弹出的元素列表

static split_list(lst: list, size: int) → List[list]

将列表按指定大小分割为多个子列表。

参数:

• lst – 列表

• size – 每个子列表的最大大小

返回:

分割后的子列表

static edit(coll: Iterable, func: Callable[[Any], Any]) → list

对集合中每个元素应用函数并返回新列表。

参数:

• coll – 可迭代对象

• func – 转换函数

返回:

转换后的新列表

static filter_new(coll: Iterable, predicate: Callable[[Any], bool]) → list

过滤并返回新列表（filter 的列表版本）。

参数:

• coll – 可迭代对象

• predicate – 过滤条件

返回:

过滤后的新列表

static extract(coll: Iterable, func: Callable[[Any], Any]) → list

提取集合中每个元素的某个属性或转换结果。

参数:

• coll – 可迭代对象

• func – 提取函数

返回:

提取结果列表

static get_field_values(coll: Iterable, field: str) → list

获取集合中每个元素的某个字段值。

参数:

• coll – 可迭代对象（元素为 dict 或对象）

• field – 字段名

返回:

字段值列表

static index_of(coll: Sequence, element: Any) → int

查找元素在集合中的索引。

参数:

• coll – 序列

• element – 要查找的元素

返回:

索引，不存在返回 -1

static index_of_all(coll: Sequence, element: Any) → List[int]

查找元素在集合中的所有索引。

参数:

• coll – 序列

• element – 要查找的元素

返回:

索引列表

static add_if_absent(lst: list, element: Any) → bool

如果元素不在列表中则添加。

参数:

• lst – 列表（会被修改）

• element – 要添加的元素

返回:

是否添加了新元素

static get(coll: Sequence, index: int) → Any

安全地获取集合中指定索引的元素。

参数:

• coll – 序列

• index – 索引

返回:

元素，越界返回 None

static get_any(coll: Iterable) → Any

获取集合中任意一个元素。

参数:

coll – 可迭代对象

返回:

任意元素，空集合返回 None

static values_of_keys(coll: Iterable, keys: Iterable) → list

获取字典集合中指定键的值。

参数:

• coll – 字典列表

• keys – 键列表

返回:

值列表

static size(coll) → int

获取集合大小（None 安全）。

参数:

coll – 集合（可为 None）

返回:

大小，None 返回 0

static is_equal_list(list1: list, list2: list) → bool

判断两个列表是否相等（逐元素比较）。

参数:

• list1 – 列表1

• list2 – 列表2

返回:

是否相等

static union_all(*colls: Iterable) → list

不去重并集。

参数:

colls – 多个集合

返回:

合并后的列表（不去重）

static subtract_to_list(coll1: Iterable, coll2: Iterable) → list

差集，返回列表。

参数:

• coll1 – 集合1

• coll2 – 集合2

返回:

属于 coll1 但不属于 coll2 的元素列表

static new_linked_hash_set(*args) → dict

创建有序集合（Python 中用 dict 实现保序去重）。

参数:

args – 初始元素

返回:

有序集合（字典键）

static list(*args) → list

创建列表。

参数:

args – 初始元素

返回:

列表

static new_linked_list(*args) → list

创建列表（LinkedList 等价）。

参数:

args – 初始元素

返回:

列表

static create(coll_type, *args)

按类型创建集合并填充元素。

参数:

• coll_type – 集合类型（list, set, tuple 等）

• args – 初始元素

返回:

指定类型的集合

static distinct_by(coll: Iterable, key_func: Callable) → list

按 key 函数去重。

参数:

• coll – 可迭代对象

• key_func – 提取去重键的函数

返回:

去重后的列表

static remove_any(coll: list, *elements) → list

移除列表中的指定元素。

参数:

• coll – 列表

• elements – 待移除的元素

返回:

移除后的列表

static remove_empty(coll: list) → list

移除列表中的空字符串和 None。

参数:

coll – 列表

返回:

移除后的列表

static remove_blank(coll: list) → list

移除列表中的空白字符串和 None。

参数:

coll – 列表

返回:

移除后的列表

static field_value_as_map(coll: Iterable, key_field: str, value_field: str) → dict

提取字段值构建 Map（同 field_value_map 别名）。

参数:

• coll – 可迭代对象

• key_field – 键字段名

• value_field – 值字段名

返回:

字段值映射

static find_one_by_field(coll: Iterable, field: str, value: Any)

按字段查找单个元素。

参数:

• coll – 可迭代对象

• field – 字段名

• value – 期望的字段值

返回:

匹配的元素，未找到返回 None

static last_index_of(coll: Sequence, element: Any) → int

查找元素最后出现的索引。

参数:

• coll – 序列

• element – 待查找元素

返回:

最后出现的索引，未找到返回 -1

static to_tree_set(coll: Iterable, key_func: Optional[Callable] = None) → list

排序后去重。

参数:

• coll – 可迭代对象

• key_func – 排序键函数，可选

返回:

排序去重后的列表

static add_all_if_not_contains(lst: list, *elements) → list

仅当元素不在列表中时才添加。

参数:

• lst – 列表

• elements – 待添加的元素

返回:

添加后的列表

static get_element_type(coll: Iterable) → Optional[type]

获取集合中第一个非 None 元素的类型。

参数:

coll – 可迭代对象

返回:

元素类型，空集合返回 None

static sort_by_pinyin(coll: list) → list

按拼音排序（适用于中文字符串列表）。

参数:

coll – 字符串列表

返回:

排序后的新列表

static reverse_new(coll: list) → list

反转列表，返回新列表（不修改原列表）。

参数:

coll – 列表

返回:

反转后的新列表

static key_set(coll_of_pairs: Iterable) → list

获取键值对集合的键列表。

参数:

coll_of_pairs – 键值对可迭代对象（字典列表或 tuple 列表）

返回:

键列表

static unmodifiable(coll)

返回不可修改的列表视图（使用 tuple 包装）。

参数:

coll – 集合

返回:

不可修改的 tuple

static clear(lst: list) → None

清空列表。

参数:

lst – 列表

static trans(coll: Iterable, func: Callable) → list

集合类型转换。

参数:

• coll – 可迭代对象

• func – 转换函数

返回:

转换后的列表

static sort_to_map(coll: Iterable, key_func: Callable, value_func: Optional[Callable] = None) → dict

集合排序后转为有序字典。

先按键排序，再转为字典。Python 3.7+ 字典保持插入顺序。

参数:

• coll – 可迭代集合

• key_func – 键提取函数

• value_func – 值提取函数，默认为元素本身

返回:

排序后的字典

static sort_entry_to_list(map_data: dict, reverse: bool = False) → list

字典条目按 key 排序，返回 [(key, value)] 列表。

参数:

• map_data – 输入字典

• reverse – 是否降序

返回:

排序后的条目列表

static sort_by_entry(map_data: dict, reverse: bool = False) → dict

按字典 key 排序，返回新字典。

参数:

• map_data – 输入字典

• reverse – 是否降序

返回:

排序后的新字典

static to_collection(iterable: Iterable, coll_type=None)

转为指定集合类型。

参数:

• iterable – 可迭代对象

• coll_type – 目标集合类型，默认为 list

返回:

指定类型的集合

static chunk_by(lst: list, size: int) → list

按大小将列表分块。

例如 [1,2,3,4,5], size=2 → [[1,2],[3,4],[5]]。

参数:

• lst – 原列表

• size – 每块大小（必须大于 0）

返回:

分块后的嵌套列表

static remove_duplicates(lst: list) → list

移除列表中的重复元素，保持原有顺序。

参数:

lst – 原列表

返回:

去重后的列表

class hutool.core.coll.ListUtil

列表工具类

static sub(lst: List[hutool.core.coll.T], start: int, end: int) → List[hutool.core.coll.T]

获取子列表，支持负索引

参数:

• lst – 原列表

• start – 起始索引（包含），支持负数

• end – 结束索引（不包含），支持负数

返回:

子列表

static page(lst: List[hutool.core.coll.T], page_num: int, page_size: int) → List[hutool.core.coll.T]

分页

参数:

• lst – 原列表

• page_num – 页码（从 1 开始）

• page_size – 每页大小

返回:

当前页数据

static empty_if_none(lst: Optional[List[hutool.core.coll.T]]) → List[hutool.core.coll.T]

None 转空列表

参数:

lst – 可能为 None 的列表

返回:

原列表或空列表

static default_if_empty(lst: Optional[List[hutool.core.coll.T]], default: List[hutool.core.coll.T]) → List[hutool.core.coll.T]

如果为空则返回默认值

参数:

• lst – 可能为空的列表

• default – 默认列表

返回:

原列表或默认列表

static to_tree(lst: List[dict], id_field: str = 'id', parent_field: str = 'parentId', children_field: str = 'children') → List[dict]

列表转树结构

将扁平的、通过 parentId 互相引用的字典列表转换为嵌套树形结构。 根节点的 parent_field 值为 None / 0 / 空字符串 / 不存在。

参数:

• lst – 扁平字典列表

• id_field – 主键字段名

• parent_field – 父级引用字段名

• children_field – 子节点列表字段名

返回:

树形结构的根节点列表（深拷贝，不修改原数据）

static sort_by_property(lst: List, prop_name: str, reverse: bool = False) → List

按属性排序

适用于元素为字典或对象的列表。字典按键取值，对象按 getattr 取值。

参数:

• lst – 待排序列表

• prop_name – 属性名

• reverse – 是否降序

返回:

排序后的新列表

static of(*elements: hutool.core.coll.T) → List[hutool.core.coll.T]

从可变参数创建列表。

参数:

elements – 元素

返回:

新列表

static empty() → list

返回空列表。

返回:

空列表

static set_or_padding(lst: list, index: int, element: Any) → list

设置元素到指定索引，越界时自动填充 None。

参数:

• lst – 列表（会被修改）

• index – 索引

• element – 元素

返回:

修改后的列表

static last_index_of(lst: Sequence, element: Any) → int

查找元素最后一次出现的索引。

参数:

• lst – 序列

• element – 要查找的元素

返回:

索引，不存在返回 -1

static index_of_all(lst: Sequence, element: Any) → List[int]

查找元素的所有索引。

参数:

• lst – 序列

• element – 要查找的元素

返回:

索引列表

static swap(lst: list, index1: int, index2: int) → list

交换列表中两个位置的元素。

参数:

• lst – 列表（会被修改）

• index1 – 索引1

• index2 – 索引2

返回:

修改后的列表

static move(lst: list, src_index: int, dest_index: int) → list

移动列表中的元素到新位置。

参数:

• lst – 列表（会被修改）

• src_index – 源索引

• dest_index – 目标索引

返回:

修改后的列表

static zip_(lst1: list, lst2: list) → List[tuple]

将两个列表压缩为元组列表。

参数:

• lst1 – 列表1

• lst2 – 列表2

返回:

[(a1, b1), (a2, b2), …]

static split(lst: list, size: int) → List[list]

将列表按指定大小分割。

参数:

• lst – 列表

• size – 每份大小

返回:

分割后的子列表

static split_avg(lst: list, limit: int) → List[list]

将列表平均分割为指定份数。

参数:

• lst – 列表

• limit – 份数

返回:

平均分割后的子列表

static to_linked_list(*elements) → list

创建列表。

参数:

elements – 初始元素

返回:

列表

static sort_by_pinyin(lst: list) → list

按拼音排序。

参数:

lst – 字符串列表

返回:

排序后的新列表

static swap_to(lst: list, src_index: int, dest_index: int) → list

将元素从源位置移动到目标位置。

参数:

• lst – 列表

• src_index – 源索引

• dest_index – 目标索引

返回:

修改后的列表

static swap_element(lst: list, old_element, new_element) → list

替换列表中的所有指定元素。

参数:

• lst – 列表

• old_element – 旧元素

• new_element – 新元素

返回:

修改后的列表

static unmodifiable(lst) → list

返回不可修改的列表（使用 tuple 包装）。

参数:

lst – 列表

返回:

不可修改的 tuple

static chunk_by(lst: list, size: int) → list

按大小将列表分块。

例如 [1,2,3,4,5], size=2 → [[1,2],[3,4],[5]]。

参数:

• lst – 原列表

• size – 每块大小（必须大于 0）

返回:

分块后的嵌套列表

static remove_duplicates(lst: list) → list

移除列表中的重复元素，保持原有顺序。

参数:

lst – 原列表

返回:

去重后的列表