`hutool.core.iter`¶

迭代工具类，提供常用的 itertools recipes。

对应 Python 官方 itertools recipes 文档中的常用工具函数，兼容 Python 3.8（不依赖 3.10+ 的 itertools.pairwise）。

Module Contents¶

Classes¶

IterUtil

迭代工具类，提供常用的 itertools recipes。

Data¶

T

API¶

hutool.core.iter.T = 'TypeVar(...)'¶

class hutool.core.iter.IterUtil¶

迭代工具类，提供常用的 itertools recipes。

所有方法均为静态方法，输入为任意可迭代对象，返回列表或生成器（按需）。

static take(n: int, iterable: Iterable) → list¶

取可迭代对象的前 n 项，返回列表。

Examples:

IterUtil.take(3, range(10))  -> [0, 1, 2]
IterUtil.take(5, "Hello")    -> ['H', 'e', 'l', 'l', 'o']

参数:

n – 取前 N 项
iterable – 可迭代对象

返回:

前 N 项组成的列表

static tail(n: int, iterable: Iterable) → list¶

取可迭代对象的后 n 项。

Examples:

IterUtil.tail(3, range(10))  -> [7, 8, 9]

参数:

n – 取后 N 项
iterable – 可迭代对象

返回:

后 N 项组成的列表

static nth(iterable: Iterable, n: int, default: Any = None) → Any¶

返回可迭代对象的第 n 项（从 0 开始）。

越界时返回 default。

Examples:

IterUtil.nth(range(10), 3)   -> 3
IterUtil.nth(range(3), 10)   -> None
IterUtil.nth(range(3), 10, -1) -> -1

参数:

iterable – 可迭代对象
n – 索引（从 0 开始）
default – 越界时的默认值

返回:

第 N 项或默认值

static all_equal(iterable: Iterable) → bool¶

判断可迭代对象中的所有元素是否相等。

空可迭代对象返回 True。

Examples:

IterUtil.all_equal([1, 1, 1])  -> True
IterUtil.all_equal([1, 2, 1])  -> False

参数:: iterable – 可迭代对象
返回:: 是否所有元素相等

static quantify(iterable: Iterable, pred: Callable = bool) → int¶

统计可迭代对象中满足谓词条件的元素数量。

Examples:

IterUtil.quantify([1, 2, 3, 4], lambda x: x % 2 == 0)  -> 2

参数:

iterable – 可迭代对象
pred – 谓词函数，默认为 bool （统计真值个数）

返回:

满足条件的元素数量

static flatten(list_of_lists: Iterable) → itertools.chain¶

将一层嵌套的可迭代对象展平。

返回生成器，惰性求值。

Examples:

list(IterUtil.flatten([[1, 2], [3, 4], [5]]))  -> [1, 2, 3, 4, 5]

参数:: list_of_lists – 嵌套可迭代对象
返回:: 展平后的生成器

static pairwise(iterable: Iterable) → Iterable[Tuple]¶

将可迭代对象中的相邻元素配对。

返回 (s0, s1), (s1, s2), (s2, s3), ... 形式的生成器。

兼容 Python 3.8（3.10+ 有 itertools.pairwise）。

Examples:

list(IterUtil.pairwise("ABC"))  -> [('A','B'), ('B','C')]

参数:: iterable – 可迭代对象
返回:: 相邻配对的生成器

static grouper(iterable: Iterable, n: int, fillvalue: Any = None) → Iterable[tuple]¶

将可迭代对象按固定长度 n 分组，不足的用 fillvalue 填充。

Examples:

list(IterUtil.grouper("ABCDEFG", 3, 'x'))
-> [('A','B','C'), ('D','E','F'), ('G','x','x')]

参数:

iterable – 可迭代对象
n – 每组长度
fillvalue – 填充值

返回:

分组元组的生成器

static roundrobin(*iterables: Iterable) → Iterable¶

交替轮询多个可迭代对象。

Examples:

list(IterUtil.roundrobin("ABC", "D", "EF"))
-> ['A', 'D', 'E', 'B', 'F', 'C']

参数:: iterables – 多个可迭代对象
返回:: 交替轮询的生成器

static partition(pred: Callable, iterable: Iterable) → Tuple[Iterable, Iterable]¶

按谓词将可迭代对象分为两组：不满足条件的和满足条件的。

