hutool.core.util.array

数组工具类，对应 Java cn.hutool.core.util.ArrayUtil

Module Contents

Classes

ArrayUtil

数组工具类，对应 Java cn.hutool.core.util.ArrayUtil

API

class hutool.core.util.array.ArrayUtil

数组工具类，对应 Java cn.hutool.core.util.ArrayUtil

static is_empty(array) → bool

数组是否为空，None也视为空

参数:

array – 待检查的数组或列表

返回:

如果 array 为 None 或长度为 0 则返回 True

static is_not_empty(array) → bool

数组是否为非空

参数:

array – 待检查的数组或列表

返回:

如果 array 非 None 且长度大于 0 则返回 True

static has_null(*args) → bool

是否有null元素

参数:

args – 任意数量的参数

返回:

如果存在任意一个参数为 None 则返回 True

static is_all_null(*args) → bool

是否全部为null

参数:

args – 任意数量的参数

返回:

如果所有参数均为 None 则返回 True

static first_non_null(*args)

返回第一个非null值

参数:

args – 任意数量的参数

返回:

第一个不为 None 的值，全部为 None 则返回 None

static append(array: list, *new_elements) → list

追加元素，返回新数组

参数:

• array – 原始列表

• new_elements – 要追加的元素

返回:

追加后的新列表

static insert(array: list, index: int, *new_elements) → list

在指定位置插入元素

参数:

• array – 原始列表

• index – 插入位置索引，支持负索引

• new_elements – 要插入的元素

返回:

插入后的新列表

抛出:

IndexError – 索引越界时抛出

static remove(array: list, index: int) → list

移除指定位置元素

参数:

• array – 原始列表

• index – 要移除的位置索引，支持负索引

返回:

移除后的新列表

抛出:

IndexError – 索引越界时抛出

static remove_ele(array: list, element) → list

移除指定元素（第一个匹配）

参数:

• array – 原始列表

• element – 要移除的元素

返回:

移除后的新列表，如果元素不存在则返回原列表的副本

static index_of(array, value) → int

查找元素位置，不存在返回-1

参数:

• array – 要搜索的列表或可迭代对象

• value – 要查找的值

返回:

元素首次出现的索引，不存在返回 -1

static last_index_of(array, value) → int

从后向前查找

参数:

• array – 要搜索的列表或可迭代对象

• value – 要查找的值

返回:

元素最后出现的索引，不存在返回 -1

static contains(array, value) → bool

是否包含指定元素

参数:

• array – 要搜索的列表或可迭代对象

• value – 要查找的值

返回:

如果包含该元素则返回 True

static contains_any(array, *values) → bool

是否包含任意一个

参数:

• array – 要搜索的列表或可迭代对象

• values – 要查找的值（可多个）

返回:

如果包含任意一个值则返回 True

static contains_all(array, *values) → bool

是否包含全部

参数:

• array – 要搜索的列表或可迭代对象

• values – 要查找的值（可多个）

返回:

如果包含全部值则返回 True

static sub(array: list, start: int, end: int) → list

获取子数组，支持负索引

参数:

• array – 原始列表

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

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

返回:

子列表

抛出:

IndexError – 索引越界时抛出

static join(array, conjunction: str) → str

数组转字符串，用连接符连接

参数:

• array – 要连接的列表或可迭代对象

• conjunction – 连接符

返回:

连接后的字符串，空数组返回空字符串

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

两个列表合并为字典

参数:

• keys – 键列表

• values – 值列表

返回:

合并后的字典，长度以较短的列表为准

static to_list(iterable) → list

转为列表

参数:

iterable – 可迭代对象

返回:

转换后的列表，None 返回空列表

static reverse(array: list) → list

反转数组，返回新数组

参数:

array – 原始列表

返回:

反转后的新列表

static shuffle(array: list) → list

随机打乱，返回新数组

参数:

array – 原始列表

返回:

随机打乱后的新列表

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

交换两个位置的元素

参数:

• array – 原始列表

• index1 – 第一个位置索引

• index2 – 第二个位置索引

返回:

交换后的新列表

抛出:

IndexError – 索引越界时抛出

static length(array) → int

获取数组长度

参数:

array – 数组或列表，None 返回 0

返回:

数组长度

static min(array) → Any

取最小值

参数:

array – 非空列表或可迭代对象

返回:

最小值

抛出:

ValueError – 数组为空时抛出

static max(array) → Any

取最大值

参数:

array – 非空列表或可迭代对象

返回:

最大值

抛出:

ValueError – 数组为空时抛出

static has_empty(*args) → bool

是否有空值

空值定义：None、空字符串、空列表/元组/字典/集合等。

参数:

args – 任意数量的参数

返回:

如果存在任意一个空值则返回 True

static filter(array: list, filter_func: Callable[[Any], bool]) → list

过滤数组

参数:

• array – 原始列表

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

返回:

过滤后的新列表

static map(array: list, map_func: Callable[[Any], Any]) → list

映射数组

参数:

• array – 原始列表

• map_func – 映射函数，对每个元素进行转换

返回:

映射后的新列表

static flatten(nested_list) → list

展平嵌套列表

将多层嵌套的列表展平为一维列表。字符串和字节类型不会被展开。

参数:

nested_list – 嵌套列表

返回:

展平后的一维列表

static distinct(array: list) → list

去重，保持顺序

参数:

array – 原始列表

返回:

去重后的新列表，保持原有顺序

static fill(value, size: int) → list

用指定值填充指定大小的列表

注意：如果 value 是可变对象（如 list、dict），列表中的每个元素将是同一个引用。 如需独立副本，请对每个元素单独复制。

