Package org.apache.sis.util

# Class ArraysExt

Object
Static
ArraysExt

public final class ArraysExt extends Static
Static methods for simple operations on arrays and array elements. This is an extension to the standard `Arrays` utility class. Some worthy methods are:

- The `resize` methods, which are very similar to the `Arrays​.copyOf(…)` methods except that they accept `null` arrays and do not copy anything if the given array already has the requested length.
- The `insert` and `remove` methods for adding and removing elements in the middle of an array.
- The `isSorted` methods for verifying if an array is sorted, strictly or not.

## Handling of null values

Many (but not all) methods in this class are tolerant to null parameter values, sometime under certain conditions. See the method javadoc for details.

All methods in this class are tolerant to null elements in arrays. Null and NaN elements are ignored.

## Performance consideration

The methods listed below are provided as convenience for casual use on small arrays. For large arrays or for frequent use, consider using the Java collection framework instead.

Convenience methods for casual use on small arrays
Method | Alternative
--- | ---
`resize(Object[], int)` | `ArrayList`
`append(Object[], Object)` | `ArrayList`
`insert(Object[], int, Object[], int, int)` | `LinkedList`
`remove(Object[], int, int)` | `LinkedList`
`intersects(Object[], Object[])` | `HashSet`
`contains(Object[], Object)` | `HashSet`
`containsIdentity(Object[], Object)` | `IdentityHashMap`

Note that this recommendation applies mostly to arrays of objects. It may not apply to arrays of primitive types, since as of JDK7 the collection framework wraps every primitive types in objects.

Since:
  0.3
See Also:
  - `Arrays`

Defined in the `sis-utility` module

- ## Field Summary

  Fields
  Modifier and Type
  Field
  Description
  `static final boolean[]`
  `EMPTY_BOOLEAN`
  An empty array of `boolean` primitive type.
  `static final byte[]`
  `EMPTY_BYTE`
  An empty array of `byte` primitive type.
  `static final char[]`
  `EMPTY_CHAR`
  An empty array of `char` primitive type.
  `static final double[]`
  `EMPTY_DOUBLE`
  An empty array of `double` primitive type.
  `static final float[]`
  `EMPTY_FLOAT`
  An empty array of `float` primitive type.
  `static final int[]`
  `EMPTY_INT`
  An empty array of `int` primitive type.
  `static final long[]`
  `EMPTY_LONG`
  An empty array of `long` primitive type.
  `static final short[]`
  `EMPTY_SHORT`
  An empty array of `short` primitive type.

- ## Method Summary

  Modifier and Type
  Method
  Description
  `static boolean`
  `allEquals(double[] array, double value)`
  Returns `true` if all values in the specified array are equal to the specified value, which may be `Double​.NaN`.
  `static boolean`
  `allEquals(float[] array, float value)`
  Returns `true` if all values in the specified array are equal to the specified value, which may be `Float​.NaN`.
  `static boolean`
  `allEquals(Object[] array, Object value)`
  Returns `true` if all values in the specified array are equal to the specified value, which may be `null`.
  `static <T> T[]`
  `append(T[] array, T element)`
  Returns a copy of the given array with a single element appended at the end.
  `static <T> T[]`
  `concatenate(T[]... arrays)`
  Returns the concatenation of all given arrays.
  `static boolean`
  `contains(Object[] array, Object value)`
  Returns `true` if the specified array contains the specified value.
  `static boolean`
  `containsIdentity(Object[] array, Object value)`
  Returns `true` if the specified array contains the specified reference.
  `static boolean`
  `containsIgnoreCase(String[] array, String value)`
  Returns `true` if the specified array contains the specified value, ignoring case.
  `static float[]`
  `copyAsFloats(double[] data)`
  Returns a copy of the given array where each value has been casted to the `float` type.
  `static float[]`
  `copyAsFloatsIfLossless(double[] data)`
  Returns a copy of the given array where each value has been casted to the `float` type, but only if all casts are lossless.
  `static long[]`
  `copyAsLongs(int[] data)`
  Returns a copy of the given array where each value has been casted to the `long` type.
  `static boolean`
  `hasNaN(double[] array)`
  Returns `true` if the specified array contains at least one `NaN` value.
  `static boolean`
  `hasNaN(float[] array)`
  Returns `true` if the specified array contains at least one `NaN` value.
  `static boolean[]`
  `insert(boolean[] src, int srcOff, boolean[] dst, int dstOff, int length)`
  Returns an array containing the same elements than the given array, with the content of an other array inserted at the given index.
  `static boolean[]`
  `insert(boolean[] array, int first, int length)`
  Returns an array containing the same elements than the given array, with additional "spaces" in the given range.
  `static byte[]`
  `insert(byte[] src, int srcOff, byte[] dst, int dstOff, int length)`
  Returns an array containing the same elements than the given array, with the content of an other array inserted at the given index.
  `static byte[]`
  `insert(byte[] array, int first, int length)`
  Returns an array containing the same elements than the given array, with additional "spaces" in the given range.
  `static char[]`
  `insert(char[] src, int srcOff, char[] dst, int dstOff, int length)`
  Returns an array containing the same elements than the given array, with the content of an other array inserted at the given index.
  `static char[]`
  `insert(char[] array, int first, int length)`
  Returns an array containing the same elements than the given array, with additional "spaces" in the given range.
  `static double[]`
  `insert(double[] src, int srcOff, double[] dst, int dstOff, int length)`
  Returns an array containing the same elements than the given array, with the content of an other array inserted at the given index.
  `static double[]`
  `insert(double[] array, int first, int length)`
  Returns an array containing the same elements than the given array, with additional "spaces" in the given range.
  `static float[]`
  `insert(float[] src, int srcOff, float[] dst, int dstOff, int length)`
  Returns an array containing the same elements than the given array, with the content of an other array inserted at the given index.
  `static float[]`
  `insert(float[] array, int first, int length)`
  Returns an array containing the same elements than the given array, with additional "spaces" in the given range.
  `static int[]`
  `insert(int[] array, int first, int length)`
  Returns an array containing the same elements than the given array, with additional "spaces" in the given range.
  `static int[]`
  `insert(int[] src, int srcOff, int[] dst, int dstOff, int length)`
  Returns an array containing the same elements than the given array, with the content of an other array inserted at the given index.
  `static long[]`
  `insert(long[] array, int first, int length)`
  Returns an array containing the same elements than the given array, with additional "spaces" in the given range.
  `static long[]`
  `insert(long[] src, int srcOff, long[] dst, int dstOff, int length)`
  Returns an array containing the same elements than the given array, with the content of an other array inserted at the given index.
  `static short[]`
  `insert(short[] array, int first, int length)`
  Returns an array containing the same elements than the given array, with additional "spaces" in the given range.
  `static short[]`
  `insert(short[] src, int srcOff, short[] dst, int dstOff, int length)`
  Returns an array containing the same elements than the given array, with the content of an other array inserted at the given index.
  `static <E> E[]`
  `insert(E[] array, int first, int length)`
  Returns an array containing the same elements than the given array, with additional "spaces" in the given range.
  `static <E> E[]`
  `insert(E[] src, int srcOff, E[] dst, int dstOff, int length)`
  Returns an array containing the same elements than the given array, with the content of an other array inserted at the given index.
  `static boolean`
  `intersects(Object[] array1, Object[] array2)`
  Returns `true` if at least one element in the first array is equals to an element in the second array.
  `static boolean`
  `isRange(int start, int[] array)`
  Returns `true` if the given array is a finite arithmetic progression starting at the given value and having a common difference of 1.
  `static boolean`
  `isSinglePrecision(double... values)`
  Returns `true` if every values in the given `double` array could be casted to the `float` type without data lost.
  `static boolean`
  `isSorted(byte[] array, boolean strict)`
  Returns `true` if all elements in the specified array are in increasing order.
  `static boolean`
  `isSorted(char[] array, boolean strict)`
  Returns `true` if all elements in the specified array are in increasing order.
  `static boolean`
  `isSorted(double[] array, boolean strict)`
  Returns `true` if all elements in the specified array are in increasing order.
  `static boolean`
  `isSorted(float[] array, boolean strict)`
  Returns `true` if all elements in the specified array are in increasing order.
  `static boolean`
  `isSorted(int[] array, boolean strict)`
  Returns `true` if all elements in the specified array are in increasing order.
  `static boolean`
  `isSorted(long[] array, boolean strict)`
  Returns `true` if all elements in the specified array are in increasing order.
  `static boolean`
  `isSorted(short[] array, boolean strict)`
  Returns `true` if all elements in the specified array are in increasing order.
  `static <E extends Comparable<? super E>>
  boolean`
  `isSorted(E[] array, boolean strict)`
  Returns `true` if all elements in the specified array are in increasing order.
  `static <E> boolean`
  `isSorted(E[] array, Comparator<? super E> comparator, boolean strict)`
  Returns `true` if all elements in the specified array are in increasing order.
  `static int[]`
  `range(int start, int end)`
  Returns the ordered values in the range from `start` inclusive to `end` exclusive.
  `static boolean[]`
  `remove(boolean[] array, int first, int length)`
  Returns an array containing the same elements than the given array except for the given range.
  `static byte[]`
  `remove(byte[] array, int first, int length)`
  Returns an array containing the same elements than the given array except for the given range.
  `static char[]`
  `remove(char[] array, int first, int length)`
  Returns an array containing the same elements than the given array except for the given range.
  `static double[]`
  `remove(double[] array, int first, int length)`
  Returns an array containing the same elements than the given array except for the given range.
  `static float[]`
  `remove(float[] array, int first, int length)`
  Returns an array containing the same elements than the given array except for the given range.
  `static int[]`
  `remove(int[] array, int first, int length)`
  Returns an array containing the same elements than the given array except for the given range.
  `static long[]`
  `remove(long[] array, int first, int length)`
  Returns an array containing the same elements than the given array except for the given range.
  `static short[]`
  `remove(short[] array, int first, int length)`
  Returns an array containing the same elements than the given array except for the given range.
  `static <E> E[]`
  `remove(E[] array, int first, int length)`
  Returns an array containing the same elements than the given array except for the given range.
  `static int`
  `removeDuplicated(Object[] array)`
  Removes the duplicated elements in the given array.
  `static void`
  `replace(double[] array, double search, double replacement)`
  Replaces all occurrences of the given value by the given replacement.
  `static void`
  `replace(float[] array, float search, float replacement)`
  Replaces all occurrences of the given value by the given replacement.
  `static boolean[]`
  `resize(boolean[] array, int length)`
  Returns an array containing the same elements as the given `array` but specified `length`, truncating or padding with `false` if necessary.
  `static byte[]`
  `resize(byte[] array, int length)`
  Returns an array containing the same elements as the given `array` but specified `length`, truncating or padding with zeros if necessary.
  `static char[]`
  `resize(char[] array, int length)`
  Returns an array containing the same elements as the given `array` but specified `length`, truncating or padding with zeros if necessary.
  `static double[]`
  `resize(double[] array, int length)`
  Returns an array containing the same elements as the given `array` but specified `length`, truncating or padding with zeros if necessary.
  `static float[]`
  `resize(float[] array, int length)`
  Returns an array containing the same elements as the given `array` but specified `length`, truncating or padding with zeros if necessary.
  `static int[]`
  `resize(int[] array, int length)`
  Returns an array containing the same elements as the given `array` but specified `length`, truncating or padding with zeros if necessary.
  `static long[]`
  `resize(long[] array, int length)`
  Returns an array containing the same elements as the given `array` but specified `length`, truncating or padding with zeros if necessary.
  `static short[]`
  `resize(short[] array, int length)`
  Returns an array containing the same elements as the given `array` but specified `length`, truncating or padding with zeros if necessary.
  `static <E> E[]`
  `resize(E[] array, int length)`
  Returns an array containing the same elements as the given `array` but with the specified `length`, truncating or padding with `null` if necessary.
  `static void`
  `reverse(int[] values)`
  Reverses the order of elements in the given array.
  `static void`
  `reverse(Object[] entries)`
  Reverses the order of elements in the given array.
  `static void`
  `swap(byte[] data, int i0, int i1)`
  Swaps the elements at the given indices in the given array of `byte` values.
  `static void`
  `swap(char[] data, int i0, int i1)`
  Swaps the elements at the given indices in the given array of `char` values.
  `static void`
  `swap(double[] data, int i0, int i1)`
  Swaps the elements at the given indices in the given array of `double` values.
  `static void`
  `swap(float[] data, int i0, int i1)`
  Swaps the elements at the given indices in the given array of `float` values.
  `static void`
  `swap(int[] data, int i0, int i1)`
  Swaps the elements at the given indices in the given array of `int` values.
  `static void`
  `swap(long[] data, int i0, int i1)`
  Swaps the elements at the given indices in the given array of `long` values.
  `static void`
  `swap(short[] data, int i0, int i1)`
  Swaps the elements at the given indices in the given array of `short` values.
  `static void`
  `swap(Object[] data, int i0, int i1)`
  Swaps the elements at the given indices in the given array of `Object` values.
  `static int[]`
  `unionOfSorted(int[] array1, int[] array2)`
  Returns the union of two sorted arrays.

  ### Methods inherited from class Object

  `clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait`