返回 (false_iter, true_iter) 两个生成器。

Examples:

f, t = IterUtil.partition(lambda x: x % 2, range(5))
list(f)  -> [0, 2, 4]
list(t)  -> [1, 3]

参数:

pred – 谓词函数
iterable – 可迭代对象

返回:

(false_iter, true_iter) 元组

static powerset(iterable: Iterable) → itertools.chain¶

计算可迭代对象的幂集（所有子集）。

Examples:

list(IterUtil.powerset([1, 2, 3]))
-> [(), (1,), (2,), (3,), (1,2), (1,3), (2,3), (1,2,3)]

参数:: iterable – 可迭代对象
返回:: 幂集的生成器

static unique_everseen(iterable: Iterable, key: Optional[Callable] = None) → Iterable¶

保序去重（记住所有已见元素）。

与 CollUtil.distinct() 功能类似，但返回生成器。

Examples:

list(IterUtil.unique_everseen("AAAABBBCCDAABBB"))  -> ['A','B','C','D']
list(IterUtil.unique_everseen("ABBCcAD", str.lower))  -> ['A','B','C','D']

参数:

iterable – 可迭代对象
key – 可选的键函数，用于比较前转换元素

返回:

去重后的生成器

static is_empty(iterable: Iterable) → bool¶

判断可迭代对象是否为空。

参数:: iterable – 可迭代对象
返回:: 是否为空

static is_not_empty(iterable: Iterable) → bool¶

判断可迭代对象是否不为空。

参数:: iterable – 可迭代对象
返回:: 是否不为空

static has_null(iterable: Iterable) → bool¶

判断可迭代对象中是否有 None 元素。

参数:: iterable – 可迭代对象
返回:: 是否包含 None

static is_all_null(iterable: Iterable) → bool¶

判断可迭代对象中是否所有元素都为 None。

参数:: iterable – 可迭代对象
返回:: 是否全部为 None

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

统计各元素出现次数。

参数:

iterable – 可迭代对象
key_func – 可选的键函数

返回:

{元素: 出现次数}

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

将可迭代对象转为 {key_field值: value_field值} 映射。

参数:

iterable – 可迭代对象（元素为 dict 或对象）
key_field – 作为键的字段名
value_field – 作为值的字段名

返回:

字典映射

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

将可迭代对象的元素拼接为字符串。

参数:

iterable – 可迭代对象
separator – 分隔符

返回:

拼接后的字符串

static to_map(iterable: Iterable, key_func: Callable, value_func: Optional[Callable] = None) → dict¶

将可迭代对象转为字典。

参数:

iterable – 可迭代对象
key_func – 键函数
value_func – 值函数（默认元素本身）

返回:

字典

static to_list(iterable: Iterable) → list¶

将可迭代对象转为列表。

参数:: iterable – 可迭代对象
返回:: 列表

static get(iterable: Iterable, index: int) → Any¶

获取可迭代对象中指定索引的元素。

参数:

iterable – 可迭代对象
index – 索引

返回:

元素，越界返回 None

static get_first(iterable: Iterable) → Any¶

获取第一个元素。

参数:: iterable – 可迭代对象
返回:: 第一个元素，为空返回 None

static get_first_none_null(iterable: Iterable) → Any¶

获取第一个非 None 的元素。

参数:: iterable – 可迭代对象
返回:: 第一个非 None 元素，全为 None 则返回 None

static first_match(iterable: Iterable, predicate: Callable[[Any], bool]) → Any¶

获取第一个满足条件的元素。

参数:

iterable – 可迭代对象
predicate – 条件函数

返回:

满足条件的第一个元素，无匹配返回 None

static get_element_type(iterable: Iterable) → Optional[type]¶

获取可迭代对象中第一个元素的类型。

参数:: iterable – 可迭代对象
返回:: 元素类型，为空返回 None

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

对每个元素应用函数。

参数:

iterable – 可迭代对象
func – 转换函数

返回:

转换后的列表

static filter_(iterable: Iterable, predicate: Callable[[Any], bool]) → list¶

过滤并返回新列表。

参数:

iterable – 可迭代对象
predicate – 过滤条件

返回:

过滤后的列表

static filter_to_list(iterable: Iterable, predicate: Callable[[Any], bool]) → list¶

过滤并返回新列表（等同于 filter_）。