参数:

• value – 填充的值

• size – 列表大小

返回:

填充后的列表

抛出:

ValueError – size 为负数时抛出

static default_if_empty(arr, default=None)

如果数组为空则返回默认值。

参数:

• arr – 数组（可为 None）

• default – 默认值

返回:

原数组或默认值

static first_match(arr, predicate)

返回数组中第一个满足条件的元素。

参数:

• arr – 数组

• predicate – 条件函数

返回:

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

static match_index(arr, predicate)

返回数组中第一个满足条件的元素索引。

参数:

• arr – 数组

• predicate – 条件函数

返回:

索引，无匹配返回 -1

static set_or_append(arr: list, index: int, value) → list

设置值到指定索引，越界时追加到末尾。

参数:

• arr – 列表

• index – 索引

• value – 值

返回:

修改后的列表

static replace(arr: list, index: int, value) → Any

替换指定索引的值并返回旧值。

参数:

• arr – 列表

• index – 索引

• value – 新值

返回:

旧值

static resize(arr: list, new_size: int, fill_value=None) → list

调整数组大小。

参数:

• arr – 列表

• new_size – 新大小

• fill_value – 填充值（当需要扩展时）

返回:

调整后的列表

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

向数组中添加多个元素。

参数:

• arr – 列表

• elements – 要添加的元素

返回:

添加后的列表

static copy(arr, new_size: int = -1)

复制数组。

参数:

• arr – 原数组

• new_size – 新数组大小，-1 表示与原数组相同

返回:

复制后的新数组

static clone(arr)

浅克隆数组。

参数:

arr – 原数组

返回:

克隆后的新数组

static edit(arr, func)

对数组中每个元素应用函数。

参数:

• arr – 数组

• func – 转换函数

返回:

转换后的新数组

static remove_null(arr: list) → list

移除数组中的 None 元素。

参数:

arr – 原数组

返回:

移除 None 后的新数组

static remove_empty(arr: list) → list

移除数组中的空元素（None、空字符串、空列表等）。

参数:

arr – 原数组

返回:

移除空元素后的新数组

static remove_blank(arr: list) → list

移除数组中的空白字符串元素。

参数:

arr – 原数组

返回:

移除空白字符串后的新数组

static null_to_empty(arr)

None 转空数组。

参数:

arr – 数组（可为 None）

返回:

原数组或空列表

static index_of_ignore_case(arr, element: str) → int

忽略大小写查找字符串在数组中的索引。

参数:

• arr – 字符串数组

• element – 要查找的字符串

返回:

索引，不存在返回 -1

static contains_ignore_case(arr, element: str) → bool

忽略大小写判断数组是否包含字符串。

参数:

• arr – 字符串数组

• element – 要查找的字符串

返回:

是否包含

static wrap(arr) → list

将单个元素包装为数组。

参数:

arr – 元素或数组

返回:

数组

static is_array(obj) → bool

判断对象是否为数组（list 或 tuple）。

参数:

obj – 对象

返回:

是否为数组

static get(arr, index: int)

安全地获取数组中指定索引的元素。

参数:

• arr – 数组

• index – 索引

返回:

元素，越界返回 None

static get_any(arr)

获取数组中任意一个元素。

参数:

arr – 数组

返回:

任意元素，为空返回 None

static index_of_sub(array, sub_array) → int

查找子数组在数组中第一次出现的起始索引。

参数:

• array – 主数组

• sub_array – 子数组

返回:

第一次出现的起始索引，未找到返回 -1

static last_index_of_sub(array, sub_array) → int

查找子数组在数组中最后一次出现的起始索引。

参数:

• array – 主数组

• sub_array – 子数组

返回:

最后一次出现的起始索引，未找到返回 -1

static is_all_empty(*arrays) → bool

判断所有数组是否都为空。

参数:

arrays – 一个或多个数组

返回:

所有数组均为空（None 或长度为 0）时返回 True

static is_all_not_empty(*arrays) → bool

判断所有数组是否都不为空。

参数:

arrays – 一个或多个数组

返回:

所有数组均非空时返回 True

static is_all_not_null(*arrays) → bool

判断所有数组是否都不为 None。

参数:

arrays – 一个或多个数组

返回:

所有数组均不为 None 时返回 True

static is_sorted(array, comparator=None) → bool

判断数组是否已排序。

参数:

• array – 待检查的数组

• comparator – 自定义比较函数，接受两个参数，返回负数/0/正数；为 None 时使用默认升序比较

返回:

是否已排序

static is_sorted_asc(array) → bool

判断数组是否为升序排列。

参数:

array – 待检查的数组

返回:

是否为升序排列

static is_sorted_desc(array) → bool

判断数组是否为降序排列。

参数:

array – 待检查的数组

返回:

是否为降序排列

static is_sub(array, sub_array) → bool

判断 sub_array 是否为 array 的子序列（元素按顺序出现，不要求连续）。

参数:

• array – 主数组

• sub_array – 待检查的子序列

返回:

是否为子序列

static map_to_set(array, func) → set

对数组中每个元素应用函数，并将结果收集到集合中。

参数:

• array – 输入数组

• func – 映射函数，接受单个元素并返回结果

返回:

映射结果组成的集合

static to_array(iterable) → list

将可迭代对象转换为列表。

参数:

iterable – 可迭代对象

返回:

列表，iterable 为 None 时返回空列表

static zip_arrays(*arrays) → list

将多个数组按对应位置打包为元组列表，长度不足的部分用 None 填充。

参数:

arrays – 一个或多个数组

返回:

打包后的元组列表