1. Overview

1.概述

The Apache Commons Lang 3 library provides support for manipulation of core classes of the Java APIs. This support includes methods for handling strings, numbers, dates, concurrency, object reflection and more.

Apache Commons Lang 3库为操作Java APIs的核心类提供支持。这种支持包括用于处理字符串、数字、日期、并发、对象反射等的方法。

In this quick tutorial, we’ll focus on array processing with the very useful ArrayUtils utility class.

在这个快速教程中，我们将专注于用非常有用的ArrayUtils工具类进行数组处理。

2. Maven Dependency

2.Maven的依赖性

In order to use the Commons Lang 3 library, just pull it from the central Maven repository using the following dependency:

为了使用Commons Lang 3库，只需使用以下依赖关系从Maven中心仓库拉取即可。

<dependency>
    <groupId>org.apache.commons</groupId>
    <artifactId>commons-lang3</artifactId>
    <version>3.12.0</version>
</dependency>

You can find the latest version of this library here.

你可以找到这个库的最新版本这里。

3. ArrayUtils

3.ArrayUtils

The ArrayUtils class provides utility methods for working with arrays. These methods try to handle the input gracefully by preventing an exception from being thrown when a null value is passed in.

ArrayUtils类提供了用于处理数组的实用方法。这些方法试图通过防止在传入null值时抛出异常来优雅地处理输入。

This section illustrates some methods defined in the ArrayUtils class. Note that all of these methods can work with any element type.

本节说明了在ArrayUtils类中定义的一些方法。请注意，所有这些方法都可以对任何元素类型起作用。

For convenience, their overloaded flavors are also defined for handling arrays containing primitive types.

为了方便起见，它们的重载风味也被定义为处理包含原始类型的数组。

4. add and addAll

4、add和addAll

The add method copies a given array and inserts a given element at a given position in the new array. If the position is not specified, the new element is added at the end of the array.

add方法复制一个给定的数组，并在新数组的指定位置插入一个指定的元素。如果没有指定位置，新元素将被添加到数组的末端。

The following code fragment inserts the number zero at the first position of the oldArray array and verifies the result:

下面的代码片段在oldArray数组的第一个位置插入数字0，并验证了结果。

int[] oldArray = { 2, 3, 4, 5 };
int[] newArray = ArrayUtils.add(oldArray, 0, 1);
int[] expectedArray = { 1, 2, 3, 4, 5 };
 
assertArrayEquals(expectedArray, newArray);

If the position is not specified, the additional element is added at the end of oldArray:

如果没有指定位置，额外的元素将被添加到oldArray的最后。

int[] oldArray = { 2, 3, 4, 5 };
int[] newArray = ArrayUtils.add(oldArray, 1);
int[] expectedArray = { 2, 3, 4, 5, 1 };
 
assertArrayEquals(expectedArray, newArray);

The addAll method adds all elements at the end of a given array. The following fragment illustrates this method and confirms the result:

addAll方法在给定数组的末尾添加所有元素。下面的片段说明了这个方法并确认了其结果。

int[] oldArray = { 0, 1, 2 };
int[] newArray = ArrayUtils.addAll(oldArray, 3, 4, 5);
int[] expectedArray = { 0, 1, 2, 3, 4, 5 };
 
assertArrayEquals(expectedArray, newArray);

5. remove and removeAll

5.remove和removeAll

The remove method removes an element at a specified position from a given array. All subsequent elements are shifted to the left. Note that this is true for all removal operations.

remove方法从一个给定的数组中的指定位置移除一个元素。所有后续的元素都被移到左边。请注意，这对所有的移除操作都是真实的。

This method returns a new array instead of making changes to the original one:

该方法返回一个新的数组，而不是对原数组进行修改。

int[] oldArray = { 1, 2, 3, 4, 5 };
int[] newArray = ArrayUtils.remove(oldArray, 1);
int[] expectedArray = { 1, 3, 4, 5 };
 
assertArrayEquals(expectedArray, newArray);

The removeAll method removes all elements at specified positions from a given array:

removeAll方法从一个给定的数组中移除指定位置的所有元素。

int[] oldArray = { 1, 2, 3, 4, 5 };
int[] newArray = ArrayUtils.removeAll(oldArray, 1, 3);
int[] expectedArray = { 1, 3, 5 };
 
assertArrayEquals(expectedArray, newArray);

6. removeElement and removeElements

6.removeElement和removeElements

The removeElement method removes the first occurrence of a specified element from a given array.

removeElement方法从一个给定的数组中移除第一次出现的指定元素。

Instead of throwing an exception, the removal operation is ignored if such an element does not exist in the given array:

如果在给定的数组中不存在这样的元素，删除操作将被忽略，而不是抛出一个异常。

int[] oldArray = { 1, 2, 3, 3, 4 };
int[] newArray = ArrayUtils.removeElement(oldArray, 3);
int[] expectedArray = { 1, 2, 3, 4 };
 
assertArrayEquals(expectedArray, newArray);

The removeElements method removes the first occurrences of specified elements from a given array.

removeElements方法从一个给定的数组中移除第一次出现的指定元素。

Instead of throwing an exception, the removal operation is ignored if a specified element does not exist in the given array:

如果指定的元素不存在于给定的数组中，移除操作将被忽略，而不是抛出一个异常。

int[] oldArray = { 1, 2, 3, 3, 4 };
int[] newArray = ArrayUtils.removeElements(oldArray, 2, 3, 5);
int[] expectedArray = { 1, 3, 4 };
 
