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[] a1, java.lang.Object[] a2) Concatenates two arrays into a new array, handling null values.
static <R,A extends R,B extends R> R[]	concatTypedArrays(java.lang.Class<R> componentType, A[] a1, B[] a2) Concatenates two typed arrays into a new array, handling null values.
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.

This method combines the elements of two arrays (a1 and a2) into a new array. If both input arrays are null, an empty array is returned. The order of the elements in the new array is the same as in the input arrays: elements from a1 first, followed by elements from a2.

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.

concatTypedArrays

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

Concatenates two typed arrays into a new array, handling null values.

This method combines the elements of two typed arrays (a1 and a2) into a new array. If both input arrays are null, an empty array of the specified component type is returned. The order of the elements in the new array is the same as in the input arrays: elements from a1 first, followed by elements from a2.

Type Parameters:

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

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

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

Parameters:

componentType - The component type of the resulting array.

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 of the specified component type if both input arrays are null or empty.

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".