de.ipcon.tools

Class ArrayTools

java.lang.Object

de.ipcon.tools.ArrayTools

public final class ArrayTools
extends java.lang.Object

Utility class providing methods for working with arrays in a null-safe manner.

Constructor Summary

Constructors

Constructor and Description
ArrayTools()

Method Summary

Modifier and Type	Method and Description
static java.lang.Object[]	concatArrays(java.lang.Object[]... arrays) Concatenates an arbitrary number of arrays into a new array, handling null and empty arrays.
static java.lang.Object[]	concatArrays(java.lang.Object[] a1, java.lang.Object[] a2) Concatenates two arrays into a new array, handling null values.
static java.lang.Object[]	concatArrays(java.lang.Object[] a1, java.lang.Object[] a2, java.lang.Object[] a3) Concatenates three arrays into a new array, handling null values.
static <R,T extends R> R[]	concatTypedArrays(java.lang.Class<R> componentType, T[]... arrays) Concatenates an arbitrary number of arrays into a new typed array, handling null and empty arrays with optimization checks.
static int	findInsertionIndex(int[] sortedArray, IntIndexComparator comparator, int valueToInsert) Finds the index at which an additional value needs to be inserted into a sorted integer array to maintain the sorted order according to the given comparator.
static int	findInsertionIndex(int[] sortedArray, int length, IntIndexComparator comparator, int valueToInsert) Finds the index at which an additional value needs to be inserted into a sorted integer array to maintain the sorted order according to the given comparator, within a specified effective length.
static int	lastIndexOf(byte[] what, byte[] within) Finds the last occurrence of the specified byte array within the given byte array, searching backward from the end.
static int	lastIndexOf(byte[] what, byte[] within, int fromIndex) Finds the last occurrence of the specified byte array within the given byte array, searching backward from the specified index.
static java.lang.Object[]	mergeArrays(java.lang.Object[] a1, java.lang.Object[] a2) Merges two arrays of objects into a new array with duplicates removed, preserving the order of the first occurrence of each element.
static <R,A extends R,B extends R> R[]	mergeTypedArrays(java.lang.Class<R> componentType, A[] a1, B[] a2) Merges two typed arrays into a new array with duplicates removed, preserving the order of the first occurrence of each element.
static java.lang.Object[]	removeArrayMemberAtIndex(java.lang.Object[] a, int i) Returns a new Object array without the element at the specified position, by copying the given Object array into a new Object array without the element at the specified position.
static java.lang.Object	removeTypedArrayMemberAtIndex(java.lang.Object a, int i) Similar to removeArrayMemberAtIndex(java.lang.Object[], int), but with Object parameter and return type to be casted to the correct array type.

Methods inherited from class java.lang.Object

equals, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Constructor Detail

ArrayTools

public ArrayTools()

Method Detail

concatArrays

public static java.lang.Object[] concatArrays(java.lang.Object[] a1,
                                              java.lang.Object[] a2)

Concatenates two arrays into a new array, handling null values. Mainly for calls from NetRexx, which does not support varargs.

This method combines the elements of two arrays (a1 and a2) into a new array. It is implemented as a convenience wrapper around the varargs method concatArrays(Object[][]) for two arguments.

Parameters:

a1 - The first array. May be null.

a2 - The second array. May be null.

Returns:

A new array containing all the elements from a1 and a2, or an empty array if both input arrays are null or empty.

concatArrays

public static java.lang.Object[] concatArrays(java.lang.Object[] a1,
                                              java.lang.Object[] a2,
                                              java.lang.Object[] a3)

Concatenates three arrays into a new array, handling null values. Mainly for calls from NetRexx, which does not support varargs.

This method filters all null or empty arrays and then delegates the remaining inputs to the optimized varargs method, avoiding ambiguous varargs calls for single- and zero-array cases.

Parameters:

a1 - The first array. May be null.

a2 - The second array. May be null.

a3 - The third array. May be null.

Returns:

A new array containing all the elements from a1, a2, and a3, or the single non-null input array itself (if applicable), or an empty array.

concatArrays

public static java.lang.Object[] concatArrays(java.lang.Object[]... arrays)

Concatenates an arbitrary number of arrays into a new array, handling null and empty arrays.

This method combines the elements of all input arrays into a single new array. If zero or one non-null array is provided, no new array is created; the single input array (or an empty array) is returned directly, ensuring optimization. The order of elements is preserved based on the order of the input arrays.

Parameters:

arrays - An arbitrary number of Object arrays. May contain nulls.

Returns:

A new array containing all elements from the input arrays, or the single non-null input array itself (for optimization), or an empty array.

concatTypedArrays

@SafeVarargs
public static <R,T extends R> R[] concatTypedArrays(java.lang.Class<R> componentType,
                                                                 T[]... arrays)

Concatenates an arbitrary number of arrays into a new typed array, handling null and empty arrays with optimization checks.

Type Parameters:

R - The type of the elements in the resulting array.

T - The common super-type of all input array elements (typically R).

Parameters:

componentType - The component type of the resulting array (R).

arrays - An arbitrary number of input arrays, whose element types must be subtypes of R. May contain nulls.

Returns:

A new array containing all elements, or an optimized single input array, or an empty array.

mergeArrays