参数:

iterable – 可迭代对象
predicate – 过滤条件

返回:

过滤后的列表

static for_each(iterable: Iterable, func: Callable[[Any], None]) → None¶

对每个元素执行操作。

参数:

iterable – 可迭代对象
func – 操作函数

static to_str(iterable: Iterable, separator: str = ',') → str¶

将可迭代对象转为字符串表示。

参数:

iterable – 可迭代对象
separator – 分隔符

返回:

字符串

static size(iterable: Iterable) → int¶

获取可迭代对象的大小。

参数:: iterable – 可迭代对象
返回:: 元素个数

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

判断两个列表是否相等。

参数:

list1 – 列表1
list2 – 列表2

返回:

是否相等

static to_list_map(iterable: Iterable, key_func: Callable, value_func: Optional[Callable] = None) → dict¶

将可迭代对象转为 {key: [values]} 字典。

参数:

iterable – 可迭代对象
key_func – 提取键的函数
value_func – 提取值的函数，为 None 时使用元素本身

返回:

分组字典

static filtered(iterable: Iterable, predicate: Callable[[Any], bool]) → Iterable¶

返回惰性过滤后的迭代器。

参数:

iterable – 可迭代对象
predicate – 过滤条件函数

返回:

过滤后的迭代器

static empty()¶

返回空迭代器。

返回:: 空迭代器

static trans(iterable: Iterable, func: Callable) → list¶

迭代器类型转换。

参数:

iterable – 可迭代对象
func – 转换函数

返回:

转换后的列表

static clear(lst: list) → None¶

清空列表。

参数:: lst – 列表

static prepend(value: Any, iterable: Iterable) → Iterable¶

在迭代器前插入一个元素。

参数:

value – 要插入的值
iterable – 可迭代对象

返回:

迭代器

static tabulate(func: Callable[[int], Any], start: int = 0) → Iterable¶

从函数生成迭代器 func(start), func(start+1), ...。

参数:

func – 接受 int 参数的函数
start – 起始索引，默认 0

返回:

无限迭代器

static consume(iterator: Iterable, n: int) → None¶

消耗迭代器的前 N 个元素（无返回值）。

参数:

iterator – 迭代器
n – 要消耗的元素数量

static pad_none(iterable: Iterable) → Iterable¶

迭代器结束后无限返回 None。

参数:: iterable – 可迭代对象
返回:: 无限迭代器

static n_cycles(iterable: Iterable, n: int) → Iterable¶

将迭代器重复 N 次。

参数:

iterable – 可迭代对象
n – 重复次数

返回:

重复后的迭代器

static iter_except(func: Callable, exception: type = Exception, first: Any = None) → Iterable¶

迭代直到抛出异常。

常用于集合迭代，当迭代结束时会抛出 exception。

参数:

func – 无参数的调用函数（每次调用返回下一个元素）
exception – 终止异常类型，默认 Exception
first – 首次调用的默认值（不使用）

返回:

迭代器

static first_true(iterable: Iterable, predicate: Optional[Callable[[Any], bool]] = None, default: Any = None) → Any¶

返回第一个使谓词为 True 的元素。

参数:

iterable – 可迭代对象
predicate – 判断函数，默认 bool
default – 无匹配时的默认值

返回:

第一个满足条件的元素，或默认值

static random_product(*iterables: Iterable, repeat: int = 1) → tuple¶

从多个迭代器中随机选取组合。

参数:

iterables – 多个可迭代对象
repeat – 重复次数，默认 1

返回:

随机选取的元组

static random_permutation(iterable: Iterable, r: Optional[int] = None) → list¶

随机排列。

参数:

iterable – 可迭代对象
r – 选取元素数量，默认为全部

返回:

随机排列的列表

static random_combination(iterable: Iterable, r: int) → tuple¶

随机组合（无放回，无序）。

参数:

iterable – 可迭代对象
r – 选取元素数量

返回:

随机组合的元组

static nth_combination(iterable: Iterable, r: int, index: int) → tuple¶

返回第 N 个组合（等价于 itertools.combinations 的第 index 个结果）。

参数:

iterable – 可迭代对象
r – 组合长度
index – 组合索引

返回:

第 N 个组合的元组

hutool.core.iter¶

Module Contents¶

Classes¶

Data¶

API¶

`hutool.core.iter`¶