assertArrayEquals(expectedArray, newArray);

**7. The removeAllOccurences API**

**7、removeAllOccurences API**

The removeAllOccurences method removes all occurrences of the specified element from the given array.

removeAllOccurences方法从给定的数组中移除所有指定元素的出现。

Instead of throwing an exception, the removal operation is ignored if such an element does not exist in the given array:

如果在给定的数组中不存在这样的元素，删除操作将被忽略，而不是抛出一个异常。

int[] oldArray = { 1, 2, 2, 2, 3 };
int[] newArray = ArrayUtils.removeAllOccurences(oldArray, 2);
int[] expectedArray = { 1, 3 };
 
assertArrayEquals(expectedArray, newArray);

**8. The contains API**

8、包含 API

The contains method checks if a value exists in a given array. Here is a code example, including verification of the result:

contains方法检查一个值是否存在于一个给定的数组中。下面是一个代码例子，包括对结果的验证。

int[] array = { 1, 3, 5, 7, 9 };
boolean evenContained = ArrayUtils.contains(array, 2);
boolean oddContained = ArrayUtils.contains(array, 7);
 
assertEquals(false, evenContained);
assertEquals(true, oddContained);

**9. The reverse API**

9.反向 API

The reverse method reverses the element order within a specified range of a given array. This method makes changes to the passed-in array instead of returning a new one.

reverse方法在给定数组的指定范围内颠倒元素顺序。这个方法会对传入的数组进行修改，而不是返回一个新的数组。

Let’s have a look at a quick:

让我们来看看一个快速。

int[] originalArray = { 1, 2, 3, 4, 5 };
ArrayUtils.reverse(originalArray, 1, 4);
int[] expectedArray = { 1, 4, 3, 2, 5 };
 
assertArrayEquals(expectedArray, originalArray);

If a range is not specified, the order of all elements is reversed:

如果没有指定范围，所有元素的顺序将被颠倒。

int[] originalArray = { 1, 2, 3, 4, 5 };
ArrayUtils.reverse(originalArray);
int[] expectedArray = { 5, 4, 3, 2, 1 };
 
assertArrayEquals(expectedArray, originalArray);

**10. The shift API**

10.shift API

The shift method shifts a series of elements in a given array a number of positions. This method makes changes to the passed-in array instead of returning a new one.

shift方法将给定数组中的一系列元素移动若干个位置。这个方法会对传入的数组进行修改，而不是返回一个新的数组。

The following code fragment shifts all elements between the elements at index 1 (inclusive) and index 4 (exclusive) one position to the right and confirms the result:

下面的代码片段将索引1（包括）和索引4（不包括）之间的所有元素向右移动一个位置并确认结果。

int[] originalArray = { 1, 2, 3, 4, 5 };
ArrayUtils.shift(originalArray, 1, 4, 1);
int[] expectedArray = { 1, 4, 2, 3, 5 };
 
assertArrayEquals(expectedArray, originalArray);

If the range boundaries are not specified, all elements of the array are shifted:

如果没有指定范围边界，数组的所有元素都会被移位。

int[] originalArray = { 1, 2, 3, 4, 5 };
ArrayUtils.shift(originalArray, 1);
int[] expectedArray = { 5, 1, 2, 3, 4 };
 
assertArrayEquals(expectedArray, originalArray);

**11. The subarray API**

11.subarray API

The subarray method creates a new array containing elements within a specified range of the given array. The following is an example of an assertion of the result:

subarray方法创建一个新的数组，包含在给定数组指定范围内的元素。下面是一个关于结果断言的例子。

int[] oldArray = { 1, 2, 3, 4, 5 };
int[] newArray = ArrayUtils.subarray(oldArray, 2, 7);
int[] expectedArray = { 3, 4, 5 };
 
assertArrayEquals(expectedArray, newArray);

Notice that when the passed-in index is greater than the length of the array, it is demoted to the array length rather than having the method throw an exception. Similarly, if a negative index is passed in, it is promoted to zero.

请注意，当传入的索引大于数组的长度时，它被降级为数组的长度，而不是让该方法抛出一个异常。同样，如果传入一个负的索引，它将被提升为零。

**12. The swap API**

12.swap API

The swap method swaps a series of elements at specified positions in the given array.

swap方法在给定的数组中的指定位置交换一系列的元素。

The following code fragment swaps two groups of elements starting at the indexes 0 and 3, with each group containing two elements:

下面的代码片段交换了两组从索引0和3开始的元素，每组包含两个元素。

int[] originalArray = { 1, 2, 3, 4, 5 };
ArrayUtils.swap(originalArray, 0, 3, 2);
int[] expectedArray = { 4, 5, 3, 1, 2 };
 
assertArrayEquals(expectedArray, originalArray);

If no length argument is passed in, only one element at each position is swapped:

如果没有传入长度参数，每个位置上只有一个元素被交换。

int[] originalArray = { 1, 2, 3, 4, 5 };
ArrayUtils.swap(originalArray, 0, 3);
int[] expectedArray = { 4, 2, 3, 1, 5 };
assertArrayEquals(expectedArray, originalArray);

13. Conclusion

13.结论

This tutorial introduces the core array processing utility in Apache Commons Lang 3 – ArrayUtils.

本教程介绍了Apache Commons Lang 3的核心数组处理工具–ArrayUtils。

As always, the implementation of all examples and code snippets given above can be found in the GitHub project.

一如既往，上面给出的所有例子和代码片段的实现都可以在GitHub项目中找到。