public static final java.lang.Object[] mergeArrays(java.lang.Object[] a1,
                                                   java.lang.Object[] a2)

Merges two arrays of objects into a new array with duplicates removed, preserving the order of the first occurrence of each element.

Parameters:

a1 - the first array

a2 - the second array

Returns:

a new array containing all the unique elements of a1 and a2 in their original order

mergeTypedArrays

public static <R,A extends R,B extends R> R[] mergeTypedArrays(java.lang.Class<R> componentType,
                                                               A[] a1,
                                                               B[] a2)

Merges two typed arrays into a new array with duplicates removed, preserving the order of the first occurrence of each element.

This method combines the elements of two arrays (a1 and a2) into a new array, ensuring that only unique elements are included. The order of the elements in the new array is determined by their first occurrence in either of the input arrays. The component type of the arrays is specified by the componentType parameter.

Type Parameters:

R - The type of the elements in the arrays.

A - The type of the first array, which must be a subtype of R.

B - The type of the second array, which must be a subtype of R.

Parameters:

componentType - The component type of the arrays.

a1 - The first array.

a2 - The second array.

Returns:

A new array containing all the unique elements of a1 and a2 in their original order.

lastIndexOf

public static final int lastIndexOf(byte[] what,
                                    byte[] within)

Finds the last occurrence of the specified byte array within the given byte array, searching backward from the end. If the target byte array is empty, the last index of the array is returned.

Parameters:

what - The byte array to search for.

within - The byte array to search within.

Returns:

The index of the last occurrence of the target byte array, or -1 if not found.

lastIndexOf

public static final int lastIndexOf(byte[] what,
                                    byte[] within,
                                    int fromIndex)

Finds the last occurrence of the specified byte array within the given byte array, searching backward from the specified index. If the target byte array is empty, the specified index is returned.

Parameters:

what - The byte array to search for.

within - The byte array to search within.

fromIndex - The index to start the backward search from.

Returns:

The index of the last occurrence of the target byte array, or -1 if not found.

removeArrayMemberAtIndex

public static final java.lang.Object[] removeArrayMemberAtIndex(java.lang.Object[] a,
                                                                int i)

Returns a new Object array without the element at the specified position, by copying the given Object array into a new Object array without the element at the specified position. The new Object array will have a length of a.length - 1, and the original array will be left untouched.

Parameters:

a - The Object array to remove the element from.

i - The element position to remove.

Returns:

The new Object array without the element at the specified position.

Throws:

java.lang.IllegalArgumentException - If the given array is null.

java.lang.ArrayIndexOutOfBoundsException - If the given element position is out of bounds.

removeTypedArrayMemberAtIndex

public static final java.lang.Object removeTypedArrayMemberAtIndex(java.lang.Object a,
                                                                   int i)

Similar to removeArrayMemberAtIndex(java.lang.Object[], int), but with Object parameter and return type to be casted to the correct array type.

Parameters:

a - The Object array to remove the element from.

i - The element position to remove.

Returns:

The new Object array without the element at the specified position.

Throws:

java.lang.IllegalArgumentException - If the given array is null.

java.lang.ArrayIndexOutOfBoundsException - If the given element position is out of bounds.

findInsertionIndex

public static final int findInsertionIndex(int[] sortedArray,
                                           IntIndexComparator comparator,
                                           int valueToInsert)

Finds the index at which an additional value needs to be inserted into a sorted integer array to maintain the sorted order according to the given comparator.

This method performs a binary search to find the first index "i" such that comparator.compare(valueToInsert, sortedArray[i]) <= 0. If no such element exists (i.e. valueToInsert is greater than all elements in the array), it returns the array's length, indicating insertion at the end.

Parameters:

sortedArray - The array, which must be sorted according to the provided comparator. If null, an IllegalArgumentException is thrown.

comparator - The IntIndexComparator used to define the sorting order of the array. If null, an IllegalArgumentException is thrown.

valueToInsert - The integer value to find the insertion index for.

Returns:

The index where the value should be inserted to maintain sorted order.

Throws:

java.lang.IllegalArgumentException - if sortedArray or comparator is null.

findInsertionIndex

public static final int findInsertionIndex(int[] sortedArray,
                                           int length,
                                           IntIndexComparator comparator,
                                           int valueToInsert)

Finds the index at which an additional value needs to be inserted into a sorted integer array to maintain the sorted order according to the given comparator, within a specified effective length.

This method performs a binary search to find the first index "i" such that comparator.compare(valueToInsert, sortedArray[i]) <= 0. If no such element exists within the specified "length" (i.e. valueToInsert is greater than all elements up to "length - 1"), it returns "length", indicating insertion at the end of the effective range.

Parameters:

sortedArray - The array, which must be sorted according to the provided comparator. If null, an IllegalArgumentException is thrown.

length - The effective length of the sorted portion of the array to consider for the binary search. Must not be larger than the length of the passed "sortedArray".

comparator - The IntIndexComparator used to define the sorting order of the array. If null, an IllegalArgumentException is thrown.

valueToInsert - The integer value to find the insertion index for.

Returns:

The index where the value should be inserted to maintain sorted order within the given length.

Throws:

java.lang.IllegalArgumentException - if sortedArray or comparator is null, or if "length" is greater than "sortedArray.length".