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 and Description
    --- | ---
    `static boolean[]` | `EMPTY_BOOLEAN` An empty array of `boolean` primitive type.
    `static byte[]` | `EMPTY_BYTE` An empty array of `byte` primitive type.
    `static char[]` | `EMPTY_CHAR` An empty array of `char` primitive type.
    `static double[]` | `EMPTY_DOUBLE` An empty array of `double` primitive type.
    `static float[]` | `EMPTY_FLOAT` An empty array of `float` primitive type.
    `static int[]` | `EMPTY_INT` An empty array of `int` primitive type.
    `static long[]` | `EMPTY_LONG` An empty array of `long` primitive type.
    `static short[]` | `EMPTY_SHORT` An empty array of `short` primitive type.

  - ### Method Summary

    All Methods Static Methods Concrete Methods
    Modifier and Type | Method and 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 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 <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 <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 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 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` | `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 <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 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 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 <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 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 int` | `removeDuplicated(Object[] array)` Removes the duplicated elements in the given array.
    `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 <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 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 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(Object[] data, int i0, int i1)` Swaps the elements at the given indices in the given array of `Object` 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 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 Detail

    - #### 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 Detail

    - #### 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 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(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 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(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 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(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 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(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 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(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 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(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 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(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 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(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.

    - #### 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

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

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

    - #### 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[][])`

Copyright © 2010–2017 The Apache Software Foundation. All rights reserved.