1. Overview
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.
In this quick tutorial, we’ll focus on array processing with the very useful ArrayUtils utility class.
2. Maven Dependency
In order to use the Commons Lang 3 library, just pull it from the central Maven repository using the following dependency:
<dependency>
<groupId>org.apache.commons</groupId>
<artifactId>commons-lang3</artifactId>
<version>3.5</version>
</dependency>
You can find the latest version of this library here.
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.
This section illustrates some methods defined in the ArrayUtils class. Note that all of these methods can work with any element type.
For convenience, their overloaded flavors are also defined for handling arrays containing primitive types.
4. add and 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.
The following code fragment inserts the number zero at the first position of the oldArray array and verifies the result:
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:
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:
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
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.
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:
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
The removeElement method removes the first occurrence of a specified element from a given array.
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.
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
The removeAllOccurences method removes all occurrences of the specified element from the given array.
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
The contains method checks if a value exists in a given array. Here is a code example, including verification of the result:
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
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.
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
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.
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:
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
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:
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
The swap method swaps a series of elements at specified positions in the given array.
The following code fragment swaps two groups of elements starting at the indexes 0 and 3, with each group containing two elements:
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
This tutorial introduces the core array processing utility in Apache Commons Lang 3 – ArrayUtils.
As always, the implementation of all examples and code snippets given above can be found in the GitHub project.