- ## Field Details

  - ### EMPTY_DOUBLE

    public static final double[] EMPTY_DOUBLE
    An empty array of `double` primitive type. Such arrays are immutable and can be safely shared.

  - ### EMPTY_FLOAT

    public static final float[] EMPTY_FLOAT
    An empty array of `float` primitive type. Such arrays are immutable and can be safely shared.

  - ### EMPTY_LONG

    public static final long[] EMPTY_LONG
    An empty array of `long` primitive type. Such arrays are immutable and can be safely shared.

  - ### EMPTY_INT

    public static final int[] EMPTY_INT
    An empty array of `int` primitive type. Such arrays are immutable and can be safely shared.

  - ### EMPTY_SHORT

    public static final short[] EMPTY_SHORT
    An empty array of `short` primitive type. Such arrays are immutable and can be safely shared.

  - ### EMPTY_BYTE

    public static final byte[] EMPTY_BYTE
    An empty array of `byte` primitive type. Such arrays are immutable and can be safely shared.

  - ### EMPTY_CHAR

    public static final char[] EMPTY_CHAR
    An empty array of `char` primitive type. Such arrays are immutable and can be safely shared.

  - ### EMPTY_BOOLEAN

    public static final boolean[] EMPTY_BOOLEAN
    An empty array of `boolean` primitive type. Such arrays are immutable and can be safely shared.

