数组工具-ArrayUtil
# 📚简介
ArrayUtil提供了一系列的快捷工具方法用于操作对象数组和原始类型数组。
# 🍭使用
# 数组判空
在数组中，“空”的概念分为三种理解：
- 数组本身为
null或含有null的情况，判断使用null之类的关键字完成。 - 数组中含有
""的情况，判断使用empty关键字完成。 - 数组中含有空白符的情况，判断使用
blank关键字完成。
# 判断null
# 1. 判断含有null元素
final String[] a = {"e", null};
// true
ArrayUtil.hasNull(a);
注意，当a本身为
null时，同样返回true。
# 2. 判断含有非null元素
String[] a = {null, "e"};
// true
ArrayUtil.hasNonNull(a);
a = new String[]{null, null};
// false
ArrayUtil.hasNonNull(a);
# 3. 数组中全部为null或全部不为null
String[] a = {null, "e"};
// false
ArrayUtil.isAllNull(a);
a = new String[]{null, null};
// true
ArrayUtil.isAllNull(a);
final String[] allNotNull = {"aa", "bb", "cc", "dd", "bb", "dd"};
// true
ArrayUtil.isAllNotNull(allNotNull);
# 4. 查找并返回第一个非空元素
final String[] a = {null, null, "cc", null, "bb", "dd"};
// "cc"
final String s = ArrayUtil.firstNonNull(a);
# 判断空（empty）
数组的"空"表示数组本身为null或数组没有元素，即长度为0。
final int[] a = {};
// true
ArrayUtil.isEmpty(a);
final int[] b = null;
// true
ArrayUtil.isEmpty(b);
注意：
isEmpty方法支持传入Object对象，当这个对象并非数组对象且非null时，返回false，即当用户传入非数组对象，理解为单个元素的数组。
final Object nonArrayObj = "a";
// false
ArrayUtil.isEmpty(nonArrayObj);
同样，Hutool提供了判断数组非空的方法：
final int[] a = {1, 2};
ArrayUtil.isNotEmpty(a);
对于数组元素的判断，可以使用hasEmpty完成：
String[] a = {"", "a"};
// true
ArrayUtil.hasEmpty(a);
当然，这里的empty并不只是针对String判断，还包括集合、Map、子数组等
final Object[] b = {"a", new ArrayList<>()};
// true
ArrayUtil.hasEmpty(b);
b = new Object[]{"a", new HashMap<>()};
// true
ArrayUtil.hasEmpty(b);
当我们需要计算数组中empty元素个数时，可以使用emptyCount:
final Object[] b = {"a", new ArrayList<>(), new HashMap<>(), new int[0]};
// 3
final int emptyCount = ArrayUtil.emptyCount(b);
# 判断空白（blank）
针对CharSequence类型的数组，即字符串数组，Hutool也封装了hasBlank、isAllBlank、isAllNotBlank等方法。
final String[] a = {" ", "aa"};
// true, " "空白符，表示blank
ArrayUtil.hasBlank(a);
final String[] a = {" ", " ", ""};
// true
ArrayUtil.isAllBlank(a);
注意：
blank包括了null、""和空白符
# 数组相等（equals）
我们知道，JDK的Arrays提供了equals方法用于判断泛型和原始类型数组是否相同，但是需要类型判断并做强制转换，Hutool封装equals方法，可以通过传入Object实现自动类型判断。
// true
ArrayUtil.equals(new int[]{1, 2, 3}, new int[]{1, 2, 3});
# 数组转字符串（toString）
JDK的Arrays同样提供了toString各种重载方法，我们在使用时依旧需要判断数组类型进而调用不同的重载方法，Hutool封装toString方法，通过传入Object自动判断类型，从而避免繁琐的类型判断，此方法也用于在Console.log中自动转换数组为可显示的类型，从而避免打印ObjectId。
final int[] a = {1, 3, 56, 6, 7};
// [1, 3, 56, 6, 7]
ArrayUtil.toString(a);
final String[] array = {"aa", "bb", "cc", "dd", "bb", "dd"};
// [aa, bb, cc, dd, bb, dd]
ArrayUtil.toString(array);
# 数组的拆装箱（wrap and unwrap）
假设一个原始类型数组，如int[]，我们想转换为Integer[]，我们无法进行自动装箱，就需要遍历后手动装箱操作。Hutool提供了wrap方法，可以简化这个操作：
final Object a = new int[]{1, 2, 3, 4};
// Integer[]
final Object[] wrapA = ArrayUtil.wrap(a);
当给定数组类型是确定的时，也可以直接调用wrap的重载方法完成转换：
final int[] a = new int[]{1, 2, 3, 4};
final Integer[] wrapA = ArrayUtil.wrap(a);
同理，我们也可以对已知类型的包装类型数组做拆箱操作：
final Integer[] a = new Integer[]{1, 2, 3, 4};
final int[] wrapA = ArrayUtil.unWrap(a);
# 数组元素追加和替换（set and append）
有时候我们想像ArrayList一样灵活的操作数组，一个办法是先转为ArrayList，再调用toArray实现；不过为了提高效率并简化操作，Hutool封装了一系列方法来辅助数组的“编辑”操作。
# 1. 追加元素（append）
final String[] a = {"1", "2", "3", "4"};
final String[] b = {"a", "b", "c"};
// ["1", "2", "3", "4", "a", "b", "c"]
final String[] result = ArrayUtil.append(a, b);
其中b为可变长参数，可以追加多个元素：
final String[] a = {"1", "2", "3", "4"};
final String[] result = ArrayUtil.append(a, "a", "b", "c");
注意：追加操作不会修改原数组，会生成新数组。
# 2. 修改元素（setOrAppend）
int[] arr2 = new int[]{1};
// [2]
int[] o = ArrayUtil.setOrAppend(arr2, 0, 2);
如果给定的index大于等于数组长度，则为追加，等同于append。如果想强制设置指定index的值，即就算index大于总长度，也要强制设置到那个位置，则使用setOrPadding:
final String[] arr = new String[0];
// [null, null, "Good"]
final String[] newArr = ArrayUtil.setOrPadding(arr, 2, "Good");
注意：
setOrPadding方法会强制设置值到指定位置，前面的位置使用默认值代替，这个默认值由ClassUtil.getDefaultValue获取，即原始类型为0或false，对象类型为null。
当然，Hutool同样提供了setOrPadding的重载方法，可以自定义默认填充值：
final String[] arr = new String[0];
// ["pad", "pad", "Good"]
final String[] newArr = ArrayUtil.setOrPadding(arr, 2, "Good", "pad");
# 是否包含元素（contains）
# 1. 查找数组中是否包含指定元素（contains）
final Integer[] a = {1, 2, 3, 4, 3, 6};
// true
final boolean contains = ArrayUtil.contains(a, 3);
注意：
contains方法通过equals方式判断对象一致，即数组中有相等对象即表示包含。
# 2. 查找数组中是否包含任意一个元素（containsAny）
final Integer[] a = {1, 2, 3, 4, 3, 6};
// 包含4，返回true
boolean contains = ArrayUtil.containsAny(a, 4, 10, 40);
# 3. 查找数组中是否包含全部指定元素（containsAll）
final Integer[] a = {1, 2, 3, 4, 3, 6};
// true, 提供的可变参数中元素顺序不需要一致
boolean contains = ArrayUtil.containsAll(a, 4, 2, 6);
# 4. 忽略大小写判断是否包含元素
final String[] keys = {"a", "B", "c"};
// true
final boolean b = ArrayUtil.containsIgnoreCase(keys, "b");
# 数组克隆和复制（clone and copy）
Hutool提供的clone方法用于复制数组，支持对象数组和原始数组。
final int[] a = {1, 2, 3};
final int[] clone = ArrayUtil.clone(a);
final Integer[] b = {1, 2, 3};
final Integer[] cloneB = ArrayUtil.clone(b);
对于数组的部分元素复制，Hutool同样封装了System.arraycopy，提供简化操作：
final String[] dest = new String[3];
// ["a", "b", null]
ArrayUtil.copy(new String[]{"a", "b"}, dest);
在数组复制中，如果目标数组长度大于源数组长度，则只复制对应位置，剩余位置保持默认值。
Hutool还提供了重载方法，指定拷贝元素的个数：
final String[] dest = new String[3];
// ["a", null, null]
ArrayUtil.copy(new String[]{"a", "b"}, dest, 1);
# 数组去重（distinct）
数组去除有两种形式：
# 1. 直接通过equals判断去重
final String[] array = {"aa", "bb", "cc", "dd", "bb", "dd"};
// ["aa", "bb", "cc", "dd"]
final String[] distinct = ArrayUtil.distinct(array);
此示例中，bb重复，dd重复，去重后整体顺序不变。
# 2. 通过自定义规则去重
final String[] array = {"aa", "Aa", "BB", "bb"};
// 覆盖模式下，保留最后加入的两个元素
// ["Aa", "bb"]
String[] distinct = ArrayUtil.distinct(array, String::toLowerCase, true);
// 忽略模式下，保留最早加入的两个元素
// ["aa", "BB"]
distinct = ArrayUtil.distinct(array, String::toLowerCase, false);
自定义规则下多出一个override参数，主要是去重方式的策略：如果为true，加入的新值会覆盖相同key的旧值，否则会忽略新加值。即选择保留后面的值还是前面的值。
# 数组编辑和过滤（edit and filter）
ArrayUtil.edit方法通过传入一个UnaryOperator函数，可以实现自定义编辑数组中所有元素，可以实现：
- 过滤出需要的对象，如果返回
null则抛弃这个元素对象。 - 修改元素对象，返回修改后的对象。
final Integer[] a = {1, 2, 3, 4, 5, 6};
// 指定规则，偶数位的数字乘以10
// [1, 20, 3, 40, 5, 60]
final Integer[] filter = ArrayUtil.edit(a, t -> (t % 2 == 0) ? t * 10 : t);
注意，edit方法始终返回一个新的数组，原数组不变。
# 获取指定元素（get）
ArrayUtil.get方法提供通过index获取对应位置的元素，与Python类似，此方法支持负数形式的index。
final String[] a = {"a", "b", "c"};
// c
final Object o = ArrayUtil.get(a, -1);
注意：-1表示倒数第一个元素，-2表示倒数第二个元素，以此类推。
ArrayUtil.get方法同样提供重载方法，通过传入Predicate支持筛选满足指定条件的第一个元素。
final String[] a = {"a", "b", "c"};
// b
final Object o = ArrayUtil.get(a, "b"::equals);
Hutool同样提供ArrayUtil.getAny方法可以获取多个元素。
final String[] a = {"a", "b", "c", "d", "e"};
// ["d", "e"];
ArrayUtil.getAny(a, 3, 4);
# 查找元素（indexOf and lastIndexOf）
ArrayUtil.indexOf方法通过equals方式查找指定元素在数组中的位置，返回-1表示未找到。
final Integer[] a = {1, 2, 3, 4, 5, 6};
// 3的位置在第2个
// 2
final int index = ArrayUtil.indexOf(a, 3);
ArrayUtil.lastIndexOf方法通过equals方式从后向前查找指定元素在数组中的位置，返回-1表示未找到。
final Integer[] a = {1, 2, 3, 4, 3, 6};
// 4
final int index = ArrayUtil.lastIndexOf(a, 3);
ArrayUtil.contains方法通过equals方式判断数组中是否包含指定元素。
# 数组拼接为字符串（join）
ArrayUtil.join方法有多个重载，可以将数组转换为字符串，支持自定义分隔符。
final Object array2 = new String[]{"aa", "bb", "cc", "dd"};
// aa,bb,cc,dd
final String join2 = ArrayUtil.join(array2, ",");
ArrayUtil.join方法还可以通过UnaryOperator自定义数组元素转换规则，返回自定义的字符串。
final String[] array = { "java", "scala", "kotlin" };
// JAVA -> SCALA -> KOTLIN
final String result = ArrayUtil.join(array, " -> ", String::toUpperCase);
ArrayUtil.join方法还可以设置每个元素的前后缀。
final String[] array = {"aa", "bb", "cc", "dd"};
// [aa],[bb],[cc],[dd]
final String join = ArrayUtil.join(array, ",", "[", "]");
# 数组转换（map）
ArrayUtil.map和ArrayUtil.mapToXXX方法可以将数组元素转换为其它类型，支持自定义转换规则。
ArrayUtil.map参数为Object，支持原始类型数组。
final int[] a = {1, 2, 3};
// [2, 4, 6]
final Integer[] map = ArrayUtil.map(a, Integer.class, t -> (int) t * 2);
ArrayUtil.mapToXXX支持泛型数组，并通过封装Stream方式提供转换，并支持转为数组、List和Set。
final String[] keys = {"a", "b", "c"};
// [1, 1, 1]
final Integer[] integers = ArrayUtil.mapToArray(keys, String::length, Integer[]::new);
final String[] keys = {"a", "b", "c"};
// [1, 1, 1]
final List<Integer> integers = ArrayUtil.mapToList(keys, String::length);
final Object[] values = {"1", "2", "3"};
// set去重了，所以为[1]
final Set<Integer> integers = ArrayUtil.mapToSet(keys, String::length);
# 数组查找和匹配（match）
查找符合条件的第一个元素
final Integer[] array = {5, 10, 15, 20, 25};
// 20
final Integer result = ArrayUtil.firstMatch(value -> value > 15, array);
查找符合条件的第一个元素的位置
final Integer[] array = {1, 2, 3, 4, 5};
// 2
final int index = ArrayUtil.matchIndex(value -> value == 3, array);
# 查找最大值和最小值（max and min）
final int max = ArrayUtil.max(1, 2, 13, 4, 5);
final int min = ArrayUtil.min(1, 2, 13, 4, 5);
也可以自定义比较器
final BigDecimal one = new BigDecimal("1.00");
final BigDecimal two = new BigDecimal("2.0");
final BigDecimal three = new BigDecimal("3");
final BigDecimal[] bigDecimals = {two, one, three};
final BigDecimal minAccuracy = ArrayUtil.min(bigDecimals, Comparator.comparingInt(BigDecimal::scale));
final BigDecimal maxAccuracy = ArrayUtil.max(bigDecimals, Comparator.comparingInt(BigDecimal::scale));
# 数组创建（newArray）
数组创建简单封装了JDK的Array.newInstance方法，返回泛型数组。
final String[] newArray = ArrayUtil.newArray(String.class, 3);
final Object[] newArray2 = ArrayUtil.newArray(3);
# 数组转换（ofArray）
ofArray方法借助List.toArray将一个集合转换为数组，支持List、Collection以及自定义Iterable。
final List<String> list = ListUtil.of("A", "B", "C", "D");
// [A, B, C, D]
final String[] array = ArrayUtil.ofArray(list, String.class);
# 移除元素（remove）
移除指定位置的元素，生成新的数组
final String[] array = {"a", "b", "c", "d"};
// [a, c, d]
final String[] result = ArrayUtil.remove(array, 1);
移除指定的元素，如果有多个，只移除第一个
final Integer[] array = {1, 2, 3, 2, 4};
// [1, 3, 2, 4]
final Integer[] result = ArrayUtil.removeEle(array, 2);
# 数组元素替换和插入（replace or insert）
# 1. 替换
从数组中的指定位置开始，按顺序使用新元素替换旧元素，规则如下：
- 如果 指定位置 为负数，那么生成一个新数组，其中新元素按顺序放在数组头部
- 如果 指定位置 大于等于 旧数组长度，那么生成一个新数组，其中新元素按顺序放在数组尾部
- 如果 指定位置 加上 新元素数量 大于 旧数组长度，那么生成一个新数组，指定位置之前是旧数组元素，指定位置及之后为新元素
- 否则，从已有数组中的指定位置开始，按顺序使用新元素替换旧元素，返回旧数组
final String[] a = {"1", "2", "3", "4"};
final String[] b = {"a", "b", "c"};
// 在小于0的位置，相当于在a前插入b，返回b+a，新数组
String[] result = ArrayUtil.replace(a, -1, b);
assertArrayEquals(new String[]{"a", "b", "c", "1", "2", "3", "4"}, result);
// 在第0个位置开始替换，返回a
result = ArrayUtil.replace(a, 0, b);
assertArrayEquals(new String[]{"a", "b", "c", "4"}, result);
// 在第1个位置替换，即"2"开始，返回a
result = ArrayUtil.replace(a, 1, b);
assertArrayEquals(new String[]{"1", "a", "b", "c"}, result);
// 在第2个位置插入，即"3"之后
result = ArrayUtil.replace(a, 2, b);
assertArrayEquals(new String[]{"1", "2", "a", "b", "c"}, result);
// 在第3个位置插入，即"4"之后
result = ArrayUtil.replace(a, 3, b);
assertArrayEquals(new String[]{"1", "2", "3", "a", "b", "c"}, result);
// 在第4个位置插入，数组长度为4，在索引4处替换，即两个数组相加
result = ArrayUtil.replace(a, 4, b);
assertArrayEquals(new String[]{"1", "2", "3", "4", "a", "b", "c"}, result);
// 在大于3个位置插入，数组长度为4，即两个数组相加
result = ArrayUtil.replace(a, 5, b);
assertArrayEquals(new String[]{"1", "2", "3", "4", "a", "b", "c"}, result);
# 2. 插入
将新元素插入到已有数组中的某个位置，添加新元素会生成一个新的数组，不影响原数组，如果插入位置为负数，从原数组从后向前计数，若大于原数组长度，则空白处用null填充
final String[] a = {"1", "2", "3", "4"};
final String[] b = {"a", "b", "c"};
// 在-1的位置插入，相当于在3的位置插入
String[] result = ArrayUtil.insert(a, -1, b);
assertArrayEquals(new String[]{"1", "2", "3", "a", "b", "c", "4"}, result);
// 在第0个位置插入，即在数组前追加
result = ArrayUtil.insert(a, 0, b);
assertArrayEquals(new String[]{"a", "b", "c", "1", "2", "3", "4"}, result);
// 在第2个位置插入，即"3"之前
result = ArrayUtil.insert(a, 2, b);
assertArrayEquals(new String[]{"1", "2", "a", "b", "c", "3", "4"}, result);
// 在第4个位置插入，即"4"之后，相当于追加
result = ArrayUtil.insert(a, 4, b);
assertArrayEquals(new String[]{"1", "2", "3", "4", "a", "b", "c"}, result);
// 在第5个位置插入，由于数组长度为4，因此补充null
result = ArrayUtil.insert(a, 5, b);
assertArrayEquals(new String[]{"1", "2", "3", "4", null, "a", "b", "c"}, result);
# 数组长度变更（resize）
数组长度变更分为两种情况：
# 1. 长度扩大，用于添加新元素
final Integer[] originalArray = {1, 2, 3};
// [1, 2, 3, null, null]
final Integer[] resizedArray = ArrayUtil.resize(originalArray, 5);
# 2. 长度缩小，用于数组截断
final Integer[] originalArray = {1, 2, 3, 4, 5};
// [1, 2, 3]
final Integer[] resizedArray = ArrayUtil.resize(originalArray, 3);
# 数组反转（reverse）
final int[] a = {1, 2, 3, 4};
// [4, 3, 2, 1]
final int[] reverse = ArrayUtil.reverse(a);
# 数组顺序打乱（shuffle）
此方法用于打乱数组元素的顺序，使用Fisher–Yates洗牌算法
final Integer[] initialArray = new Integer[]{0, 1, 2, 3, 4, 5, 6, 7, 8, 9};
// 需要注意，这里使用clone，因为此方法会修改原数组
final Integer[] shuffledArray = ArrayUtil.shuffle(initialArray.clone());
# 数组截取（sub）
# 1.sub方法
JDK中，提供了Arrays.copyOfRange方法，用于截取字符串，Hutool对此方法做了进一步封装。
String[] strArray = {"a", "b", "c", "d", "e"};
// ["b", "c", "d"]
ArrayUtil.sub(strArray, 1, 4);
其中1是起始位置（包含），从0计数，即从b开始，4是结束位置（不包含），即e之前。
sub方法同时支持负数形式，如：
// ["b", "c", "d"]
ArrayUtil.sub(strArray, 1, -1);
其中-1表示倒数第一个元素，即从e的前面。
同样，sub方法支持传入一个step参数，表示步长，可以实现每隔几个元素截取一次。
String[] array = {"a", "b", "c", "d", "e", "f", "g"};
// 步进为2（隔一个取一个）
// ["a", "c", "e", "g"]
String[] step2 = ArrayUtil.sub(array, 0, 7, 2);
// 步进为3（隔两个取一个）
// ["a", "d", "g"]
String[] step3 = ArrayUtil.sub(array, 0, 7, 3);
# 2. isSub方法
判断一个数组是否为另一个数组的子集，即前者包含后者所有元素，要求顺序一致。
ArrayUtil.isSub(new Integer[]{1, 2, 3, 4, 5}, new Integer[]{1, 2})
# 3. indexOfSub方法
查找子数组在父数组中的起始位置，即返回第一个匹配的索引。
// 1
ArrayUtil.indexOfSub(new String[]{"a", "b", "c", "d"}, new String[]{"b", "c"});
# 元素交换（swap）
有时候我们需要交换数组中的两个元素，可以使用swap方法。
String[] array = {"a", "b", "c", "d"};
// 交换位置1和2的元素
// ["a", "c", "b", "d"]
String[] swapped = ArrayUtil.swap(array, 1, 2);
注意：此方法会修改原数组。
# 数据和元素类型（type）
我们可以通过getComponentType方法获取数组的元素类型。
// 获取数组的元素类型、
// class java.lang.String
Class<?> type = ArrayUtil.getComponentType(new String[]{"a", "b", "c"});
同样，我们也可以通过getArrayType获取指定元素对应的数组类型。
// int[].class
Class<?> arrayType = ArrayUtil.getArrayType(int.class);
对于数组元素类型已知，但是数组类型不同的情况下，我们可以强制转换数组类型：
Object[] values = {"1", "2", "3"};
String[] cast = (String[]) ArrayUtil.cast(String.class, values);
# 元素映射（zip）
如果你对Python熟悉，那么zip方法一定不陌生，Hutool提供了类似的实现。
Hutool中zip方法可以将两个数组映射为键值对，即第一个数组的元素为key，第二个数组的元素为value。
String[] keys = {"a", "b", "c"};
Integer[] values = {1, 2, 3};
// {a=1, b=2, c=3}
Map<String, Integer> map = ArrayUtil.zip(keys, values, true);