- ## Method Details

  - ### resize

    public static <E> E[] resize(E[] array, int length) throws NegativeArraySizeException
    Returns an array containing the same elements as the given `array` but with the specified `length`, truncating or padding with `null` if necessary.
    - If the given `length` is longer than the length of the given `array`, then the returned array will contain all the elements of `array` at index i < `array​.length`. Elements at index i >= `array​.length` are initialized to `null`.
    - If the given `length` is shorter than the length of the given `array`, then the returned array will contain only the elements of `array` at index i < `length`. Remaining elements are not copied.
    - If the given `length` is equal to the length of the given `array`, then `array` is returned unchanged. No copy is performed. This behavior is different than the `Arrays​.copyOf(Object[], int)` one.
    Note that if the given array is `null`, then this method unconditionally returns `null` no matter the value of the `length` argument.
    Type Parameters:
      `E` - the array elements.
    Parameters:
      `array` - array to resize, or `null`.
      `length` - length of the desired array.
    Returns:
      a new array of the requested length, or `array` if the given array is `null` or already have the requested length.
    Throws:
      `NegativeArraySizeException` - if `length` is negative.
    See Also:
      - `Arrays​.copyOf(Object[], int)`

  - ### resize

    public static double[] resize(double[] array, int length) throws NegativeArraySizeException
    Returns an array containing the same elements as the given `array` but specified `length`, truncating or padding with zeros if necessary. This method returns `null` if and only if the given array is `null`, in which case the value of the `length` argument is ignored.
    Parameters:
      `array` - array to resize, or `null`.
      `length` - length of the desired array.
    Returns:
      a new array of the requested length, or `array` if the given array is `null` or already have the requested length.
    Throws:
      `NegativeArraySizeException` - if `length` is negative.
    See Also:
      - `Arrays​.copyOf(double[], int)`

  - ### resize

    public static float[] resize(float[] array, int length) throws NegativeArraySizeException
    Returns an array containing the same elements as the given `array` but specified `length`, truncating or padding with zeros if necessary. This method returns `null` if and only if the given array is `null`, in which case the value of the `length` argument is ignored.
    Parameters:
      `array` - array to resize, or `null`.
      `length` - length of the desired array.
    Returns:
      a new array of the requested length, or `array` if the given array is `null` or already have the requested length.
    Throws:
      `NegativeArraySizeException` - if `length` is negative.
    See Also:
      - `Arrays​.copyOf(float[], int)`

  - ### resize

    public static long[] resize(long[] array, int length) throws NegativeArraySizeException
    Returns an array containing the same elements as the given `array` but specified `length`, truncating or padding with zeros if necessary. This method returns `null` if and only if the given array is `null`, in which case the value of the `length` argument is ignored.
    Parameters:
      `array` - array to resize, or `null`.
      `length` - length of the desired array.
    Returns:
      a new array of the requested length, or `array` if the given array is `null` or already have the requested length.
    Throws:
      `NegativeArraySizeException` - if `length` is negative.
    See Also:
      - `Arrays​.copyOf(long[], int)`

  - ### resize

    public static int[] resize(int[] array, int length) throws NegativeArraySizeException
    Returns an array containing the same elements as the given `array` but specified `length`, truncating or padding with zeros if necessary. This method returns `null` if and only if the given array is `null`, in which case the value of the `length` argument is ignored.
    Parameters:
      `array` - array to resize, or `null`.
      `length` - length of the desired array.
    Returns:
      a new array of the requested length, or `array` if the given array is `null` or already have the requested length.
    Throws:
      `NegativeArraySizeException` - if `length` is negative.
    See Also:
      - `Arrays​.copyOf(int[], int)`

  - ### resize

    public static short[] resize(short[] array, int length) throws NegativeArraySizeException
    Returns an array containing the same elements as the given `array` but specified `length`, truncating or padding with zeros if necessary. This method returns `null` if and only if the given array is `null`, in which case the value of the `length` argument is ignored.
    Parameters:
      `array` - array to resize, or `null`.
      `length` - length of the desired array.
    Returns:
      a new array of the requested length, or `array` if the given array is `null` or already have the requested length.
    Throws:
      `NegativeArraySizeException` - if `length` is negative.
    See Also:
      - `Arrays​.copyOf(short[], int)`

  - ### resize

    public static byte[] resize(byte[] array, int length) throws NegativeArraySizeException
    Returns an array containing the same elements as the given `array` but specified `length`, truncating or padding with zeros if necessary. This method returns `null` if and only if the given array is `null`, in which case the value of the `length` argument is ignored.
    Parameters:
      `array` - array to resize, or `null`.
      `length` - length of the desired array.
    Returns:
      a new array of the requested length, or `array` if the given array is `null` or already have the requested length.
    Throws:
      `NegativeArraySizeException` - if `length` is negative.
    See Also:
      - `Arrays​.copyOf(byte[], int)`

  - ### resize

    public static char[] resize(char[] array, int length) throws NegativeArraySizeException
    Returns an array containing the same elements as the given `array` but specified `length`, truncating or padding with zeros if necessary. This method returns `null` if and only if the given array is `null`, in which case the value of the `length` argument is ignored.
    Parameters:
      `array` - array to resize, or `null`.
      `length` - length of the desired array.
    Returns:
      a new array of the requested length, or `array` if the given array is `null` or already have the requested length.
    Throws:
      `NegativeArraySizeException` - if `length` is negative.
    See Also:
      - `Arrays​.copyOf(char[], int)`

  - ### resize

    public static boolean[] resize(boolean[] array, int length) throws NegativeArraySizeException
    Returns an array containing the same elements as the given `array` but specified `length`, truncating or padding with `false` if necessary. This method returns `null` if and only if the given array is `null`, in which case the value of the `length` argument is ignored.
    Parameters:
      `array` - array to resize, or `null`.
      `length` - length of the desired array.
    Returns:
      a new array of the requested length, or `array` if the given array is `null` or already have the requested length.
    Throws:
      `NegativeArraySizeException` - if `length` is negative.
    See Also:
      - `Arrays​.copyOf(boolean[], int)`

  - ### remove

    public static <E> E[] remove(E[] array, int first, int length) throws NullArgumentException, IllegalArgumentException, IndexOutOfBoundsException
    Returns an array containing the same elements than the given array except for the given range. If the `length` argument is 0, then this method returns the `array` reference unchanged. Otherwise this method creates a new array. In every cases, the given array is never modified.
    Type Parameters:
      `E` - the type of array elements.
    Parameters:
      `array` - array from which to remove elements. Can be `null` only if `length` is 0.
      `first` - index of the first element to remove from the given `array`.
      `length` - number of elements to remove.
    Returns:
      array with the same elements than the given `array` except for the removed elements, or `array` (which may be null) if `length` is 0.
    Throws:
      `NullArgumentException` - if `array` is null and `length` is different than 0.
      `IllegalArgumentException` - if `length` is negative.
      `IndexOutOfBoundsException` - if `first` or `first+length` is out of array bounds.
    See Also:
      - `insert(Object[], int, int)`

  - ### remove

    public static double[] remove(double[] array, int first, int length) throws NullArgumentException, IllegalArgumentException, IndexOutOfBoundsException
    Returns an array containing the same elements than the given array except for the given range. If the `length` argument is 0, then this method returns the `array` reference unchanged, except for empty arrays. Otherwise this method creates a new array. In every cases, the given array is never modified.
    Parameters:
      `array` - array from which to remove elements. Can be `null` only if `length` is 0.
      `first` - index of the first element to remove from the given `array`.
      `length` - number of elements to remove.
    Returns:
      array with the same elements than the given `array` except for the removed elements, or `array` (which may be null) if `length` is 0.
    Throws:
      `NullArgumentException` - if `array` is null and `length` is different than 0.
      `IllegalArgumentException` - if `length` is negative.
      `IndexOutOfBoundsException` - if `first` or `first+length` is out of array bounds.
    See Also:
      - `insert(double[], int, int)`

  - ### remove

    public static float[] remove(float[] array, int first, int length) throws NullArgumentException, IllegalArgumentException, IndexOutOfBoundsException
    Returns an array containing the same elements than the given array except for the given range. If the `length` argument is 0, then this method returns the `array` reference unchanged, except for empty arrays. Otherwise this method creates a new array. In every cases, the given array is never modified.
    Parameters:
      `array` - array from which to remove elements. Can be `null` only if `length` is 0.
      `first` - index of the first element to remove from the given `array`.
      `length` - number of elements to remove.
    Returns:
      array with the same elements than the given `array` except for the removed elements, or `array` (which may be null) if `length` is 0.
    Throws:
      `NullArgumentException` - if `array` is null and `length` is different than 0.
      `IllegalArgumentException` - if `length` is negative.
      `IndexOutOfBoundsException` - if `first` or `first+length` is out of array bounds.
    See Also:
      - `insert(float[], int, int)`

  - ### remove

    public static long[] remove(long[] array, int first, int length) throws NullArgumentException, IllegalArgumentException, IndexOutOfBoundsException
    Returns an array containing the same elements than the given array except for the given range. If the `length` argument is 0, then this method returns the `array` reference unchanged, except for empty arrays. Otherwise this method creates a new array. In every cases, the given array is never modified.
    Parameters:
      `array` - array from which to remove elements. Can be `null` only if `length` is 0.
      `first` - index of the first element to remove from the given `array`.
      `length` - number of elements to remove.
    Returns:
      array with the same elements than the given `array` except for the removed elements, or `array` (which may be null) if `length` is 0.
    Throws:
      `NullArgumentException` - if `array` is null and `length` is different than 0.
      `IllegalArgumentException` - if `length` is negative.
      `IndexOutOfBoundsException` - if `first` or `first+length` is out of array bounds.
    See Also:
      - `insert(long[], int, int)`

  - ### remove

    public static int[] remove(int[] array, int first, int length) throws NullArgumentException, IllegalArgumentException, IndexOutOfBoundsException
    Returns an array containing the same elements than the given array except for the given range. If the `length` argument is 0, then this method returns the `array` reference unchanged, except for empty arrays. Otherwise this method creates a new array. In every cases, the given array is never modified.
    Parameters:
      `array` - array from which to remove elements. Can be `null` only if `length` is 0.
      `first` - index of the first element to remove from the given `array`.
      `length` - number of elements to remove.
    Returns:
      array with the same elements than the given `array` except for the removed elements, or `array` (which may be null) if `length` is 0.
    Throws:
      `NullArgumentException` - if `array` is null and `length` is different than 0.
      `IllegalArgumentException` - if `length` is negative.
      `IndexOutOfBoundsException` - if `first` or `first+length` is out of array bounds.
    See Also:
      - `insert(int[], int, int)`

  - ### remove

    public static short[] remove(short[] array, int first, int length) throws NullArgumentException, IllegalArgumentException, IndexOutOfBoundsException
    Returns an array containing the same elements than the given array except for the given range. If the `length` argument is 0, then this method returns the `array` reference unchanged, except for empty arrays. Otherwise this method creates a new array. In every cases, the given array is never modified.
    Parameters:
      `array` - array from which to remove elements. Can be `null` only if `length` is 0.
      `first` - index of the first element to remove from the given `array`.
      `length` - number of elements to remove.
    Returns:
      array with the same elements than the given `array` except for the removed elements, or `array` (which may be null) if `length` is 0.
    Throws:
      `NullArgumentException` - if `array` is null and `length` is different than 0.
      `IllegalArgumentException` - if `length` is negative.
      `IndexOutOfBoundsException` - if `first` or `first+length` is out of array bounds.
    See Also:
      - `insert(short[], int, int)`

  - ### remove

    public static byte[] remove(byte[] array, int first, int length) throws NullArgumentException, IllegalArgumentException, IndexOutOfBoundsException
    Returns an array containing the same elements than the given array except for the given range. If the `length` argument is 0, then this method returns the `array` reference unchanged, except for empty arrays. Otherwise this method creates a new array. In every cases, the given array is never modified.
    Parameters:
      `array` - array from which to remove elements. Can be `null` only if `length` is 0.
      `first` - index of the first element to remove from the given `array`.
      `length` - number of elements to remove.
    Returns:
      array with the same elements than the given `array` except for the removed elements, or `array` (which may be null) if `length` is 0.
    Throws:
      `NullArgumentException` - if `array` is null and `length` is different than 0.
      `IllegalArgumentException` - if `length` is negative.
      `IndexOutOfBoundsException` - if `first` or `first+length` is out of array bounds.
    See Also:
      - `insert(byte[], int, int)`

  - ### remove

    public static char[] remove(char[] array, int first, int length) throws NullArgumentException, IllegalArgumentException, IndexOutOfBoundsException
    Returns an array containing the same elements than the given array except for the given range. If the `length` argument is 0, then this method returns the `array` reference unchanged, except for empty arrays. Otherwise this method creates a new array. In every cases, the given array is never modified.
    Parameters:
      `array` - array from which to remove elements. Can be `null` only if `length` is 0.
      `first` - index of the first element to remove from the given `array`.
      `length` - number of elements to remove.
    Returns:
      array with the same elements than the given `array` except for the removed elements, or `array` (which may be null) if `length` is 0.
    Throws:
      `NullArgumentException` - if `array` is null and `length` is different than 0.
      `IllegalArgumentException` - if `length` is negative.
      `IndexOutOfBoundsException` - if `first` or `first+length` is out of array bounds.
    See Also:
      - `insert(char[], int, int)`

  - ### remove

    public static boolean[] remove(boolean[] array, int first, int length) throws NullArgumentException, IllegalArgumentException, IndexOutOfBoundsException
    Returns an array containing the same elements than the given array except for the given range. If the `length` argument is 0, then this method returns the `array` reference unchanged, except for empty arrays. Otherwise this method creates a new array. In every cases, the given array is never modified.
    Parameters:
      `array` - array from which to remove elements. Can be `null` only if `length` is 0.
      `first` - index of the first element to remove from the given `array`.
      `length` - number of elements to remove.
    Returns:
      array with the same elements than the given `array` except for the removed elements, or `array` (which may be null) if `length` is 0.
    Throws:
      `NullArgumentException` - if `array` is null and `length` is different than 0.
      `IllegalArgumentException` - if `length` is negative.
      `IndexOutOfBoundsException` - if `first` or `first+length` is out of array bounds.
    See Also:
      - `insert(boolean[], int, int)`

  - ### insert

    public static <E> E[] insert(E[] array, int first, int length) throws NullArgumentException, IllegalArgumentException, IndexOutOfBoundsException
    Returns an array containing the same elements than the given array, with additional "spaces" in the given range. These "spaces" will be made up of `null` elements. If the `length` argument is 0, then this method returns the `array` reference unchanged. Otherwise this method creates a new array. In every cases, the given array is never modified.
    Type Parameters:
      `E` - the type of array elements.
    Parameters:
      `array` - array in which to insert spaces. Can be `null` only if `length` is 0.
      `first` - index where the first space will be inserted. All `array` elements having an index equal to or higher than `index` will be moved forward. Can be `array​.length` for inserting spaces at the end of the array.
      `length` - number of spaces to insert.
    Returns:
      array containing the `array` elements with the additional space inserted, or `array` (which may be null) if `length` is 0.
    Throws:
      `NullArgumentException` - if `array` is null and `length` is different than 0.
      `IllegalArgumentException` - if `length` is negative.
      `IndexOutOfBoundsException` - if `first` or `first+length` is out of array bounds.
    See Also:
      - `insert(Object[], int, Object[], int, int)`
      - `remove(Object[], int, int)`

  - ### insert

    public static double[] insert(double[] array, int first, int length) throws NullArgumentException, IllegalArgumentException, IndexOutOfBoundsException
    Returns an array containing the same elements than the given array, with additional "spaces" in the given range. These "spaces" will be made up of elements initialized to zero. If the `length` argument is 0, then this method returns the `array` reference unchanged. Otherwise this method creates a new array. In every cases, the given array is never modified.
    Parameters:
      `array` - array in which to insert spaces. Can be `null` only if `length` is 0.
      `first` - index where the first space will be inserted. All `array` elements having an index equal to or higher than `index` will be moved forward. Can be `array​.length` for inserting spaces at the end of the array.
      `length` - number of spaces to insert.
    Returns:
      array containing the `array` elements with the additional space inserted, or `array` (which may be null) if `length` is 0.
    Throws:
      `NullArgumentException` - if `array` is null and `length` is different than 0.
      `IllegalArgumentException` - if `length` is negative.
      `IndexOutOfBoundsException` - if `first` or `first+length` is out of array bounds.
    See Also:
      - `insert(double[], int, double[], int, int)`
      - `remove(double[], int, int)`

  - ### insert

    public static float[] insert(float[] array, int first, int length) throws NullArgumentException, IllegalArgumentException, IndexOutOfBoundsException
    Returns an array containing the same elements than the given array, with additional "spaces" in the given range. These "spaces" will be made up of elements initialized to zero. If the `length` argument is 0, then this method returns the `array` reference unchanged. Otherwise this method creates a new array. In every cases, the given array is never modified.
    Parameters:
      `array` - array in which to insert spaces. Can be `null` only if `length` is 0.
      `first` - index where the first space will be inserted. All `array` elements having an index equal to or higher than `index` will be moved forward. Can be `array​.length` for inserting spaces at the end of the array.
      `length` - number of spaces to insert.
    Returns:
      array containing the `array` elements with the additional space inserted, or `array` (which may be null) if `length` is 0.
    Throws:
      `NullArgumentException` - if `array` is null and `length` is different than 0.
      `IllegalArgumentException` - if `length` is negative.
      `IndexOutOfBoundsException` - if `first` or `first+length` is out of array bounds.
    See Also:
      - `insert(float[], int, float[], int, int)`
      - `remove(float[], int, int)`

  - ### insert

    public static long[] insert(long[] array, int first, int length) throws NullArgumentException, IllegalArgumentException, IndexOutOfBoundsException
    Returns an array containing the same elements than the given array, with additional "spaces" in the given range. These "spaces" will be made up of elements initialized to zero. If the `length` argument is 0, then this method returns the `array` reference unchanged. Otherwise this method creates a new array. In every cases, the given array is never modified.
    Parameters:
      `array` - array in which to insert spaces. Can be `null` only if `length` is 0.
      `first` - index where the first space will be inserted. All `array` elements having an index equal to or higher than `index` will be moved forward. Can be `array​.length` for inserting spaces at the end of the array.
      `length` - number of spaces to insert.
    Returns:
      array containing the `array` elements with the additional space inserted, or `array` (which may be null) if `length` is 0.
    Throws:
      `NullArgumentException` - if `array` is null and `length` is different than 0.
      `IllegalArgumentException` - if `length` is negative.
      `IndexOutOfBoundsException` - if `first` or `first+length` is out of array bounds.
    See Also:
      - `insert(long[], int, long[], int, int)`
      - `remove(long[], int, int)`

  - ### insert

    public static int[] insert(int[] array, int first, int length) throws NullArgumentException, IllegalArgumentException, IndexOutOfBoundsException
    Returns an array containing the same elements than the given array, with additional "spaces" in the given range. These "spaces" will be made up of elements initialized to zero. If the `length` argument is 0, then this method returns the `array` reference unchanged. Otherwise this method creates a new array. In every cases, the given array is never modified.
    Parameters:
      `array` - array in which to insert spaces. Can be `null` only if `length` is 0.
      `first` - index where the first space will be inserted. All `array` elements having an index equal to or higher than `index` will be moved forward. Can be `array​.length` for inserting spaces at the end of the array.
      `length` - number of spaces to insert.
    Returns:
      array containing the `array` elements with the additional space inserted, or `array` (which may be null) if `length` is 0.
    Throws:
      `NullArgumentException` - if `array` is null and `length` is different than 0.
      `IllegalArgumentException` - if `length` is negative.
      `IndexOutOfBoundsException` - if `first` or `first+length` is out of array bounds.
    See Also:
      - `insert(int[], int, int[], int, int)`
      - `remove(int[], int, int)`

  - ### insert

    public static short[] insert(short[] array, int first, int length) throws NullArgumentException, IllegalArgumentException, IndexOutOfBoundsException
    Returns an array containing the same elements than the given array, with additional "spaces" in the given range. These "spaces" will be made up of elements initialized to zero. If the `length` argument is 0, then this method returns the `array` reference unchanged. Otherwise this method creates a new array. In every cases, the given array is never modified.
    Parameters:
      `array` - array in which to insert spaces. Can be `null` only if `length` is 0.
      `first` - index where the first space should be inserted. All `array` elements having an index equal to or higher than `index` will be moved forward.
      `length` - number of spaces to insert.
    Returns:
      array containing the `array` elements with the additional space inserted, or `array` (which may be null) if `length` is 0.
    Throws:
      `NullArgumentException` - if `array` is null and `length` is different than 0.
      `IllegalArgumentException` - if `length` is negative.
      `IndexOutOfBoundsException` - if `first` or `first+length` is out of array bounds.
    See Also:
      - `insert(short[], int, short[], int, int)`
      - `remove(short[], int, int)`

  - ### insert

    public static byte[] insert(byte[] array, int first, int length) throws NullArgumentException, IllegalArgumentException, IndexOutOfBoundsException
    Returns an array containing the same elements than the given array, with additional "spaces" in the given range. These "spaces" will be made up of elements initialized to zero. If the `length` argument is 0, then this method returns the `array` reference unchanged. Otherwise this method creates a new array. In every cases, the given array is never modified.
    Parameters:
      `array` - array in which to insert spaces. Can be `null` only if `length` is 0.
      `first` - index where the first space will be inserted. All `array` elements having an index equal to or higher than `index` will be moved forward. Can be `array​.length` for inserting spaces at the end of the array.
      `length` - number of spaces to insert.
    Returns:
      array containing the `array` elements with the additional space inserted, or `array` (which may be null) if `length` is 0.
    Throws:
      `NullArgumentException` - if `array` is null and `length` is different than 0.
      `IllegalArgumentException` - if `length` is negative.
      `IndexOutOfBoundsException` - if `first` or `first+length` is out of array bounds.
    See Also:
      - `insert(byte[], int, byte[], int, int)`
      - `remove(byte[], int, int)`

  - ### insert

    public static char[] insert(char[] array, int first, int length) throws NullArgumentException, IllegalArgumentException, IndexOutOfBoundsException
    Returns an array containing the same elements than the given array, with additional "spaces" in the given range. These "spaces" will be made up of elements initialized to zero. If the `length` argument is 0, then this method returns the `array` reference unchanged. Otherwise this method creates a new array. In every cases, the given array is never modified.
    Parameters:
      `array` - array in which to insert spaces. Can be `null` only if `length` is 0.
      `first` - index where the first space will be inserted. All `array` elements having an index equal to or higher than `index` will be moved forward. Can be `array​.length` for inserting spaces at the end of the array.
      `length` - number of spaces to insert.
    Returns:
      array containing the `array` elements with the additional space inserted, or `array` (which may be null) if `length` is 0.
    Throws:
      `NullArgumentException` - if `array` is null and `length` is different than 0.
      `IllegalArgumentException` - if `length` is negative.
      `IndexOutOfBoundsException` - if `first` or `first+length` is out of array bounds.
    See Also:
      - `insert(char[], int, char[], int, int)`
      - `remove(char[], int, int)`

  - ### insert

    public static boolean[] insert(boolean[] array, int first, int length) throws NullArgumentException, IllegalArgumentException, IndexOutOfBoundsException
    Returns an array containing the same elements than the given array, with additional "spaces" in the given range. These "spaces" will be made up of elements initialized to `false`. If the `length` argument is 0, then this method returns the `array` reference unchanged. Otherwise this method creates a new array. In every cases, the given array is never modified.
    Parameters:
      `array` - array in which to insert spaces. Can be `null` only if `length` is 0.
      `first` - index where the first space will be inserted. All `array` elements having an index equal to or higher than `index` will be moved forward. Can be `array​.length` for inserting spaces at the end of the array.
      `length` - number of spaces to insert.
    Returns:
      array containing the `array` elements with the additional space inserted, or `array` (which may be null) if `length` is 0.
    Throws:
      `NullArgumentException` - if `array` is null and `length` is different than 0.
      `IllegalArgumentException` - if `length` is negative.
      `IndexOutOfBoundsException` - if `first` or `first+length` is out of array bounds.
    See Also:
      - `insert(boolean[], int, boolean[], int, int)`
      - `remove(boolean[], int, int)`

  - ### insert

    public static <E> E[] insert(E[] src, int srcOff, E[] dst, int dstOff, int length) throws NullArgumentException, IllegalArgumentException, IndexOutOfBoundsException
    Returns an array containing the same elements than the given array, with the content of an other array inserted at the given index. If the `length` argument is 0, then this method returns the `dst` reference unchanged. Otherwise this method creates a new array. In every cases, the given arrays are never modified.
    Type Parameters:
      `E` - the type of array elements.
    Parameters:
      `src` - array to entirely or partially insert into `dst`. Can be null only if `length` is 0.
      `srcOff` - index of the first element of `src` to insert into `dst`.
      `dst` - array in which to insert `src` data. Can be null only if `length` is 0.
      `dstOff` - index of the first element in `dst` where to insert `src` data. All elements of `dst` whose index is equal to or greater than `dstOff` will be moved forward.
      `length` - number of `src` elements to insert.
    Returns:
      array which contains the merge of `src` and `dst`. This method returns directly `dst` when `length` is zero, but never return `src`.
    Throws:
      `NullArgumentException` - if `src` or `dst` is null while `length` is different than 0.
      `IllegalArgumentException` - if `length` is negative.
      `IndexOutOfBoundsException` - if `srcOff`, `srcOff+length` or `dstOff` is out of array bounds.

  - ### insert

    public static double[] insert(double[] src, int srcOff, double[] dst, int dstOff, int length) throws NullArgumentException, IllegalArgumentException, IndexOutOfBoundsException
    Returns an array containing the same elements than the given array, with the content of an other array inserted at the given index. If the `length` argument is 0, then this method returns the `dst` reference unchanged. Otherwise this method creates a new array. In every cases, the given arrays are never modified.
    Parameters:
      `src` - array to entirely or partially insert into `dst`. Can be null only if `length` is 0.
      `srcOff` - index of the first element of `src` to insert into `dst`.
      `dst` - array in which to insert `src` data. Can be null only if `length` is 0.
      `dstOff` - index of the first element in `dst` where to insert `src` data. All elements of `dst` whose index is equal to or greater than `dstOff` will be moved forward.
      `length` - number of `src` elements to insert.
    Returns:
      array which contains the merge of `src` and `dst`. This method returns directly `dst` when `length` is zero, but never return `src`.
    Throws:
      `NullArgumentException` - if `src` or `dst` is null while `length` is different than 0.
      `IllegalArgumentException` - if `length` is negative.
      `IndexOutOfBoundsException` - if `srcOff`, `srcOff+length` or `dstOff` is out of array bounds.

  - ### insert

    public static float[] insert(float[] src, int srcOff, float[] dst, int dstOff, int length) throws NullArgumentException, IllegalArgumentException, IndexOutOfBoundsException
    Returns an array containing the same elements than the given array, with the content of an other array inserted at the given index. If the `length` argument is 0, then this method returns the `dst` reference unchanged. Otherwise this method creates a new array. In every cases, the given arrays are never modified.
    Parameters:
      `src` - array to entirely or partially insert into `dst`. Can be null only if `length` is 0.
      `srcOff` - index of the first element of `src` to insert into `dst`.
      `dst` - array in which to insert `src` data. Can be null only if `length` is 0.
      `dstOff` - index of the first element in `dst` where to insert `src` data. All elements of `dst` whose index is equal to or greater than `dstOff` will be moved forward.
      `length` - number of `src` elements to insert.
    Returns:
      array which contains the merge of `src` and `dst`. This method returns directly `dst` when `length` is zero, but never return `src`.
    Throws:
      `NullArgumentException` - if `src` or `dst` is null while `length` is different than 0.
      `IllegalArgumentException` - if `length` is negative.
      `IndexOutOfBoundsException` - if `srcOff`, `srcOff+length` or `dstOff` is out of array bounds.

  - ### insert

    public static long[] insert(long[] src, int srcOff, long[] dst, int dstOff, int length) throws NullArgumentException, IllegalArgumentException, IndexOutOfBoundsException
    Returns an array containing the same elements than the given array, with the content of an other array inserted at the given index. If the `length` argument is 0, then this method returns the `dst` reference unchanged. Otherwise this method creates a new array. In every cases, the given arrays are never modified.
    Parameters:
      `src` - array to entirely or partially insert into `dst`. Can be null only if `length` is 0.
      `srcOff` - index of the first element of `src` to insert into `dst`.
      `dst` - array in which to insert `src` data. Can be null only if `length` is 0.
      `dstOff` - index of the first element in `dst` where to insert `src` data. All elements of `dst` whose index is equal to or greater than `dstOff` will be moved forward.
      `length` - number of `src` elements to insert.
    Returns:
      array which contains the merge of `src` and `dst`. This method returns directly `dst` when `length` is zero, but never return `src`.
    Throws:
      `NullArgumentException` - if `src` or `dst` is null while `length` is different than 0.
      `IllegalArgumentException` - if `length` is negative.
      `IndexOutOfBoundsException` - if `srcOff`, `srcOff+length` or `dstOff` is out of array bounds.

  - ### insert

    public static int[] insert(int[] src, int srcOff, int[] dst, int dstOff, int length) throws NullArgumentException, IllegalArgumentException, IndexOutOfBoundsException
    Returns an array containing the same elements than the given array, with the content of an other array inserted at the given index. If the `length` argument is 0, then this method returns the `dst` reference unchanged. Otherwise this method creates a new array. In every cases, the given arrays are never modified.
    Parameters:
      `src` - array to entirely or partially insert into `dst`. Can be null only if `length` is 0.
      `srcOff` - index of the first element of `src` to insert into `dst`.
      `dst` - array in which to insert `src` data. Can be null only if `length` is 0.
      `dstOff` - index of the first element in `dst` where to insert `src` data. All elements of `dst` whose index is equal to or greater than `dstOff` will be moved forward.
      `length` - number of `src` elements to insert.
    Returns:
      array which contains the merge of `src` and `dst`. This method returns directly `dst` when `length` is zero, but never return `src`.
    Throws:
      `NullArgumentException` - if `src` or `dst` is null while `length` is different than 0.
      `IllegalArgumentException` - if `length` is negative.
      `IndexOutOfBoundsException` - if `srcOff`, `srcOff+length` or `dstOff` is out of array bounds.

  - ### insert

    public static short[] insert(short[] src, int srcOff, short[] dst, int dstOff, int length) throws NullArgumentException, IllegalArgumentException, IndexOutOfBoundsException
    Returns an array containing the same elements than the given array, with the content of an other array inserted at the given index. If the `length` argument is 0, then this method returns the `dst` reference unchanged. Otherwise this method creates a new array. In every cases, the given arrays are never modified.
    Parameters:
      `src` - array to entirely or partially insert into `dst`. Can be null only if `length` is 0.
      `srcOff` - index of the first element of `src` to insert into `dst`.
      `dst` - array in which to insert `src` data. Can be null only if `length` is 0.
      `dstOff` - index of the first element in `dst` where to insert `src` data. All elements of `dst` whose index is equal to or greater than `dstOff` will be moved forward.
      `length` - number of `src` elements to insert.
    Returns:
      array which contains the merge of `src` and `dst`. This method returns directly `dst` when `length` is zero, but never return `src`.
    Throws:
      `NullArgumentException` - if `src` or `dst` is null while `length` is different than 0.
      `IllegalArgumentException` - if `length` is negative.
      `IndexOutOfBoundsException` - if `srcOff`, `srcOff+length` or `dstOff` is out of array bounds.

  - ### insert

    public static byte[] insert(byte[] src, int srcOff, byte[] dst, int dstOff, int length) throws NullArgumentException, IllegalArgumentException, IndexOutOfBoundsException
    Returns an array containing the same elements than the given array, with the content of an other array inserted at the given index. If the `length` argument is 0, then this method returns the `dst` reference unchanged. Otherwise this method creates a new array. In every cases, the given arrays are never modified.
    Parameters:
      `src` - array to entirely or partially insert into `dst`. Can be null only if `length` is 0.
      `srcOff` - index of the first element of `src` to insert into `dst`.
      `dst` - array in which to insert `src` data. Can be null only if `length` is 0.
      `dstOff` - index of the first element in `dst` where to insert `src` data. All elements of `dst` whose index is equal to or greater than `dstOff` will be moved forward.
      `length` - number of `src` elements to insert.
    Returns:
      array which contains the merge of `src` and `dst`. This method returns directly `dst` when `length` is zero, but never return `src`.
    Throws:
      `NullArgumentException` - if `src` or `dst` is null while `length` is different than 0.
      `IllegalArgumentException` - if `length` is negative.
      `IndexOutOfBoundsException` - if `srcOff`, `srcOff+length` or `dstOff` is out of array bounds.

  - ### insert

    public static char[] insert(char[] src, int srcOff, char[] dst, int dstOff, int length) throws NullArgumentException, IllegalArgumentException, IndexOutOfBoundsException
    Returns an array containing the same elements than the given array, with the content of an other array inserted at the given index. If the `length` argument is 0, then this method returns the `dst` reference unchanged. Otherwise this method creates a new array. In every cases, the given arrays are never modified.
    Parameters:
      `src` - array to entirely or partially insert into `dst`. Can be null only if `length` is 0.
      `srcOff` - index of the first element of `src` to insert into `dst`.
      `dst` - array in which to insert `src` data. Can be null only if `length` is 0.
      `dstOff` - index of the first element in `dst` where to insert `src` data. All elements of `dst` whose index is equal to or greater than `dstOff` will be moved forward.
      `length` - number of `src` elements to insert.
    Returns:
      array which contains the merge of `src` and `dst`. This method returns directly `dst` when `length` is zero, but never return `src`.
    Throws:
      `NullArgumentException` - if `src` or `dst` is null while `length` is different than 0.
      `IllegalArgumentException` - if `length` is negative.
      `IndexOutOfBoundsException` - if `srcOff`, `srcOff+length` or `dstOff` is out of array bounds.

  - ### insert

    public static boolean[] insert(boolean[] src, int srcOff, boolean[] dst, int dstOff, int length) throws NullArgumentException, IllegalArgumentException, IndexOutOfBoundsException
    Returns an array containing the same elements than the given array, with the content of an other array inserted at the given index. If the `length` argument is 0, then this method returns the `dst` reference unchanged. Otherwise this method creates a new array. In every cases, the given arrays are never modified.
    Parameters:
      `src` - array to entirely or partially insert into `dst`. Can be null only if `length` is 0.
      `srcOff` - index of the first element of `src` to insert into `dst`.
      `dst` - array in which to insert `src` data. Can be null only if `length` is 0.
      `dstOff` - index of the first element in `dst` where to insert `src` data. All elements of `dst` whose index is equal to or greater than `dstOff` will be moved forward.
      `length` - number of `src` elements to insert.
    Returns:
      array which contains the merge of `src` and `dst`. This method returns directly `dst` when `length` is zero, but never return `src`.
    Throws:
      `NullArgumentException` - if `src` or `dst` is null while `length` is different than 0.
      `IllegalArgumentException` - if `length` is negative.
      `IndexOutOfBoundsException` - if `srcOff`, `srcOff+length` or `dstOff` is out of array bounds.

  - ### append

    public static <T> T[] append(T[] array, T element) throws NullArgumentException
    Returns a copy of the given array with a single element appended at the end. This method should be invoked only on rare occasions. If many elements are to be added, use `ArrayList` instead.
    Type Parameters:
      `T` - the type of elements in the array.
    Parameters:
      `array` - the array to copy with a new element. The original array will not be modified.
      `element` - the element to add (can be null).
    Returns:
      a copy of the given array with the given element appended at the end.
    Throws:
      `NullArgumentException` - if the given array is null.
    See Also:
      - `concatenate(Object[][])`

  - ### removeDuplicated

    public static int removeDuplicated(Object[] array)
    Removes the duplicated elements in the given array. This method should be invoked only for small arrays, typically less than 10 distinct elements. For larger arrays, use `LinkedHashSet` instead.

    This method compares all pair of elements using the `Objects​.equals(Object, Object)` method - so null elements are allowed. If duplicated values are found, then only the first occurrence is retained; the second occurrence is removed in-place. After all elements have been compared, this method returns the number of remaining elements in the array. The free space at the end of the array is padded with `null` values.

    Callers can obtain an array of appropriate length using the following idiom. Note that this idiom will create a new array only if necessary:

    >     T[] array = ...;
    >     array = resize(array, removeDuplicated(array));

    API note: This method return type is not an array in order to make obvious that the given array will be modified in-place. This behavior is different than the behavior of many other methods in this class, which do not modify the given source array.
    Parameters:
      `array` - array from which to remove duplicated elements, or `null`.
    Returns:
      the number of remaining elements in the given array, or 0 if the given `array` was null.

  - ### reverse

    public static void reverse(Object[] entries)
    Reverses the order of elements in the given array. This operation is performed in-place. If the given array is `null`, then this method does nothing.
    Parameters:
      `entries` - the array in which to reverse the order of elements, or `null` if none.

  - ### reverse

    public static void reverse(int[] values)
    Reverses the order of elements in the given array. This operation is performed in-place. If the given array is `null`, then this method does nothing.
    Parameters:
      `values` - the array in which to reverse the order of elements, or `null` if none.

  - ### range

    public static int[] range(int start, int end)
    Returns the ordered values in the range from `start` inclusive to `end` exclusive. This method performs the same work than `IntStream​.range(int, int)` but returning values in an array instead of in a stream. This method is okay for small sequences; for large sequences the stream approach should be preferred.
    Purpose: this method is convenient for enumerating dimensions in a coordinate reference system or bands in an image. Some methods in the Java library or in Apache SIS want dimensions or bands to be specified by their indices. An example from the Java library is the `bankIndices` argument in `Raster​.createBandedRaster(…, bankIndices, …)`. An example from Apache SIS is the `range` argument in `GridCoverageResource​.read(…, range)`. This `range(start, end)` method can be used in the common case where all bands are wanted in order.
    For any array returned by this method, ``isRange`(start, array)` is guaranteed to return `true`.
    Parameters:
      `start` - first value (inclusive) in the array to return.
      `end` - upper bound (exclusive) of values in the array to return.
    Returns:
      a finite arithmetic progression of common difference of 1 with all values in the specified range.
    Throws:
      `ArithmeticException` - if the sequence length is greater than `Integer​.MAX_VALUE`.
    Since:
      1.0
    See Also:
      - `IntStream​.range(int, int)`
      - Arithmetic progression on Wikipedia

  - ### isRange

    public static boolean isRange(int start, int[] array)
    Returns `true` if the given array is a finite arithmetic progression starting at the given value and having a common difference of 1. More specifically:
    - If `array` is `null`, then return `false`.
    - Otherwise if `array` is empty, then return `true` for consistency with `range(int, int)`.
    - Otherwise for any index 0 ≤ i < `array​.length`, if `array[i]` is equal to `start + i` (computed as if no overflow occurs), then return `true`.
    - Otherwise return `false`.
    Example: `isRange(1, array)` returns `true` if the given array is `{1, 2, 3, 4}` but `false` if the array is `{1, 2, 4}` (missing 3).
    This method is useful when `array` is an argument specified to another method, and determining that the argument values are `start`, `start`+1, `start`+2, etc. allows some optimizations.
    Parameters:
      `start` - first value expected in the given `array`.
      `array` - the array to test, or `null`.
    Returns:
      `true` if the given array is non-null and equal to `range(start, start + array​.length)`.
    Since:
      1.0
    See Also:
      - `range(int, int)`

  - ### isSorted

    public static <E> boolean isSorted(E[] array, Comparator<? super E> comparator, boolean strict)
    Returns `true` if all elements in the specified array are in increasing order. Special cases:
    - Empty arrays are considered as sorted.
    - Null arrays are considered as unknown content and cause a `NullPointerException` to be thrown.
    - `null` elements are considered unordered and may appear anywhere in the array; they will be silently ignored.
    Type Parameters:
      `E` - the type of array elements.
    Parameters:
      `array` - the array to test for order.
      `comparator` - the comparator to use for comparing order.
      `strict` - `true` if elements should be strictly sorted (i.e. equal elements are not allowed), or `false` otherwise.
    Returns:
      `true` if all elements in the given array are sorted in increasing order.

  - ### isSorted

    public static <E extends Comparable<? super E>> boolean isSorted(E[] array, boolean strict)
    Returns `true` if all elements in the specified array are in increasing order. Special cases:
    - Empty arrays are considered as sorted.
    - Null arrays are considered as unknown content and cause a `NullPointerException` to be thrown.
    - `null` elements are considered unordered and may appear anywhere in the array; they will be silently ignored.
    Type Parameters:
      `E` - the type of array elements.
    Parameters:
      `array` - the array to test for order.
      `strict` - `true` if elements should be strictly sorted (i.e. equal elements are not allowed), or `false` otherwise.
    Returns:
      `true` if all elements in the given array are sorted in increasing order.

  - ### isSorted

    public static boolean isSorted(double[] array, boolean strict)
    Returns `true` if all elements in the specified array are in increasing order. Special cases:
    - Empty arrays are considered as sorted.
    - Null arrays are considered as unknown content and cause a `NullPointerException` to be thrown.
    - `NaN` elements are considered unordered and may appear anywhere in the array; they will be silently ignored.
    Parameters:
      `array` - the array to test for order.
      `strict` - `true` if elements should be strictly sorted (i.e. equal elements are not allowed), or `false` otherwise.
    Returns:
      `true` if all elements in the given array are sorted in increasing order.

  - ### isSorted

    public static boolean isSorted(float[] array, boolean strict)
    Returns `true` if all elements in the specified array are in increasing order. Special cases:
    - Empty arrays are considered as sorted.
    - Null arrays are considered as unknown content and cause a `NullPointerException` to be thrown.
    - `NaN` elements are considered unordered and may appear anywhere in the array; they will be silently ignored.
    Parameters:
      `array` - the array to test for order.
      `strict` - `true` if elements should be strictly sorted (i.e. equal elements are not allowed), or `false` otherwise.
    Returns:
      `true` if all elements in the given array are sorted in increasing order.

  - ### isSorted

    public static boolean isSorted(long[] array, boolean strict)
    Returns `true` if all elements in the specified array are in increasing order. Special cases:
    - Empty arrays are considered as sorted.
    - Null arrays are considered as unknown content and cause a `NullPointerException` to be thrown.
    Parameters:
      `array` - the array to test for order.
      `strict` - `true` if elements should be strictly sorted (i.e. equal elements are not allowed), or `false` otherwise.
    Returns:
      `true` if all elements in the given array are sorted in increasing order.

  - ### isSorted

    public static boolean isSorted(int[] array, boolean strict)
    Returns `true` if all elements in the specified array are in increasing order. Special cases:
    - Empty arrays are considered as sorted.
    - Null arrays are considered as unknown content and cause a `NullPointerException` to be thrown.
    Parameters:
      `array` - the array to test for order.
      `strict` - `true` if elements should be strictly sorted (i.e. equal elements are not allowed), or `false` otherwise.
    Returns:
      `true` if all elements in the given array are sorted in increasing order.

  - ### isSorted

    public static boolean isSorted(short[] array, boolean strict)
    Returns `true` if all elements in the specified array are in increasing order. Special cases:
    - Empty arrays are considered as sorted.
    - Null arrays are considered as unknown content and cause a `NullPointerException` to be thrown.
    Parameters:
      `array` - the array to test for order.
      `strict` - `true` if elements should be strictly sorted (i.e. equal elements are not allowed), or `false` otherwise.
    Returns:
      `true` if all elements in the given array are sorted in increasing order.

  - ### isSorted

    public static boolean isSorted(byte[] array, boolean strict)
    Returns `true` if all elements in the specified array are in increasing order. Special cases:
    - Empty arrays are considered as sorted.
    - Null arrays are considered as unknown content and cause a `NullPointerException` to be thrown.
    Parameters:
      `array` - the array to test for order.
      `strict` - `true` if elements should be strictly sorted (i.e. equal elements are not allowed), or `false` otherwise.
    Returns:
      `true` if all elements in the given array are sorted in increasing order.

  - ### isSorted

    public static boolean isSorted(char[] array, boolean strict)
    Returns `true` if all elements in the specified array are in increasing order. Special cases:
    - Empty arrays are considered as sorted.
    - Null arrays are considered as unknown content and cause a `NullPointerException` to be thrown.
    Parameters:
      `array` - the array to test for order.
      `strict` - `true` if elements should be strictly sorted (i.e. equal elements are not allowed), or `false` otherwise.
    Returns:
      `true` if all elements in the given array are sorted in increasing order.

  - ### swap

    public static void swap(Object[] data, int i0, int i1)
    Swaps the elements at the given indices in the given array of `Object` values.
    Note: While trivial, this method is provided because its need occurs relatively often and the availability of a `swap` method makes the code easier to read.
    Parameters:
      `data` - the array in which to swap elements.
      `i0` - index of one element to be swapped.
      `i1` - index of the other element to be swapped.
    Since:
      0.4

  - ### swap

    public static void swap(double[] data, int i0, int i1)
    Swaps the elements at the given indices in the given array of `double` values.
    Note: While trivial, this method is provided because its need occurs relatively often and the availability of a `swap` method makes the code easier to read.
    Parameters:
      `data` - the array in which to swap elements.
      `i0` - index of one element to be swapped.
      `i1` - index of the other element to be swapped.
    Since:
      0.4

  - ### swap

    public static void swap(float[] data, int i0, int i1)
    Swaps the elements at the given indices in the given array of `float` values.
    Parameters:
      `data` - the array in which to swap elements.
      `i0` - index of one element to be swapped.
      `i1` - index of the other element to be swapped.
    Since:
      0.4

  - ### swap

    public static void swap(long[] data, int i0, int i1)
    Swaps the elements at the given indices in the given array of `long` values.
    Parameters:
      `data` - the array in which to swap elements.
      `i0` - index of one element to be swapped.
      `i1` - index of the other element to be swapped.
    Since:
      0.4

  - ### swap

    public static void swap(int[] data, int i0, int i1)
    Swaps the elements at the given indices in the given array of `int` values.
    Note: While trivial, this method is provided because its need occurs relatively often and the availability of a `swap` method makes the code easier to read.
    Parameters:
      `data` - the array in which to swap elements.
      `i0` - index of one element to be swapped.
      `i1` - index of the other element to be swapped.
    Since:
      0.4

  - ### swap

    public static void swap(short[] data, int i0, int i1)
    Swaps the elements at the given indices in the given array of `short` values.
    Parameters:
      `data` - the array in which to swap elements.
      `i0` - index of one element to be swapped.
      `i1` - index of the other element to be swapped.
    Since:
      0.4

  - ### swap

    public static void swap(byte[] data, int i0, int i1)
    Swaps the elements at the given indices in the given array of `byte` values.
    Parameters:
      `data` - the array in which to swap elements.
      `i0` - index of one element to be swapped.
      `i1` - index of the other element to be swapped.
    Since:
      0.4

  - ### swap

    public static void swap(char[] data, int i0, int i1)
    Swaps the elements at the given indices in the given array of `char` values.
    Parameters:
      `data` - the array in which to swap elements.
      `i0` - index of one element to be swapped.
      `i1` - index of the other element to be swapped.
    Since:
      0.4

  - ### replace

    public static void replace(double[] array, double search, double replacement)
    Replaces all occurrences of the given value by the given replacement. This method compares the values using `Double​.doubleToRawLongBits(double)`:
    - Positive zero is considered different then negative zero.
    - The various possible NaN values are considered different.
    A common usage for this method is to replace pad values by `Double​.NaN` in the sample values of a grid coverage. This method does nothing if the given array is `null` or if `search` is the same bits pattern than `replacement`.
    Parameters:
      `array` - the array where to perform the search and replace, or `null`.
      `search` - the value to search.
      `replacement` - the replacement.
    Since:
      1.0

  - ### replace

    public static void replace(float[] array, float search, float replacement)
    Replaces all occurrences of the given value by the given replacement. This method compares the values using `Float​.floatToRawIntBits(float)`:
    - Positive zero is considered different then negative zero.
    - The various possible NaN values are considered different.
    A common usage for this method is to replace pad values by `Float​.NaN` in the sample values of a grid coverage. This method does nothing if the given array is `null` or if `search` is the same bits pattern than `replacement`.
    Parameters:
      `array` - the array where to perform the search and replace, or `null`.
      `search` - the value to search.
      `replacement` - the replacement.
    Since:
      1.0

  - ### copyAsLongs

    public static long[] copyAsLongs(int[] data)
    Returns a copy of the given array where each value has been casted to the `long` type.
    Parameters:
      `data` - the array to copy, or `null`.
    Returns:
      a copy of the given array with values casted to the `long` type, or `null` if the given array was null.
    Since:
      1.1

  - ### copyAsFloats

    public static float[] copyAsFloats(double[] data)
    Returns a copy of the given array where each value has been casted to the `float` type. This method does not verify if the casts would cause data loss.
    Parameters:
      `data` - the array to copy, or `null`.
    Returns:
      a copy of the given array with values casted to the `float` type, or `null` if the given array was null.
    Since:
      1.0

  - ### copyAsFloatsIfLossless

    public static float[] copyAsFloatsIfLossless(double[] data)
    Returns a copy of the given array where each value has been casted to the `float` type, but only if all casts are lossless. If any cast causes data loss, then this method returns `null`. This method is equivalent to the following code, but potentially more efficient:

    >     if (isSinglePrecision(data)) {
    >         return copyAsFloat(data);
    >     } else {
    >         return null;
    >     }

    Parameters:
      `data` - the array to copy, or `null`.
    Returns:
      a copy of the given array with values casted to the `float` type, or `null` if the given array was null or if a cast would cause data lost.
    Since:
      1.0

  - ### isSinglePrecision

    public static boolean isSinglePrecision(double... values)
    Returns `true` if every values in the given `double` array could be casted to the `float` type without data lost. If this method returns `true`, then the array can be converted to the `float[]` type with `copyAsFloats(double[])` and the exact same `double` values can still be obtained by casting back each `float` value to `double`.
    Parameters:
      `values` - the values to test for their precision, or `null`.
    Returns:
      `true` if every values can be casted to the `float` type without data lost.
    Since:
      1.0

  - ### hasNaN

    public static boolean hasNaN(double[] array)
    Returns `true` if the specified array contains at least one `NaN` value.
    Parameters:
      `array` - the array to check, or `null`.
    Returns:
      `true` if the given array is non-null and contains at least one NaN value.

  - ### hasNaN

    public static boolean hasNaN(float[] array)
    Returns `true` if the specified array contains at least one `NaN` value.
    Parameters:
      `array` - the array to check, or `null`.
    Returns:
      `true` if the given array is non-null and contains at least one NaN value.

  - ### allEquals

    public static boolean allEquals(Object[] array, Object value)
    Returns `true` if all values in the specified array are equal to the specified value, which may be `null`.
    Parameters:
      `array` - the array to check.
      `value` - the expected value.
    Returns:
      `true` if all elements in the given array are equal to the given value.
    Since:
      0.8

  - ### allEquals

    public static boolean allEquals(double[] array, double value)
    Returns `true` if all values in the specified array are equal to the specified value, which may be `Double​.NaN`.
    Parameters:
      `array` - the array to check.
      `value` - the expected value.
    Returns:
      `true` if all elements in the given array are equal to the given value.

  - ### allEquals

    public static boolean allEquals(float[] array, float value)
    Returns `true` if all values in the specified array are equal to the specified value, which may be `Float​.NaN`.
    Parameters:
      `array` - the array to check.
      `value` - the expected value.
    Returns:
      `true` if all elements in the given array are equal to the given value.

  - ### containsIgnoreCase

    public static boolean containsIgnoreCase(String[] array, String value)
    Returns `true` if the specified array contains the specified value, ignoring case. This method should be used only for very small arrays.
    Parameters:
      `array` - the array to search in. May be `null`.
      `value` - the value to search.
    Returns:
      `true` if the array is non-null and contains the given value, or `false` otherwise.

  - ### containsIdentity

    public static boolean containsIdentity(Object[] array, Object value)
    Returns `true` if the specified array contains the specified reference. The comparisons are performed using the `==` operator.

    This method should be used only for very small arrays, or for searches to be performed only once, because it performs a linear search. If more than one search need to be done on the same array, consider using `IdentityHashMap` instead.

    Parameters:
      `array` - the array to search in. May be `null` and may contains null elements.
      `value` - the value to search. May be `null`.
    Returns:
      `true` if the array is non-null and contains the value (which may be null), or `false` otherwise.

  - ### contains

    public static boolean contains(Object[] array, Object value)
    Returns `true` if the specified array contains the specified value. The comparisons are performed using the `Object​.equals(Object)` method.

    This method should be used only for very small arrays, or for searches to be performed only once, because it performs a linear search. If more than one search need to be done on the same array, consider using `HashSet` instead.

    Parameters:
      `array` - the array to search in. May be `null` and may contains null elements.
      `value` - the value to search. May be `null`.
    Returns:
      `true` if the array is non-null and contains the value (which may be null), or `false` otherwise.
    See Also:
      - `intersects(Object[], Object[])`

  - ### intersects

    public static boolean intersects(Object[] array1, Object[] array2)
    Returns `true` if at least one element in the first array is equals to an element in the second array. The element doesn't need to be at the same index in both array.

    This method should be used only for very small arrays since it may be very slow. If the arrays are large or if an array will be involved in more than one search, consider using `HashSet` instead.

    Parameters:
      `array1` - the first array, or `null`.
      `array2` - the second array, or `null`.
    Returns:
      `true` if both array are non-null and have at least one element in common.
    See Also:
      - `contains(Object[], Object)`

  - ### concatenate

    @SafeVarargs public static <T> T[] concatenate(T[]... arrays)
    Returns the concatenation of all given arrays. This method performs the following checks:
    - If the `arrays` argument is `null` or contains only `null` elements, then this method returns `null`.
    - Otherwise if the `arrays` argument contains exactly one non-null array with a length greater than zero, then that array is returned. It is not copied.
    - Otherwise a new array with a length equals to the sum of the length of every non-null arrays is created, and the content of non-null arrays are appended in the new array in declaration order.
    Type Parameters:
      `T` - the type of arrays.
    Parameters:
      `arrays` - the arrays to concatenate, or `null`.
    Returns:
      the concatenation of all non-null arrays (may be a direct reference to one of the given array if it can be returned with no change), or `null`.
    See Also:
      - `append(Object[], Object)`
      - `unionOfSorted(int[], int[])`

  - ### unionOfSorted

    public static int[] unionOfSorted(int[] array1, int[] array2)
    Returns the union of two sorted arrays. The input arrays shall be sorted in strictly increasing order. The output array is the union of the input arrays without duplicated values, with elements sorted in strictly increasing order.

    #### Recommended assertions

    Callers are encouraged to place the following assertions before calls to this method, using the `isSorted(int[], boolean)` and `Arrays​.toString(int[])` methods:

    >     assert isSorted(array1, true) : toString(array1);
    >     assert isSorted(array2, true) : toString(array2);

    Parameters:
      `array1` - the first array, or `null`.
      `array2` - the second array, or `null`.
    Returns:
      the union of the given array without duplicated values, or `null` if the two given arrays were null. May be one of the given arrays.
    See Also:
      - `concatenate(Object[][])`