ArrayUtils.java

  1. /*
  2.  * Licensed to the Apache Software Foundation (ASF) under one or more
  3.  * contributor license agreements.  See the NOTICE file distributed with
  4.  * this work for additional information regarding copyright ownership.
  5.  * The ASF licenses this file to You under the Apache License, Version 2.0
  6.  * (the "License"); you may not use this file except in compliance with
  7.  * the License.  You may obtain a copy of the License at
  8.  *
  9.  *      http://www.apache.org/licenses/LICENSE-2.0
  10.  *
  11.  * Unless required by applicable law or agreed to in writing, software
  12.  * distributed under the License is distributed on an "AS IS" BASIS,
  13.  * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
  14.  * See the License for the specific language governing permissions and
  15.  * limitations under the License.
  16.  */
  17. package org.apache.commons.lang3;

  19. import java.lang.reflect.Array;
  20. import java.lang.reflect.Field;
  21. import java.lang.reflect.Method;
  22. import java.lang.reflect.Type;
  23. import java.util.Arrays;
  24. import java.util.BitSet;
  25. import java.util.Comparator;
  26. import java.util.Date;
  27. import java.util.HashMap;
  28. import java.util.Map;
  29. import java.util.Objects;
  30. import java.util.Random;
  31. import java.util.concurrent.ThreadLocalRandom;
  32. import java.util.function.Function;
  33. import java.util.function.IntFunction;
  34. import java.util.function.Supplier;

  36. import org.apache.commons.lang3.builder.EqualsBuilder;
  37. import org.apache.commons.lang3.builder.HashCodeBuilder;
  38. import org.apache.commons.lang3.builder.ToStringBuilder;
  39. import org.apache.commons.lang3.builder.ToStringStyle;
  40. import org.apache.commons.lang3.math.NumberUtils;
  41. import org.apache.commons.lang3.mutable.MutableInt;
  42. import org.apache.commons.lang3.stream.Streams;

  44. /**
  45.  * Operations on arrays, primitive arrays (like {@code int[]}) and
  46.  * primitive wrapper arrays (like {@code Integer[]}).
  47.  * <p>
  48.  * This class tries to handle {@code null} input gracefully.
  49.  * An exception will not be thrown for a {@code null}
  50.  * array input. However, an Object array that contains a {@code null}
  51.  * element may throw an exception. Each method documents its behavior.
  52.  * </p>
  53.  * <p>
  54.  * #ThreadSafe#
  55.  * </p>
  56.  * @since 2.0
  57.  */
  58. public class ArrayUtils {

  60.     /**
  61.      * An empty immutable {@code boolean} array.
  62.      */
  63.     public static final boolean[] EMPTY_BOOLEAN_ARRAY = {};

  65.     /**
  66.      * An empty immutable {@link Boolean} array.
  67.      */
  68.     public static final Boolean[] EMPTY_BOOLEAN_OBJECT_ARRAY = {};

  70.     /**
  71.      * An empty immutable {@code byte} array.
  72.      */
  73.     public static final byte[] EMPTY_BYTE_ARRAY = {};

  75.     /**
  76.      * An empty immutable {@link Byte} array.
  77.      */
  78.     public static final Byte[] EMPTY_BYTE_OBJECT_ARRAY = {};

  80.     /**
  81.      * An empty immutable {@code char} array.
  82.      */
  83.     public static final char[] EMPTY_CHAR_ARRAY = {};

  85.     /**
  86.      * An empty immutable {@link Character} array.
  87.      */
  88.     public static final Character[] EMPTY_CHARACTER_OBJECT_ARRAY = {};

  90.     /**
  91.      * An empty immutable {@link Class} array.
  92.      */
  93.     public static final Class<?>[] EMPTY_CLASS_ARRAY = {};

  95.     /**
  96.      * An empty immutable {@code double} array.
  97.      */
  98.     public static final double[] EMPTY_DOUBLE_ARRAY = {};

  100.     /**
  101.      * An empty immutable {@link Double} array.
  102.      */
  103.     public static final Double[] EMPTY_DOUBLE_OBJECT_ARRAY = {};

  105.     /**
  106.      * An empty immutable {@link Field} array.
  107.      *
  108.      * @since 3.10
  109.      */
  110.     public static final Field[] EMPTY_FIELD_ARRAY = {};

  112.     /**
  113.      * An empty immutable {@code float} array.
  114.      */
  115.     public static final float[] EMPTY_FLOAT_ARRAY = {};

  117.     /**
  118.      * An empty immutable {@link Float} array.
  119.      */
  120.     public static final Float[] EMPTY_FLOAT_OBJECT_ARRAY = {};

  122.     /**
  123.      * An empty immutable {@code int} array.
  124.      */
  125.     public static final int[] EMPTY_INT_ARRAY = {};

  127.     /**
  128.      * An empty immutable {@link Integer} array.
  129.      */
  130.     public static final Integer[] EMPTY_INTEGER_OBJECT_ARRAY = {};

  132.     /**
  133.      * An empty immutable {@code long} array.
  134.      */
  135.     public static final long[] EMPTY_LONG_ARRAY = {};

  137.     /**
  138.      * An empty immutable {@link Long} array.
  139.      */
  140.     public static final Long[] EMPTY_LONG_OBJECT_ARRAY = {};

  142.     /**
  143.      * An empty immutable {@link Method} array.
  144.      *
  145.      * @since 3.10
  146.      */
  147.     public static final Method[] EMPTY_METHOD_ARRAY = {};

  149.     /**
  150.      * An empty immutable {@link Object} array.
  151.      */
  152.     public static final Object[] EMPTY_OBJECT_ARRAY = {};

  154.     /**
  155.      * An empty immutable {@code short} array.
  156.      */
  157.     public static final short[] EMPTY_SHORT_ARRAY = {};

  159.     /**
  160.      * An empty immutable {@link Short} array.
  161.      */
  162.     public static final Short[] EMPTY_SHORT_OBJECT_ARRAY = {};

  164.     /**
  165.      * An empty immutable {@link String} array.
  166.      */
  167.     public static final String[] EMPTY_STRING_ARRAY = {};

  169.     /**
  170.      * An empty immutable {@link Throwable} array.
  171.      *
  172.      * @since 3.10
  173.      */
  174.     public static final Throwable[] EMPTY_THROWABLE_ARRAY = {};

  176.     /**
  177.      * An empty immutable {@link Type} array.
  178.      *
  179.      * @since 3.10
  180.      */
  181.     public static final Type[] EMPTY_TYPE_ARRAY = {};

  183.     /**
  184.      * The index value when an element is not found in a list or array: {@code -1}.
  185.      * This value is returned by methods in this class and can also be used in comparisons with values returned by
  186.      * various method from {@link java.util.List}.
  187.      */
  188.     public static final int INDEX_NOT_FOUND = -1;

  190.     /**
  191.      * Copies the given array and adds the given element at the end of the new array.
  192.      * <p>
  193.      * The new array contains the same elements of the input
  194.      * array plus the given element in the last position. The component type of
  195.      * the new array is the same as that of the input array.
  196.      * </p>
  197.      * <p>
  198.      * If the input array is {@code null}, a new one element array is returned
  199.      * whose component type is the same as the element.
  200.      * </p>
  201.      * <pre>
  202.      * ArrayUtils.add(null, true)          = [true]
  203.      * ArrayUtils.add([true], false)       = [true, false]
  204.      * ArrayUtils.add([true, false], true) = [true, false, true]
  205.      * </pre>
  206.      *
  207.      * @param array  the array to copy and add the element to, may be {@code null}
  208.      * @param element  the object to add at the last index of the new array
  209.      * @return A new array containing the existing elements plus the new element
  210.      * @since 2.1
  211.      */
  212.     public static boolean[] add(final boolean[] array, final boolean element) {
  213.         final boolean[] newArray = (boolean[]) copyArrayGrow1(array, Boolean.TYPE);
  214.         newArray[newArray.length - 1] = element;
  215.         return newArray;
  216.     }

  218.     /**
  219.      * Inserts the specified element at the specified position in the array.
  220.      * Shifts the element currently at that position (if any) and any subsequent
  221.      * elements to the right (adds one to their indices).
  222.      * <p>
  223.      * This method returns a new array with the same elements of the input
  224.      * array plus the given element on the specified position. The component
  225.      * type of the returned array is always the same as that of the input
  226.      * array.
  227.      * </p>
  228.      * <p>
  229.      * If the input array is {@code null}, a new one element array is returned
  230.      * whose component type is the same as the element.
  231.      * </p>
  232.      * <pre>
  233.      * ArrayUtils.add(null, 0, true)          = [true]
  234.      * ArrayUtils.add([true], 0, false)       = [false, true]
  235.      * ArrayUtils.add([false], 1, true)       = [false, true]
  236.      * ArrayUtils.add([true, false], 1, true) = [true, true, false]
  237.      * </pre>
  238.      *
  239.      * @param array  the array to add the element to, may be {@code null}
  240.      * @param index  the position of the new object
  241.      * @param element  the object to add
  242.      * @return A new array containing the existing elements and the new element
  243.      * @throws IndexOutOfBoundsException if the index is out of range (index &lt; 0 || index &gt; array.length).
  244.      * @deprecated this method has been superseded by {@link #insert(int, boolean[], boolean...)} and
  245.      * may be removed in a future release. Please note the handling of {@code null} input arrays differs
  246.      * in the new method: inserting {@code X} into a {@code null} array results in {@code null} not {@code X}.
  247.      */
  248.     @Deprecated
  249.     public static boolean[] add(final boolean[] array, final int index, final boolean element) {
  250.         return (boolean[]) add(array, index, Boolean.valueOf(element), Boolean.TYPE);
  251.     }

  253.     /**
  254.      * Copies the given array and adds the given element at the end of the new array.
  255.      * <p>
  256.      * The new array contains the same elements of the input
  257.      * array plus the given element in the last position. The component type of
  258.      * the new array is the same as that of the input array.
  259.      * </p>
  260.      * <p>
  261.      * If the input array is {@code null}, a new one element array is returned
  262.      * whose component type is the same as the element.
  263.      * </p>
  264.      * <pre>
  265.      * ArrayUtils.add(null, 0)   = [0]
  266.      * ArrayUtils.add([1], 0)    = [1, 0]
  267.      * ArrayUtils.add([1, 0], 1) = [1, 0, 1]
  268.      * </pre>
  269.      *
  270.      * @param array  the array to copy and add the element to, may be {@code null}
  271.      * @param element  the object to add at the last index of the new array
  272.      * @return A new array containing the existing elements plus the new element
  273.      * @since 2.1
  274.      */
  275.     public static byte[] add(final byte[] array, final byte element) {
  276.         final byte[] newArray = (byte[]) copyArrayGrow1(array, Byte.TYPE);
  277.         newArray[newArray.length - 1] = element;
  278.         return newArray;
  279.     }

  281.     /**
  282.      * Inserts the specified element at the specified position in the array.
  283.      * Shifts the element currently at that position (if any) and any subsequent
  284.      * elements to the right (adds one to their indices).
  285.      * <p>
  286.      * This method returns a new array with the same elements of the input
  287.      * array plus the given element on the specified position. The component
  288.      * type of the returned array is always the same as that of the input
  289.      * array.
  290.      * </p>
  291.      * <p>
  292.      * If the input array is {@code null}, a new one element array is returned
  293.      * whose component type is the same as the element.
  294.      * </p>
  295.      * <pre>
  296.      * ArrayUtils.add([1], 0, 2)         = [2, 1]
  297.      * ArrayUtils.add([2, 6], 2, 3)      = [2, 6, 3]
  298.      * ArrayUtils.add([2, 6], 0, 1)      = [1, 2, 6]
  299.      * ArrayUtils.add([2, 6, 3], 2, 1)   = [2, 6, 1, 3]
  300.      * </pre>
  301.      *
  302.      * @param array  the array to add the element to, may be {@code null}
  303.      * @param index  the position of the new object
  304.      * @param element  the object to add
  305.      * @return A new array containing the existing elements and the new element
  306.      * @throws IndexOutOfBoundsException if the index is out of range
  307.      * (index &lt; 0 || index &gt; array.length).
  308.      * @deprecated this method has been superseded by {@link #insert(int, byte[], byte...)} and
  309.      * may be removed in a future release. Please note the handling of {@code null} input arrays differs
  310.      * in the new method: inserting {@code X} into a {@code null} array results in {@code null} not {@code X}.
  311.      */
  312.     @Deprecated
  313.     public static byte[] add(final byte[] array, final int index, final byte element) {
  314.         return (byte[]) add(array, index, Byte.valueOf(element), Byte.TYPE);
  315.     }

  317.     /**
  318.      * Copies the given array and adds the given element at the end of the new array.
  319.      * <p>
  320.      * The new array contains the same elements of the input
  321.      * array plus the given element in the last position. The component type of
  322.      * the new array is the same as that of the input array.
  323.      * </p>
  324.      * <p>
  325.      * If the input array is {@code null}, a new one element array is returned
  326.      * whose component type is the same as the element.
  327.      * </p>
  328.      * <pre>
  329.      * ArrayUtils.add(null, '0')       = ['0']
  330.      * ArrayUtils.add(['1'], '0')      = ['1', '0']
  331.      * ArrayUtils.add(['1', '0'], '1') = ['1', '0', '1']
  332.      * </pre>
  333.      *
  334.      * @param array  the array to copy and add the element to, may be {@code null}
  335.      * @param element  the object to add at the last index of the new array
  336.      * @return A new array containing the existing elements plus the new element
  337.      * @since 2.1
  338.      */
  339.     public static char[] add(final char[] array, final char element) {
  340.         final char[] newArray = (char[]) copyArrayGrow1(array, Character.TYPE);
  341.         newArray[newArray.length - 1] = element;
  342.         return newArray;
  343.     }

  345.     /**
  346.      * Inserts the specified element at the specified position in the array.
  347.      * Shifts the element currently at that position (if any) and any subsequent
  348.      * elements to the right (adds one to their indices).
  349.      * <p>
  350.      * This method returns a new array with the same elements of the input
  351.      * array plus the given element on the specified position. The component
  352.      * type of the returned array is always the same as that of the input
  353.      * array.
  354.      * </p>
  355.      * <p>
  356.      * If the input array is {@code null}, a new one element array is returned
  357.      * whose component type is the same as the element.
  358.      * </p>
  359.      * <pre>
  360.      * ArrayUtils.add(null, 0, 'a')            = ['a']
  361.      * ArrayUtils.add(['a'], 0, 'b')           = ['b', 'a']
  362.      * ArrayUtils.add(['a', 'b'], 0, 'c')      = ['c', 'a', 'b']
  363.      * ArrayUtils.add(['a', 'b'], 1, 'k')      = ['a', 'k', 'b']
  364.      * ArrayUtils.add(['a', 'b', 'c'], 1, 't') = ['a', 't', 'b', 'c']
  365.      * </pre>
  366.      *
  367.      * @param array  the array to add the element to, may be {@code null}
  368.      * @param index  the position of the new object
  369.      * @param element  the object to add
  370.      * @return A new array containing the existing elements and the new element
  371.      * @throws IndexOutOfBoundsException if the index is out of range
  372.      * (index &lt; 0 || index &gt; array.length).
  373.      * @deprecated this method has been superseded by {@link #insert(int, char[], char...)} and
  374.      * may be removed in a future release. Please note the handling of {@code null} input arrays differs
  375.      * in the new method: inserting {@code X} into a {@code null} array results in {@code null} not {@code X}.
  376.      */
  377.     @Deprecated
  378.     public static char[] add(final char[] array, final int index, final char element) {
  379.         return (char[]) add(array, index, Character.valueOf(element), Character.TYPE);
  380.     }

  382.     /**
  383.      * Copies the given array and adds the given element at the end of the new array.
  384.      *
  385.      * <p>
  386.      * The new array contains the same elements of the input
  387.      * array plus the given element in the last position. The component type of
  388.      * the new array is the same as that of the input array.
  389.      * </p>
  390.      * <p>
  391.      * If the input array is {@code null}, a new one element array is returned
  392.      * whose component type is the same as the element.
  393.      * </p>
  394.      * <pre>
  395.      * ArrayUtils.add(null, 0)   = [0]
  396.      * ArrayUtils.add([1], 0)    = [1, 0]
  397.      * ArrayUtils.add([1, 0], 1) = [1, 0, 1]
  398.      * </pre>
  399.      *
  400.      * @param array  the array to copy and add the element to, may be {@code null}
  401.      * @param element  the object to add at the last index of the new array
  402.      * @return A new array containing the existing elements plus the new element
  403.      * @since 2.1
  404.      */
  405.     public static double[] add(final double[] array, final double element) {
  406.         final double[] newArray = (double[]) copyArrayGrow1(array, Double.TYPE);
  407.         newArray[newArray.length - 1] = element;
  408.         return newArray;
  409.     }

  411.     /**
  412.      * Inserts the specified element at the specified position in the array.
  413.      * Shifts the element currently at that position (if any) and any subsequent
  414.      * elements to the right (adds one to their indices).
  415.      * <p>
  416.      * This method returns a new array with the same elements of the input
  417.      * array plus the given element on the specified position. The component
  418.      * type of the returned array is always the same as that of the input
  419.      * array.
  420.      * </p>
  421.      * <p>
  422.      * If the input array is {@code null}, a new one element array is returned
  423.      * whose component type is the same as the element.
  424.      * </p>
  425.      * <pre>
  426.      * ArrayUtils.add([1.1], 0, 2.2)              = [2.2, 1.1]
  427.      * ArrayUtils.add([2.3, 6.4], 2, 10.5)        = [2.3, 6.4, 10.5]
  428.      * ArrayUtils.add([2.6, 6.7], 0, -4.8)        = [-4.8, 2.6, 6.7]
  429.      * ArrayUtils.add([2.9, 6.0, 0.3], 2, 1.0)    = [2.9, 6.0, 1.0, 0.3]
  430.      * </pre>
  431.      *
  432.      * @param array  the array to add the element to, may be {@code null}
  433.      * @param index  the position of the new object
  434.      * @param element  the object to add
  435.      * @return A new array containing the existing elements and the new element
  436.      * @throws IndexOutOfBoundsException if the index is out of range
  437.      * (index &lt; 0 || index &gt; array.length).
  438.      * @deprecated this method has been superseded by {@link #insert(int, double[], double...)} and
  439.      * may be removed in a future release. Please note the handling of {@code null} input arrays differs
  440.      * in the new method: inserting {@code X} into a {@code null} array results in {@code null} not {@code X}.
  441.      */
  442.     @Deprecated
  443.     public static double[] add(final double[] array, final int index, final double element) {
  444.         return (double[]) add(array, index, Double.valueOf(element), Double.TYPE);
  445.     }

  447.     /**
  448.      * Copies the given array and adds the given element at the end of the new array.
  449.      * <p>
  450.      * The new array contains the same elements of the input
  451.      * array plus the given element in the last position. The component type of
  452.      * the new array is the same as that of the input array.
  453.      * </p>
  454.      * <p>
  455.      * If the input array is {@code null}, a new one element array is returned
  456.      * whose component type is the same as the element.
  457.      * </p>
  458.      * <pre>
  459.      * ArrayUtils.add(null, 0)   = [0]
  460.      * ArrayUtils.add([1], 0)    = [1, 0]
  461.      * ArrayUtils.add([1, 0], 1) = [1, 0, 1]
  462.      * </pre>
  463.      *
  464.      * @param array  the array to copy and add the element to, may be {@code null}
  465.      * @param element  the object to add at the last index of the new array
  466.      * @return A new array containing the existing elements plus the new element
  467.      * @since 2.1
  468.      */
  469.     public static float[] add(final float[] array, final float element) {
  470.         final float[] newArray = (float[]) copyArrayGrow1(array, Float.TYPE);
  471.         newArray[newArray.length - 1] = element;
  472.         return newArray;
  473.     }

  475.     /**
  476.      * Inserts the specified element at the specified position in the array.
  477.      * Shifts the element currently at that position (if any) and any subsequent
  478.      * elements to the right (adds one to their indices).
  479.      * <p>
  480.      * This method returns a new array with the same elements of the input
  481.      * array plus the given element on the specified position. The component
  482.      * type of the returned array is always the same as that of the input
  483.      * array.
  484.      * </p>
  485.      * <p>
  486.      * If the input array is {@code null}, a new one element array is returned
  487.      * whose component type is the same as the element.
  488.      * </p>
  489.      * <pre>
  490.      * ArrayUtils.add([1.1f], 0, 2.2f)               = [2.2f, 1.1f]
  491.      * ArrayUtils.add([2.3f, 6.4f], 2, 10.5f)        = [2.3f, 6.4f, 10.5f]
  492.      * ArrayUtils.add([2.6f, 6.7f], 0, -4.8f)        = [-4.8f, 2.6f, 6.7f]
  493.      * ArrayUtils.add([2.9f, 6.0f, 0.3f], 2, 1.0f)   = [2.9f, 6.0f, 1.0f, 0.3f]
  494.      * </pre>
  495.      *
  496.      * @param array  the array to add the element to, may be {@code null}
  497.      * @param index  the position of the new object
  498.      * @param element  the object to add
  499.      * @return A new array containing the existing elements and the new element
  500.      * @throws IndexOutOfBoundsException if the index is out of range
  501.      * (index &lt; 0 || index &gt; array.length).
  502.      * @deprecated this method has been superseded by {@link #insert(int, float[], float...)} and
  503.      * may be removed in a future release. Please note the handling of {@code null} input arrays differs
  504.      * in the new method: inserting {@code X} into a {@code null} array results in {@code null} not {@code X}.
  505.      */
  506.     @Deprecated
  507.     public static float[] add(final float[] array, final int index, final float element) {
  508.         return (float[]) add(array, index, Float.valueOf(element), Float.TYPE);
  509.     }

  511.     /**
  512.      * Copies the given array and adds the given element at the end of the new array.
  513.      * <p>
  514.      * The new array contains the same elements of the input
  515.      * array plus the given element in the last position. The component type of
  516.      * the new array is the same as that of the input array.
  517.      * </p>
  518.      * <p>
  519.      * If the input array is {@code null}, a new one element array is returned
  520.      * whose component type is the same as the element.
  521.      * </p>
  522.      * <pre>
  523.      * ArrayUtils.add(null, 0)   = [0]
  524.      * ArrayUtils.add([1], 0)    = [1, 0]
  525.      * ArrayUtils.add([1, 0], 1) = [1, 0, 1]
  526.      * </pre>
  527.      *
  528.      * @param array  the array to copy and add the element to, may be {@code null}
  529.      * @param element  the object to add at the last index of the new array
  530.      * @return A new array containing the existing elements plus the new element
  531.      * @since 2.1
  532.      */
  533.     public static int[] add(final int[] array, final int element) {
  534.         final int[] newArray = (int[]) copyArrayGrow1(array, Integer.TYPE);
  535.         newArray[newArray.length - 1] = element;
  536.         return newArray;
  537.     }

  539.     /**
  540.      * Inserts the specified element at the specified position in the array.
  541.      * Shifts the element currently at that position (if any) and any subsequent
  542.      * elements to the right (adds one to their indices).
  543.      * <p>
  544.      * This method returns a new array with the same elements of the input
  545.      * array plus the given element on the specified position. The component
  546.      * type of the returned array is always the same as that of the input
  547.      * array.
  548.      * </p>
  549.      * <p>
  550.      * If the input array is {@code null}, a new one element array is returned
  551.      * whose component type is the same as the element.
  552.      * </p>
  553.      * <pre>
  554.      * ArrayUtils.add([1], 0, 2)         = [2, 1]
  555.      * ArrayUtils.add([2, 6], 2, 10)     = [2, 6, 10]
  556.      * ArrayUtils.add([2, 6], 0, -4)     = [-4, 2, 6]
  557.      * ArrayUtils.add([2, 6, 3], 2, 1)   = [2, 6, 1, 3]
  558.      * </pre>
  559.      *
  560.      * @param array  the array to add the element to, may be {@code null}
  561.      * @param index  the position of the new object
  562.      * @param element  the object to add
  563.      * @return A new array containing the existing elements and the new element
  564.      * @throws IndexOutOfBoundsException if the index is out of range
  565.      * (index &lt; 0 || index &gt; array.length).
  566.      * @deprecated this method has been superseded by {@link #insert(int, int[], int...)} and
  567.      * may be removed in a future release. Please note the handling of {@code null} input arrays differs
  568.      * in the new method: inserting {@code X} into a {@code null} array results in {@code null} not {@code X}.
  569.      */
  570.     @Deprecated
  571.     public static int[] add(final int[] array, final int index, final int element) {
  572.         return (int[]) add(array, index, Integer.valueOf(element), Integer.TYPE);
  573.     }

  575.     /**
  576.      * Inserts the specified element at the specified position in the array.
  577.      * Shifts the element currently at that position (if any) and any subsequent
  578.      * elements to the right (adds one to their indices).
  579.      * <p>
  580.      * This method returns a new array with the same elements of the input
  581.      * array plus the given element on the specified position. The component
  582.      * type of the returned array is always the same as that of the input
  583.      * array.
  584.      * </p>
  585.      * <p>
  586.      * If the input array is {@code null}, a new one element array is returned
  587.      * whose component type is the same as the element.
  588.      * </p>
  589.      * <pre>
  590.      * ArrayUtils.add([1L], 0, 2L)           = [2L, 1L]
  591.      * ArrayUtils.add([2L, 6L], 2, 10L)      = [2L, 6L, 10L]
  592.      * ArrayUtils.add([2L, 6L], 0, -4L)      = [-4L, 2L, 6L]
  593.      * ArrayUtils.add([2L, 6L, 3L], 2, 1L)   = [2L, 6L, 1L, 3L]
  594.      * </pre>
  595.      *
  596.      * @param array  the array to add the element to, may be {@code null}
  597.      * @param index  the position of the new object
  598.      * @param element  the object to add
  599.      * @return A new array containing the existing elements and the new element
  600.      * @throws IndexOutOfBoundsException if the index is out of range
  601.      * (index &lt; 0 || index &gt; array.length).
  602.      * @deprecated this method has been superseded by {@link #insert(int, long[], long...)} and
  603.      * may be removed in a future release. Please note the handling of {@code null} input arrays differs
  604.      * in the new method: inserting {@code X} into a {@code null} array results in {@code null} not {@code X}.
  605.      */
  606.     @Deprecated
  607.     public static long[] add(final long[] array, final int index, final long element) {
  608.         return (long[]) add(array, index, Long.valueOf(element), Long.TYPE);
  609.     }

  611.     /**
  612.      * Copies the given array and adds the given element at the end of the new array.
  613.      * <p>
  614.      * The new array contains the same elements of the input
  615.      * array plus the given element in the last position. The component type of
  616.      * the new array is the same as that of the input array.
  617.      * </p>
  618.      * <p>
  619.      * If the input array is {@code null}, a new one element array is returned
  620.      * whose component type is the same as the element.
  621.      * </p>
  622.      * <pre>
  623.      * ArrayUtils.add(null, 0)   = [0]
  624.      * ArrayUtils.add([1], 0)    = [1, 0]
  625.      * ArrayUtils.add([1, 0], 1) = [1, 0, 1]
  626.      * </pre>
  627.      *
  628.      * @param array  the array to copy and add the element to, may be {@code null}
  629.      * @param element  the object to add at the last index of the new array
  630.      * @return A new array containing the existing elements plus the new element
  631.      * @since 2.1
  632.      */
  633.     public static long[] add(final long[] array, final long element) {
  634.         final long[] newArray = (long[]) copyArrayGrow1(array, Long.TYPE);
  635.         newArray[newArray.length - 1] = element;
  636.         return newArray;
  637.     }

  639.     /**
  640.      * Underlying implementation of add(array, index, element) methods.
  641.      * The last parameter is the class, which may not equal element.getClass
  642.      * for primitives.
  643.      *
  644.      * @param array  the array to add the element to, may be {@code null}
  645.      * @param index  the position of the new object
  646.      * @param element  the object to add
  647.      * @param clazz the type of the element being added
  648.      * @return A new array containing the existing elements and the new element
  649.      */
  650.     private static Object add(final Object array, final int index, final Object element, final Class<?> clazz) {
  651.         if (array == null) {
  652.             if (index != 0) {
  653.                 throw new IndexOutOfBoundsException("Index: " + index + ", Length: 0");
  654.             }
  655.             final Object joinedArray = Array.newInstance(clazz, 1);
  656.             Array.set(joinedArray, 0, element);
  657.             return joinedArray;
  658.         }
  659.         final int length = Array.getLength(array);
  660.         if (index > length || index < 0) {
  661.             throw new IndexOutOfBoundsException("Index: " + index + ", Length: " + length);
  662.         }
  663.         final Object result = arraycopy(array, 0, 0, index, () -> Array.newInstance(clazz, length + 1));
  664.         Array.set(result, index, element);
  665.         if (index < length) {
  666.             System.arraycopy(array, index, result, index + 1, length - index);
  667.         }
  668.         return result;
  669.     }

  671.     /**
  672.      * Inserts the specified element at the specified position in the array.
  673.      * Shifts the element currently at that position (if any) and any subsequent
  674.      * elements to the right (adds one to their indices).
  675.      * <p>
  676.      * This method returns a new array with the same elements of the input
  677.      * array plus the given element on the specified position. The component
  678.      * type of the returned array is always the same as that of the input
  679.      * array.
  680.      * </p>
  681.      * <p>
  682.      * If the input array is {@code null}, a new one element array is returned
  683.      * whose component type is the same as the element.
  684.      * </p>
  685.      * <pre>
  686.      * ArrayUtils.add([1], 0, 2)         = [2, 1]
  687.      * ArrayUtils.add([2, 6], 2, 10)     = [2, 6, 10]
  688.      * ArrayUtils.add([2, 6], 0, -4)     = [-4, 2, 6]
  689.      * ArrayUtils.add([2, 6, 3], 2, 1)   = [2, 6, 1, 3]
  690.      * </pre>
  691.      *
  692.      * @param array  the array to add the element to, may be {@code null}
  693.      * @param index  the position of the new object
  694.      * @param element  the object to add
  695.      * @return A new array containing the existing elements and the new element
  696.      * @throws IndexOutOfBoundsException if the index is out of range
  697.      * (index &lt; 0 || index &gt; array.length).
  698.      * @deprecated this method has been superseded by {@link #insert(int, short[], short...)} and
  699.      * may be removed in a future release. Please note the handling of {@code null} input arrays differs
  700.      * in the new method: inserting {@code X} into a {@code null} array results in {@code null} not {@code X}.
  701.      */
  702.     @Deprecated
  703.     public static short[] add(final short[] array, final int index, final short element) {
  704.         return (short[]) add(array, index, Short.valueOf(element), Short.TYPE);
  705.     }

  707.     /**
  708.      * Copies the given array and adds the given element at the end of the new array.
  709.      * <p>
  710.      * The new array contains the same elements of the input
  711.      * array plus the given element in the last position. The component type of
  712.      * the new array is the same as that of the input array.
  713.      * </p>
  714.      * <p>
  715.      * If the input array is {@code null}, a new one element array is returned
  716.      * whose component type is the same as the element.
  717.      * </p>
  718.      * <pre>
  719.      * ArrayUtils.add(null, 0)   = [0]
  720.      * ArrayUtils.add([1], 0)    = [1, 0]
  721.      * ArrayUtils.add([1, 0], 1) = [1, 0, 1]
  722.      * </pre>
  723.      *
  724.      * @param array  the array to copy and add the element to, may be {@code null}
  725.      * @param element  the object to add at the last index of the new array
  726.      * @return A new array containing the existing elements plus the new element
  727.      * @since 2.1
  728.      */
  729.     public static short[] add(final short[] array, final short element) {
  730.         final short[] newArray = (short[]) copyArrayGrow1(array, Short.TYPE);
  731.         newArray[newArray.length - 1] = element;
  732.         return newArray;
  733.     }

  735.     /**
  736.      * Inserts the specified element at the specified position in the array.
  737.      * Shifts the element currently at that position (if any) and any subsequent
  738.      * elements to the right (adds one to their indices).
  739.      * <p>
  740.      * This method returns a new array with the same elements of the input
  741.      * array plus the given element on the specified position. The component
  742.      * type of the returned array is always the same as that of the input
  743.      * array.
  744.      * </p>
  745.      * <p>
  746.      * If the input array is {@code null}, a new one element array is returned
  747.      * whose component type is the same as the element.
  748.      * </p>
  749.      * <pre>
  750.      * ArrayUtils.add(null, 0, null)      = IllegalArgumentException
  751.      * ArrayUtils.add(null, 0, "a")       = ["a"]
  752.      * ArrayUtils.add(["a"], 1, null)     = ["a", null]
  753.      * ArrayUtils.add(["a"], 1, "b")      = ["a", "b"]
  754.      * ArrayUtils.add(["a", "b"], 3, "c") = ["a", "b", "c"]
  755.      * </pre>
  756.      *
  757.      * @param <T> the component type of the array
  758.      * @param array  the array to add the element to, may be {@code null}
  759.      * @param index  the position of the new object
  760.      * @param element  the object to add
  761.      * @return A new array containing the existing elements and the new element
  762.      * @throws IndexOutOfBoundsException if the index is out of range (index &lt; 0 || index &gt; array.length).
  763.      * @throws IllegalArgumentException if both array and element are null
  764.      * @deprecated this method has been superseded by {@link #insert(int, Object[], Object...) insert(int, T[], T...)} and
  765.      * may be removed in a future release. Please note the handling of {@code null} input arrays differs
  766.      * in the new method: inserting {@code X} into a {@code null} array results in {@code null} not {@code X}.
  767.      */
  768.     @Deprecated
  769.     public static <T> T[] add(final T[] array, final int index, final T element) {
  770.         final Class<T> clazz;
  771.         if (array != null) {
  772.             clazz = getComponentType(array);
  773.         } else if (element != null) {
  774.             clazz = ObjectUtils.getClass(element);
  775.         } else {
  776.             throw new IllegalArgumentException("Array and element cannot both be null");
  777.         }
  778.         return (T[]) add(array, index, element, clazz);
  779.     }

  781.     /**
  782.      * Copies the given array and adds the given element at the end of the new array.
  783.      * <p>
  784.      * The new array contains the same elements of the input
  785.      * array plus the given element in the last position. The component type of
  786.      * the new array is the same as that of the input array.
  787.      * </p>
  788.      * <p>
  789.      * If the input array is {@code null}, a new one element array is returned
  790.      * whose component type is the same as the element, unless the element itself is null,
  791.      * in which case the return type is Object[]
  792.      * </p>
  793.      * <pre>
  794.      * ArrayUtils.add(null, null)      = IllegalArgumentException
  795.      * ArrayUtils.add(null, "a")       = ["a"]
  796.      * ArrayUtils.add(["a"], null)     = ["a", null]
  797.      * ArrayUtils.add(["a"], "b")      = ["a", "b"]
  798.      * ArrayUtils.add(["a", "b"], "c") = ["a", "b", "c"]
  799.      * </pre>
  800.      *
  801.      * @param <T> the component type of the array
  802.      * @param array  the array to "add" the element to, may be {@code null}
  803.      * @param element  the object to add, may be {@code null}
  804.      * @return A new array containing the existing elements plus the new element
  805.      * The returned array type will be that of the input array (unless null),
  806.      * in which case it will have the same type as the element.
  807.      * If both are null, an IllegalArgumentException is thrown
  808.      * @since 2.1
  809.      * @throws IllegalArgumentException if both arguments are null
  810.      */
  811.     public static <T> T[] add(final T[] array, final T element) {
  812.         final Class<?> type;
  813.         if (array != null) {
  814.             type = array.getClass().getComponentType();
  815.         } else if (element != null) {
  816.             type = element.getClass();
  817.         } else {
  818.             throw new IllegalArgumentException("Arguments cannot both be null");
  819.         }
  820.         @SuppressWarnings("unchecked") // type must be T
  821.         final
  822.         T[] newArray = (T[]) copyArrayGrow1(array, type);
  823.         newArray[newArray.length - 1] = element;
  824.         return newArray;
  825.     }

  827.     /**
  828.      * Adds all the elements of the given arrays into a new array.
  829.      * <p>
  830.      * The new array contains all of the element of {@code array1} followed
  831.      * by all of the elements {@code array2}. When an array is returned, it is always
  832.      * a new array.
  833.      * </p>
  834.      * <pre>
  835.      * ArrayUtils.addAll(array1, null)   = cloned copy of array1
  836.      * ArrayUtils.addAll(null, array2)   = cloned copy of array2
  837.      * ArrayUtils.addAll([], [])         = []
  838.      * ArrayUtils.addAll(null, null)     = null
  839.      * </pre>
  840.      *
  841.      * @param array1  the first array whose elements are added to the new array.
  842.      * @param array2  the second array whose elements are added to the new array.
  843.      * @return The new boolean[] array or {@code null}.
  844.      * @since 2.1
  845.      */
  846.     public static boolean[] addAll(final boolean[] array1, final boolean... array2) {
  847.         if (array1 == null) {
  848.             return clone(array2);
  849.         }
  850.         if (array2 == null) {
  851.             return clone(array1);
  852.         }
  853.         final boolean[] joinedArray = new boolean[array1.length + array2.length];
  854.         System.arraycopy(array1, 0, joinedArray, 0, array1.length);
  855.         System.arraycopy(array2, 0, joinedArray, array1.length, array2.length);
  856.         return joinedArray;
  857.     }

  859.     /**
  860.      * Adds all the elements of the given arrays into a new array.
  861.      * <p>
  862.      * The new array contains all of the element of {@code array1} followed
  863.      * by all of the elements {@code array2}. When an array is returned, it is always
  864.      * a new array.
  865.      * </p>
  866.      * <pre>
  867.      * ArrayUtils.addAll(array1, null)   = cloned copy of array1
  868.      * ArrayUtils.addAll(null, array2)   = cloned copy of array2
  869.      * ArrayUtils.addAll([], [])         = []
  870.      * ArrayUtils.addAll(null, null)     = null
  871.      * </pre>
  872.      *
  873.      * @param array1  the first array whose elements are added to the new array.
  874.      * @param array2  the second array whose elements are added to the new array.
  875.      * @return The new byte[] array or {@code null}.
  876.      * @since 2.1
  877.      */
  878.     public static byte[] addAll(final byte[] array1, final byte... array2) {
  879.         if (array1 == null) {
  880.             return clone(array2);
  881.         }
  882.         if (array2 == null) {
  883.             return clone(array1);
  884.         }
  885.         final byte[] joinedArray = new byte[array1.length + array2.length];
  886.         System.arraycopy(array1, 0, joinedArray, 0, array1.length);
  887.         System.arraycopy(array2, 0, joinedArray, array1.length, array2.length);
  888.         return joinedArray;
  889.     }

  891.     /**
  892.      * Adds all the elements of the given arrays into a new array.
  893.      * <p>
  894.      * The new array contains all of the element of {@code array1} followed
  895.      * by all of the elements {@code array2}. When an array is returned, it is always
  896.      * a new array.
  897.      * </p>
  898.      * <pre>
  899.      * ArrayUtils.addAll(array1, null)   = cloned copy of array1
  900.      * ArrayUtils.addAll(null, array2)   = cloned copy of array2
  901.      * ArrayUtils.addAll([], [])         = []
  902.      * ArrayUtils.addAll(null, null)     = null
  903.      * </pre>
  904.      *
  905.      * @param array1  the first array whose elements are added to the new array.
  906.      * @param array2  the second array whose elements are added to the new array.
  907.      * @return The new char[] array or {@code null}.
  908.      * @since 2.1
  909.      */
  910.     public static char[] addAll(final char[] array1, final char... array2) {
  911.         if (array1 == null) {
  912.             return clone(array2);
  913.         }
  914.         if (array2 == null) {
  915.             return clone(array1);
  916.         }
  917.         final char[] joinedArray = new char[array1.length + array2.length];
  918.         System.arraycopy(array1, 0, joinedArray, 0, array1.length);
  919.         System.arraycopy(array2, 0, joinedArray, array1.length, array2.length);
  920.         return joinedArray;
  921.     }

  923.     /**
  924.      * Adds all the elements of the given arrays into a new array.
  925.      * <p>
  926.      * The new array contains all of the element of {@code array1} followed
  927.      * by all of the elements {@code array2}. When an array is returned, it is always
  928.      * a new array.
  929.      * </p>
  930.      * <pre>
  931.      * ArrayUtils.addAll(array1, null)   = cloned copy of array1
  932.      * ArrayUtils.addAll(null, array2)   = cloned copy of array2
  933.      * ArrayUtils.addAll([], [])         = []
  934.      * ArrayUtils.addAll(null, null)     = null
  935.      * </pre>
  936.      *
  937.      * @param array1  the first array whose elements are added to the new array.
  938.      * @param array2  the second array whose elements are added to the new array.
  939.      * @return The new double[] array or {@code null}.
  940.      * @since 2.1
  941.      */
  942.     public static double[] addAll(final double[] array1, final double... array2) {
  943.         if (array1 == null) {
  944.             return clone(array2);
  945.         }
  946.         if (array2 == null) {
  947.             return clone(array1);
  948.         }
  949.         final double[] joinedArray = new double[array1.length + array2.length];
  950.         System.arraycopy(array1, 0, joinedArray, 0, array1.length);
  951.         System.arraycopy(array2, 0, joinedArray, array1.length, array2.length);
  952.         return joinedArray;
  953.     }

  955.     /**
  956.      * Adds all the elements of the given arrays into a new array.
  957.      * <p>
  958.      * The new array contains all of the element of {@code array1} followed
  959.      * by all of the elements {@code array2}. When an array is returned, it is always
  960.      * a new array.
  961.      * </p>
  962.      * <pre>
  963.      * ArrayUtils.addAll(array1, null)   = cloned copy of array1
  964.      * ArrayUtils.addAll(null, array2)   = cloned copy of array2
  965.      * ArrayUtils.addAll([], [])         = []
  966.      * ArrayUtils.addAll(null, null)     = null
  967.      * </pre>
  968.      *
  969.      * @param array1  the first array whose elements are added to the new array.
  970.      * @param array2  the second array whose elements are added to the new array.
  971.      * @return The new float[] array or {@code null}.
  972.      * @since 2.1
  973.      */
  974.     public static float[] addAll(final float[] array1, final float... array2) {
  975.         if (array1 == null) {
  976.             return clone(array2);
  977.         }
  978.         if (array2 == null) {
  979.             return clone(array1);
  980.         }
  981.         final float[] joinedArray = new float[array1.length + array2.length];
  982.         System.arraycopy(array1, 0, joinedArray, 0, array1.length);
  983.         System.arraycopy(array2, 0, joinedArray, array1.length, array2.length);
  984.         return joinedArray;
  985.     }

  987.     /**
  988.      * Adds all the elements of the given arrays into a new array.
  989.      * <p>
  990.      * The new array contains all of the element of {@code array1} followed
  991.      * by all of the elements {@code array2}. When an array is returned, it is always
  992.      * a new array.
  993.      * </p>
  994.      * <pre>
  995.      * ArrayUtils.addAll(array1, null)   = cloned copy of array1
  996.      * ArrayUtils.addAll(null, array2)   = cloned copy of array2
  997.      * ArrayUtils.addAll([], [])         = []
  998.      * ArrayUtils.addAll(null, null)     = null
  999.      * </pre>
  1000.      *
  1001.      * @param array1  the first array whose elements are added to the new array.
  1002.      * @param array2  the second array whose elements are added to the new array.
  1003.      * @return The new int[] array or {@code null}.
  1004.      * @since 2.1
  1005.      */
  1006.     public static int[] addAll(final int[] array1, final int... array2) {
  1007.         if (array1 == null) {
  1008.             return clone(array2);
  1009.         }
  1010.         if (array2 == null) {
  1011.             return clone(array1);
  1012.         }
  1013.         final int[] joinedArray = new int[array1.length + array2.length];
  1014.         System.arraycopy(array1, 0, joinedArray, 0, array1.length);
  1015.         System.arraycopy(array2, 0, joinedArray, array1.length, array2.length);
  1016.         return joinedArray;
  1017.     }

  1019.     /**
  1020.      * Adds all the elements of the given arrays into a new array.
  1021.      * <p>
  1022.      * The new array contains all of the element of {@code array1} followed
  1023.      * by all of the elements {@code array2}. When an array is returned, it is always
  1024.      * a new array.
  1025.      * </p>
  1026.      * <pre>
  1027.      * ArrayUtils.addAll(array1, null)   = cloned copy of array1
  1028.      * ArrayUtils.addAll(null, array2)   = cloned copy of array2
  1029.      * ArrayUtils.addAll([], [])         = []
  1030.      * ArrayUtils.addAll(null, null)     = null
  1031.      * </pre>
  1032.      *
  1033.      * @param array1  the first array whose elements are added to the new array.
  1034.      * @param array2  the second array whose elements are added to the new array.
  1035.      * @return The new long[] array or {@code null}.
  1036.      * @since 2.1
  1037.      */
  1038.     public static long[] addAll(final long[] array1, final long... array2) {
  1039.         if (array1 == null) {
  1040.             return clone(array2);
  1041.         }
  1042.         if (array2 == null) {
  1043.             return clone(array1);
  1044.         }
  1045.         final long[] joinedArray = new long[array1.length + array2.length];
  1046.         System.arraycopy(array1, 0, joinedArray, 0, array1.length);
  1047.         System.arraycopy(array2, 0, joinedArray, array1.length, array2.length);
  1048.         return joinedArray;
  1049.     }

  1051.     /**
  1052.      * Adds all the elements of the given arrays into a new array.
  1053.      * <p>
  1054.      * The new array contains all of the element of {@code array1} followed
  1055.      * by all of the elements {@code array2}. When an array is returned, it is always
  1056.      * a new array.
  1057.      * </p>
  1058.      * <pre>
  1059.      * ArrayUtils.addAll(array1, null)   = cloned copy of array1
  1060.      * ArrayUtils.addAll(null, array2)   = cloned copy of array2
  1061.      * ArrayUtils.addAll([], [])         = []
  1062.      * ArrayUtils.addAll(null, null)     = null
  1063.      * </pre>
  1064.      *
  1065.      * @param array1  the first array whose elements are added to the new array.
  1066.      * @param array2  the second array whose elements are added to the new array.
  1067.      * @return The new short[] array or {@code null}.
  1068.      * @since 2.1
  1069.      */
  1070.     public static short[] addAll(final short[] array1, final short... array2) {
  1071.         if (array1 == null) {
  1072.             return clone(array2);
  1073.         }
  1074.         if (array2 == null) {
  1075.             return clone(array1);
  1076.         }
  1077.         final short[] joinedArray = new short[array1.length + array2.length];
  1078.         System.arraycopy(array1, 0, joinedArray, 0, array1.length);
  1079.         System.arraycopy(array2, 0, joinedArray, array1.length, array2.length);
  1080.         return joinedArray;
  1081.     }

  1083.     /**
  1084.      * Adds all the elements of the given arrays into a new array.
  1085.      * <p>
  1086.      * The new array contains all of the element of {@code array1} followed
  1087.      * by all of the elements {@code array2}. When an array is returned, it is always
  1088.      * a new array.
  1089.      * </p>
  1090.      * <pre>
  1091.      * ArrayUtils.addAll(null, null)     = null
  1092.      * ArrayUtils.addAll(array1, null)   = cloned copy of array1
  1093.      * ArrayUtils.addAll(null, array2)   = cloned copy of array2
  1094.      * ArrayUtils.addAll([], [])         = []
  1095.      * ArrayUtils.addAll(null, null)     = null
  1096.      * ArrayUtils.addAll([null], [null]) = [null, null]
  1097.      * ArrayUtils.addAll(["a", "b", "c"], ["1", "2", "3"]) = ["a", "b", "c", "1", "2", "3"]
  1098.      * </pre>
  1099.      *
  1100.      * @param <T> the component type of the array
  1101.      * @param array1  the first array whose elements are added to the new array, may be {@code null}
  1102.      * @param array2  the second array whose elements are added to the new array, may be {@code null}
  1103.      * @return The new array, {@code null} if both arrays are {@code null}.
  1104.      *      The type of the new array is the type of the first array,
  1105.      *      unless the first array is null, in which case the type is the same as the second array.
  1106.      * @since 2.1
  1107.      * @throws IllegalArgumentException if the array types are incompatible
  1108.      */
  1109.     public static <T> T[] addAll(final T[] array1, @SuppressWarnings("unchecked") final T... array2) {
  1110.         if (array1 == null) {
  1111.             return clone(array2);
  1112.         }
  1113.         if (array2 == null) {
  1114.             return clone(array1);
  1115.         }
  1116.         final Class<T> type1 = getComponentType(array1);
  1117.         final T[] joinedArray = arraycopy(array1, 0, 0, array1.length, () -> newInstance(type1, array1.length + array2.length));
  1118.         try {
  1119.             System.arraycopy(array2, 0, joinedArray, array1.length, array2.length);
  1120.         } catch (final ArrayStoreException ase) {
  1121.             // Check if problem was due to incompatible types
  1122.             /*
  1123.              * We do this here, rather than before the copy because: - it would be a wasted check most of the time - safer, in case check turns out to be too
  1124.              * strict
  1125.              */
  1126.             final Class<?> type2 = array2.getClass().getComponentType();
  1127.             if (!type1.isAssignableFrom(type2)) {
  1128.                 throw new IllegalArgumentException("Cannot store " + type2.getName() + " in an array of " + type1.getName(), ase);
  1129.             }
  1130.             throw ase; // No, so rethrow original
  1131.         }
  1132.         return joinedArray;
  1133.     }

  1135.     /**
  1136.      * Copies the given array and adds the given element at the beginning of the new array.
  1137.      * <p>
  1138.      * The new array contains the same elements of the input array plus the given element in the first position. The
  1139.      * component type of the new array is the same as that of the input array.
  1140.      * </p>
  1141.      * <p>
  1142.      * If the input array is {@code null}, a new one element array is returned whose component type is the same as the
  1143.      * element.
  1144.      * </p>
  1145.      * <pre>
  1146.      * ArrayUtils.addFirst(null, true)          = [true]
  1147.      * ArrayUtils.addFirst([true], false)       = [false, true]
  1148.      * ArrayUtils.addFirst([true, false], true) = [true, true, false]
  1149.      * </pre>
  1150.      *
  1151.      * @param array the array to "add" the element to, may be {@code null}.
  1152.      * @param element the object to add.
  1153.      * @return A new array containing the existing elements plus the new element The returned array type will be that of
  1154.      *         the input array (unless null), in which case it will have the same type as the element.
  1155.      * @since 3.10
  1156.      */
  1157.     public static boolean[] addFirst(final boolean[] array, final boolean element) {
  1158.         return array == null ? add(array, element) : insert(0, array, element);
  1159.     }

  1161.     /**
  1162.      * Copies the given array and adds the given element at the beginning of the new array.
  1163.      * <p>
  1164.      * The new array contains the same elements of the input array plus the given element in the first position. The
  1165.      * component type of the new array is the same as that of the input array.
  1166.      * </p>
  1167.      * <p>
  1168.      * If the input array is {@code null}, a new one element array is returned whose component type is the same as the
  1169.      * element.
  1170.      * </p>
  1171.      * <pre>
  1172.      * ArrayUtils.addFirst(null, 1)   = [1]
  1173.      * ArrayUtils.addFirst([1], 0)    = [0, 1]
  1174.      * ArrayUtils.addFirst([1, 0], 1) = [1, 1, 0]
  1175.      * </pre>
  1176.      *
  1177.      * @param array the array to "add" the element to, may be {@code null}.
  1178.      * @param element the object to add.
  1179.      * @return A new array containing the existing elements plus the new element The returned array type will be that of
  1180.      *         the input array (unless null), in which case it will have the same type as the element.
  1181.      * @since 3.10
  1182.      */
  1183.     public static byte[] addFirst(final byte[] array, final byte element) {
  1184.         return array == null ? add(array, element) : insert(0, array, element);
  1185.     }

  1187.     /**
  1188.      * Copies the given array and adds the given element at the beginning of the new array.
  1189.      * <p>
  1190.      * The new array contains the same elements of the input array plus the given element in the first position. The
  1191.      * component type of the new array is the same as that of the input array.
  1192.      * </p>
  1193.      * <p>
  1194.      * If the input array is {@code null}, a new one element array is returned whose component type is the same as the
  1195.      * element.
  1196.      * </p>
  1197.      * <pre>
  1198.      * ArrayUtils.addFirst(null, '1')       = ['1']
  1199.      * ArrayUtils.addFirst(['1'], '0')      = ['0', '1']
  1200.      * ArrayUtils.addFirst(['1', '0'], '1') = ['1', '1', '0']
  1201.      * </pre>
  1202.      *
  1203.      * @param array the array to "add" the element to, may be {@code null}.
  1204.      * @param element the object to add.
  1205.      * @return A new array containing the existing elements plus the new element The returned array type will be that of
  1206.      *         the input array (unless null), in which case it will have the same type as the element.
  1207.      * @since 3.10
  1208.      */
  1209.     public static char[] addFirst(final char[] array, final char element) {
  1210.         return array == null ? add(array, element) : insert(0, array, element);
  1211.     }

  1213.     /**
  1214.      * Copies the given array and adds the given element at the beginning of the new array.
  1215.      * <p>
  1216.      * The new array contains the same elements of the input array plus the given element in the first position. The
  1217.      * component type of the new array is the same as that of the input array.
  1218.      * </p>
  1219.      * <p>
  1220.      * If the input array is {@code null}, a new one element array is returned whose component type is the same as the
  1221.      * element.
  1222.      * </p>
  1223.      * <pre>
  1224.      * ArrayUtils.addFirst(null, 1)   = [1]
  1225.      * ArrayUtils.addFirst([1], 0)    = [0, 1]
  1226.      * ArrayUtils.addFirst([1, 0], 1) = [1, 1, 0]
  1227.      * </pre>
  1228.      *
  1229.      * @param array the array to "add" the element to, may be {@code null}.
  1230.      * @param element the object to add.
  1231.      * @return A new array containing the existing elements plus the new element The returned array type will be that of
  1232.      *         the input array (unless null), in which case it will have the same type as the element.
  1233.      * @since 3.10
  1234.      */
  1235.     public static double[] addFirst(final double[] array, final double element) {
  1236.         return array == null ? add(array, element) : insert(0, array, element);
  1237.     }

  1239.     /**
  1240.      * Copies the given array and adds the given element at the beginning of the new array.
  1241.      * <p>
  1242.      * The new array contains the same elements of the input array plus the given element in the first position. The
  1243.      * component type of the new array is the same as that of the input array.
  1244.      * </p>
  1245.      * <p>
  1246.      * If the input array is {@code null}, a new one element array is returned whose component type is the same as the
  1247.      * element.
  1248.      * </p>
  1249.      * <pre>
  1250.      * ArrayUtils.addFirst(null, 1)   = [1]
  1251.      * ArrayUtils.addFirst([1], 0)    = [0, 1]
  1252.      * ArrayUtils.addFirst([1, 0], 1) = [1, 1, 0]
  1253.      * </pre>
  1254.      *
  1255.      * @param array the array to "add" the element to, may be {@code null}.
  1256.      * @param element the object to add.
  1257.      * @return A new array containing the existing elements plus the new element The returned array type will be that of
  1258.      *         the input array (unless null), in which case it will have the same type as the element.
  1259.      * @since 3.10
  1260.      */
  1261.     public static float[] addFirst(final float[] array, final float element) {
  1262.         return array == null ? add(array, element) : insert(0, array, element);
  1263.     }

  1265.     /**
  1266.      * Copies the given array and adds the given element at the beginning of the new array.
  1267.      * <p>
  1268.      * The new array contains the same elements of the input array plus the given element in the first position. The
  1269.      * component type of the new array is the same as that of the input array.
  1270.      * </p>
  1271.      * <p>
  1272.      * If the input array is {@code null}, a new one element array is returned whose component type is the same as the
  1273.      * element.
  1274.      * </p>
  1275.      * <pre>
  1276.      * ArrayUtils.addFirst(null, 1)   = [1]
  1277.      * ArrayUtils.addFirst([1], 0)    = [0, 1]
  1278.      * ArrayUtils.addFirst([1, 0], 1) = [1, 1, 0]
  1279.      * </pre>
  1280.      *
  1281.      * @param array the array to "add" the element to, may be {@code null}.
  1282.      * @param element the object to add.
  1283.      * @return A new array containing the existing elements plus the new element The returned array type will be that of
  1284.      *         the input array (unless null), in which case it will have the same type as the element.
  1285.      * @since 3.10
  1286.      */
  1287.     public static int[] addFirst(final int[] array, final int element) {
  1288.         return array == null ? add(array, element) : insert(0, array, element);
  1289.     }

  1291.     /**
  1292.      * Copies the given array and adds the given element at the beginning of the new array.
  1293.      * <p>
  1294.      * The new array contains the same elements of the input array plus the given element in the first position. The
  1295.      * component type of the new array is the same as that of the input array.
  1296.      * </p>
  1297.      * <p>
  1298.      * If the input array is {@code null}, a new one element array is returned whose component type is the same as the
  1299.      * element.
  1300.      * </p>
  1301.      * <pre>
  1302.      * ArrayUtils.addFirst(null, 1)   = [1]
  1303.      * ArrayUtils.addFirst([1], 0)    = [0, 1]
  1304.      * ArrayUtils.addFirst([1, 0], 1) = [1, 1, 0]
  1305.      * </pre>
  1306.      *
  1307.      * @param array the array to "add" the element to, may be {@code null}.
  1308.      * @param element the object to add.
  1309.      * @return A new array containing the existing elements plus the new element The returned array type will be that of
  1310.      *         the input array (unless null), in which case it will have the same type as the element.
  1311.      * @since 3.10
  1312.      */
  1313.     public static long[] addFirst(final long[] array, final long element) {
  1314.         return array == null ? add(array, element) : insert(0, array, element);
  1315.     }

  1317.     /**
  1318.      * Copies the given array and adds the given element at the beginning of the new array.
  1319.      * <p>
  1320.      * The new array contains the same elements of the input array plus the given element in the first position. The
  1321.      * component type of the new array is the same as that of the input array.
  1322.      * </p>
  1323.      * <p>
  1324.      * If the input array is {@code null}, a new one element array is returned whose component type is the same as the
  1325.      * element.
  1326.      * </p>
  1327.      * <pre>
  1328.      * ArrayUtils.addFirst(null, 1)   = [1]
  1329.      * ArrayUtils.addFirst([1], 0)    = [0, 1]
  1330.      * ArrayUtils.addFirst([1, 0], 1) = [1, 1, 0]
  1331.      * </pre>
  1332.      *
  1333.      * @param array the array to "add" the element to, may be {@code null}.
  1334.      * @param element the object to add.
  1335.      * @return A new array containing the existing elements plus the new element The returned array type will be that of
  1336.      *         the input array (unless null), in which case it will have the same type as the element.
  1337.      * @since 3.10
  1338.      */
  1339.     public static short[] addFirst(final short[] array, final short element) {
  1340.         return array == null ? add(array, element) : insert(0, array, element);
  1341.     }

  1343.     /**
  1344.      * Copies the given array and adds the given element at the beginning of the new array.
  1345.      * <p>
  1346.      * The new array contains the same elements of the input array plus the given element in the first position. The
  1347.      * component type of the new array is the same as that of the input array.
  1348.      * </p>
  1349.      * <p>
  1350.      * If the input array is {@code null}, a new one element array is returned whose component type is the same as the
  1351.      * element, unless the element itself is null, in which case the return type is Object[]
  1352.      * </p>
  1353.      * <pre>
  1354.      * ArrayUtils.addFirst(null, null)      = IllegalArgumentException
  1355.      * ArrayUtils.addFirst(null, "a")       = ["a"]
  1356.      * ArrayUtils.addFirst(["a"], null)     = [null, "a"]
  1357.      * ArrayUtils.addFirst(["a"], "b")      = ["b", "a"]
  1358.      * ArrayUtils.addFirst(["a", "b"], "c") = ["c", "a", "b"]
  1359.      * </pre>
  1360.      *
  1361.      * @param <T> the component type of the array
  1362.      * @param array the array to "add" the element to, may be {@code null}
  1363.      * @param element the object to add, may be {@code null}
  1364.      * @return A new array containing the existing elements plus the new element The returned array type will be that of
  1365.      *         the input array (unless null), in which case it will have the same type as the element. If both are null,
  1366.      *         an IllegalArgumentException is thrown
  1367.      * @since 3.10
  1368.      * @throws IllegalArgumentException if both arguments are null
  1369.      */
  1370.     public static <T> T[] addFirst(final T[] array, final T element) {
  1371.         return array == null ? add(array, element) : insert(0, array, element);
  1372.     }

  1374.     /**
  1375.      * A fluent version of {@link System#arraycopy(Object, int, Object, int, int)} that returns the destination array.
  1376.      *
  1377.      * @param <T>       the type.
  1378.      * @param source    the source array.
  1379.      * @param sourcePos starting position in the source array.
  1380.      * @param destPos   starting position in the destination data.
  1381.      * @param length    the number of array elements to be copied.
  1382.      * @param allocator allocates the array to populate and return.
  1383.      * @return dest
  1384.      * @throws IndexOutOfBoundsException if copying would cause access of data outside array bounds.
  1385.      * @throws ArrayStoreException       if an element in the {@code src} array could not be stored into the {@code dest} array because of a type
  1386.      *                                   mismatch.
  1387.      * @throws NullPointerException      if either {@code src} or {@code dest} is {@code null}.
  1388.      * @since 3.15.0
  1389.      */
  1390.     public static <T> T arraycopy(final T source, final int sourcePos, final int destPos, final int length, final Function<Integer, T> allocator) {
  1391.         return arraycopy(source, sourcePos, allocator.apply(length), destPos, length);
  1392.     }

  1394.     /**
  1395.      * A fluent version of {@link System#arraycopy(Object, int, Object, int, int)} that returns the destination array.
  1396.      *
  1397.      * @param <T>       the type.
  1398.      * @param source    the source array.
  1399.      * @param sourcePos starting position in the source array.
  1400.      * @param destPos   starting position in the destination data.
  1401.      * @param length    the number of array elements to be copied.
  1402.      * @param allocator allocates the array to populate and return.
  1403.      * @return dest
  1404.      * @throws IndexOutOfBoundsException if copying would cause access of data outside array bounds.
  1405.      * @throws ArrayStoreException       if an element in the {@code src} array could not be stored into the {@code dest} array because of a type
  1406.      *                                   mismatch.
  1407.      * @throws NullPointerException      if either {@code src} or {@code dest} is {@code null}.
  1408.      * @since 3.15.0
  1409.      */
  1410.     public static <T> T arraycopy(final T source, final int sourcePos, final int destPos, final int length, final Supplier<T> allocator) {
  1411.         return arraycopy(source, sourcePos, allocator.get(), destPos, length);
  1412.     }

  1414.     /**
  1415.      * A fluent version of {@link System#arraycopy(Object, int, Object, int, int)} that returns the destination array.
  1416.      *
  1417.      * @param <T>       the type
  1418.      * @param source    the source array.
  1419.      * @param sourcePos starting position in the source array.
  1420.      * @param dest      the destination array.
  1421.      * @param destPos   starting position in the destination data.
  1422.      * @param length    the number of array elements to be copied.
  1423.      * @return dest
  1424.      * @throws IndexOutOfBoundsException if copying would cause access of data outside array bounds.
  1425.      * @throws ArrayStoreException       if an element in the {@code src} array could not be stored into the {@code dest} array because of a type
  1426.      *                                   mismatch.
  1427.      * @throws NullPointerException      if either {@code src} or {@code dest} is {@code null}.
  1428.      * @since 3.15.0
  1429.      */
  1430.     public static <T> T arraycopy(final T source, final int sourcePos, final T dest, final int destPos, final int length) {
  1431.         System.arraycopy(source, sourcePos, dest, destPos, length);
  1432.         return dest;
  1433.     }

  1435.     /**
  1436.      * Clones an array or returns {@code null}.
  1437.      * <p>
  1438.      * This method returns {@code null} for a {@code null} input array.
  1439.      * </p>
  1440.      *
  1441.      * @param array the array to clone, may be {@code null}
  1442.      * @return the cloned array, {@code null} if {@code null} input
  1443.      */
  1444.     public static boolean[] clone(final boolean[] array) {
  1445.         return array != null ? array.clone() : null;
  1446.     }

  1448.     /**
  1449.      * Clones an array or returns {@code null}.
  1450.      * <p>
  1451.      * This method returns {@code null} for a {@code null} input array.
  1452.      * </p>
  1453.      *
  1454.      * @param array the array to clone, may be {@code null}
  1455.      * @return the cloned array, {@code null} if {@code null} input
  1456.      */
  1457.     public static byte[] clone(final byte[] array) {
  1458.         return array != null ? array.clone() : null;
  1459.     }

  1461.     /**
  1462.      * Clones an array or returns {@code null}.
  1463.      * <p>
  1464.      * This method returns {@code null} for a {@code null} input array.
  1465.      * </p>
  1466.      *
  1467.      * @param array the array to clone, may be {@code null}
  1468.      * @return the cloned array, {@code null} if {@code null} input
  1469.      */
  1470.     public static char[] clone(final char[] array) {
  1471.         return array != null ? array.clone() : null;
  1472.     }

  1474.     /**
  1475.      * Clones an array or returns {@code null}.
  1476.      * <p>
  1477.      * This method returns {@code null} for a {@code null} input array.
  1478.      * </p>
  1479.      *
  1480.      * @param array the array to clone, may be {@code null}
  1481.      * @return the cloned array, {@code null} if {@code null} input
  1482.      */
  1483.     public static double[] clone(final double[] array) {
  1484.         return array != null ? array.clone() : null;
  1485.     }

  1487.     /**
  1488.      * Clones an array or returns {@code null}.
  1489.      * <p>
  1490.      * This method returns {@code null} for a {@code null} input array.
  1491.      * </p>
  1492.      *
  1493.      * @param array the array to clone, may be {@code null}
  1494.      * @return the cloned array, {@code null} if {@code null} input
  1495.      */
  1496.     public static float[] clone(final float[] array) {
  1497.         return array != null ? array.clone() : null;
  1498.     }

  1500.     /**
  1501.      * Clones an array or returns {@code null}.
  1502.      * <p>
  1503.      * This method returns {@code null} for a {@code null} input array.
  1504.      * </p>
  1505.      *
  1506.      * @param array the array to clone, may be {@code null}
  1507.      * @return the cloned array, {@code null} if {@code null} input
  1508.      */
  1509.     public static int[] clone(final int[] array) {
  1510.         return array != null ? array.clone() : null;
  1511.     }

  1513.     /**
  1514.      * Clones an array or returns {@code null}.
  1515.      * <p>
  1516.      * This method returns {@code null} for a {@code null} input array.
  1517.      * </p>
  1518.      *
  1519.      * @param array the array to clone, may be {@code null}
  1520.      * @return the cloned array, {@code null} if {@code null} input
  1521.      */
  1522.     public static long[] clone(final long[] array) {
  1523.         return array != null ? array.clone() : null;
  1524.     }

  1526.     /**
  1527.      * Clones an array or returns {@code null}.
  1528.      * <p>
  1529.      * This method returns {@code null} for a {@code null} input array.
  1530.      * </p>
  1531.      *
  1532.      * @param array the array to clone, may be {@code null}
  1533.      * @return the cloned array, {@code null} if {@code null} input
  1534.      */
  1535.     public static short[] clone(final short[] array) {
  1536.         return array != null ? array.clone() : null;
  1537.     }

  1539.     /**
  1540.      * Shallow clones an array or returns {@code null}.
  1541.      * <p>
  1542.      * The objects in the array are not cloned, thus there is no special handling for multi-dimensional arrays.
  1543.      * </p>
  1544.      * <p>
  1545.      * This method returns {@code null} for a {@code null} input array.
  1546.      * </p>
  1547.      *
  1548.      * @param <T>   the component type of the array
  1549.      * @param array the array to shallow clone, may be {@code null}
  1550.      * @return the cloned array, {@code null} if {@code null} input
  1551.      */
  1552.     public static <T> T[] clone(final T[] array) {
  1553.         return array != null ? array.clone() : null;
  1554.     }

  1556.     /**
  1557.      * Checks if the value is in the given array.
  1558.      * <p>
  1559.      * The method returns {@code false} if a {@code null} array is passed in.
  1560.      * </p>
  1561.      *
  1562.      * @param array  the array to search through
  1563.      * @param valueToFind  the value to find
  1564.      * @return {@code true} if the array contains the object
  1565.      */
  1566.     public static boolean contains(final boolean[] array, final boolean valueToFind) {
  1567.         return indexOf(array, valueToFind) != INDEX_NOT_FOUND;
  1568.     }

  1570.     /**
  1571.      * Checks if the value is in the given array.
  1572.      * <p>
  1573.      * The method returns {@code false} if a {@code null} array is passed in.
  1574.      * </p>
  1575.      *
  1576.      * @param array  the array to search through
  1577.      * @param valueToFind  the value to find
  1578.      * @return {@code true} if the array contains the object
  1579.      */
  1580.     public static boolean contains(final byte[] array, final byte valueToFind) {
  1581.         return indexOf(array, valueToFind) != INDEX_NOT_FOUND;
  1582.     }

  1584.     /**
  1585.      * Checks if the value is in the given array.
  1586.      * <p>
  1587.      * The method returns {@code false} if a {@code null} array is passed in.
  1588.      * </p>
  1589.      *
  1590.      * @param array  the array to search through
  1591.      * @param valueToFind  the value to find
  1592.      * @return {@code true} if the array contains the object
  1593.      * @since 2.1
  1594.      */
  1595.     public static boolean contains(final char[] array, final char valueToFind) {
  1596.         return indexOf(array, valueToFind) != INDEX_NOT_FOUND;
  1597.     }

  1599.     /**
  1600.      * Checks if the value is in the given array.
  1601.      * <p>
  1602.      * The method returns {@code false} if a {@code null} array is passed in.
  1603.      * </p>
  1604.      *
  1605.      * @param array  the array to search through
  1606.      * @param valueToFind  the value to find
  1607.      * @return {@code true} if the array contains the object
  1608.      */
  1609.     public static boolean contains(final double[] array, final double valueToFind) {
  1610.         return indexOf(array, valueToFind) != INDEX_NOT_FOUND;
  1611.     }

  1613.     /**
  1614.      * Checks if a value falling within the given tolerance is in the
  1615.      * given array.  If the array contains a value within the inclusive range
  1616.      * defined by (value - tolerance) to (value + tolerance).
  1617.      * <p>
  1618.      * The method returns {@code false} if a {@code null} array
  1619.      * is passed in.
  1620.      * </p>
  1621.      *
  1622.      * @param array  the array to search
  1623.      * @param valueToFind  the value to find
  1624.      * @param tolerance  the array contains the tolerance of the search
  1625.      * @return true if value falling within tolerance is in array
  1626.      */
  1627.     public static boolean contains(final double[] array, final double valueToFind, final double tolerance) {
  1628.         return indexOf(array, valueToFind, 0, tolerance) != INDEX_NOT_FOUND;
  1629.     }

  1631.     /**
  1632.      * Checks if the value is in the given array.
  1633.      * <p>
  1634.      * The method returns {@code false} if a {@code null} array is passed in.
  1635.      * </p>
  1636.      *
  1637.      * @param array  the array to search through
  1638.      * @param valueToFind  the value to find
  1639.      * @return {@code true} if the array contains the object
  1640.      */
  1641.     public static boolean contains(final float[] array, final float valueToFind) {
  1642.         return indexOf(array, valueToFind) != INDEX_NOT_FOUND;
  1643.     }

  1645.     /**
  1646.      * Checks if the value is in the given array.
  1647.      * <p>
  1648.      * The method returns {@code false} if a {@code null} array is passed in.
  1649.      * </p>
  1650.      *
  1651.      * @param array  the array to search through
  1652.      * @param valueToFind  the value to find
  1653.      * @return {@code true} if the array contains the object
  1654.      */
  1655.     public static boolean contains(final int[] array, final int valueToFind) {
  1656.         return indexOf(array, valueToFind) != INDEX_NOT_FOUND;
  1657.     }

  1659.     /**
  1660.      * Checks if the value is in the given array.
  1661.      * <p>
  1662.      * The method returns {@code false} if a {@code null} array is passed in.
  1663.      * </p>
  1664.      *
  1665.      * @param array  the array to search through
  1666.      * @param valueToFind  the value to find
  1667.      * @return {@code true} if the array contains the object
  1668.      */
  1669.     public static boolean contains(final long[] array, final long valueToFind) {
  1670.         return indexOf(array, valueToFind) != INDEX_NOT_FOUND;
  1671.     }

  1673.     /**
  1674.      * Checks if the object is in the given array.
  1675.      * <p>
  1676.      * The method returns {@code false} if a {@code null} array is passed in.
  1677.      * </p>
  1678.      *
  1679.      * @param array  the array to search through
  1680.      * @param objectToFind  the object to find
  1681.      * @return {@code true} if the array contains the object
  1682.      */
  1683.     public static boolean contains(final Object[] array, final Object objectToFind) {
  1684.         return indexOf(array, objectToFind) != INDEX_NOT_FOUND;
  1685.     }

  1687.     /**
  1688.      * Checks if the value is in the given array.
  1689.      * <p>
  1690.      * The method returns {@code false} if a {@code null} array is passed in.
  1691.      * </p>
  1692.      *
  1693.      * @param array  the array to search through
  1694.      * @param valueToFind  the value to find
  1695.      * @return {@code true} if the array contains the object
  1696.      */
  1697.     public static boolean contains(final short[] array, final short valueToFind) {
  1698.         return indexOf(array, valueToFind) != INDEX_NOT_FOUND;
  1699.     }

  1701.     /**
  1702.      * Checks if any of the objects are in the given array.
  1703.      * <p>
  1704.      * The method returns {@code false} if a {@code null} array is passed in.
  1705.      * </p>
  1706.      *
  1707.      * @param array  the array to search through
  1708.      * @param objectsToFind  any of the objects to find
  1709.      * @return {@code true} if the array contains any of the objects
  1710.      * @since 3.13.0
  1711.      */
  1712.     public static boolean containsAny(final Object[] array, final Object... objectsToFind) {
  1713.         return Streams.of(objectsToFind).anyMatch(e -> contains(array, e));
  1714.     }

  1716.     /**
  1717.      * Returns a copy of the given array of size 1 greater than the argument.
  1718.      * The last value of the array is left to the default value.
  1719.      *
  1720.      * @param array The array to copy, must not be {@code null}.
  1721.      * @param newArrayComponentType If {@code array} is {@code null}, create a
  1722.      * size 1 array of this type.
  1723.      * @return A new copy of the array of size 1 greater than the input.
  1724.      */
  1725.     private static Object copyArrayGrow1(final Object array, final Class<?> newArrayComponentType) {
  1726.         if (array != null) {
  1727.             final int arrayLength = Array.getLength(array);
  1728.             final Object newArray = Array.newInstance(array.getClass().getComponentType(), arrayLength + 1);
  1729.             System.arraycopy(array, 0, newArray, 0, arrayLength);
  1730.             return newArray;
  1731.         }
  1732.         return Array.newInstance(newArrayComponentType, 1);
  1733.     }

  1735.     /**
  1736.      * Gets the nTh element of an array or null if the index is out of bounds or the array is null.
  1737.      *
  1738.      * @param <T> The type of array elements.
  1739.      * @param array The array to index.
  1740.      * @param index The index
  1741.      * @return the nTh element of an array or null if the index is out of bounds or the array is null.
  1742.      * @since 3.11
  1743.      */
  1744.     public static <T> T get(final T[] array, final int index) {
  1745.         return get(array, index, null);
  1746.     }

  1748.     /**
  1749.      * Gets the nTh element of an array or a default value if the index is out of bounds.
  1750.      *
  1751.      * @param <T> The type of array elements.
  1752.      * @param array The array to index.
  1753.      * @param index The index
  1754.      * @param defaultValue The return value of the given index is out of bounds.
  1755.      * @return the nTh element of an array or a default value if the index is out of bounds.
  1756.      * @since 3.11
  1757.      */
  1758.     public static <T> T get(final T[] array, final int index, final T defaultValue) {
  1759.         return isArrayIndexValid(array, index) ? array[index] : defaultValue;
  1760.     }

  1762.     /**
  1763.      * Gets an array's component type.
  1764.      *
  1765.      * @param <T> The array type.
  1766.      * @param array The array.
  1767.      * @return The component type.
  1768.      * @since 3.13.0
  1769.      */
  1770.     public static <T> Class<T> getComponentType(final T[] array) {
  1771.         return ClassUtils.getComponentType(ObjectUtils.getClass(array));
  1772.     }

  1774.     /**
  1775.      * Returns the length of the specified array.
  1776.      * This method can deal with {@link Object} arrays and with primitive arrays.
  1777.      * <p>
  1778.      * If the input array is {@code null}, {@code 0} is returned.
  1779.      * </p>
  1780.      * <pre>
  1781.      * ArrayUtils.getLength(null)            = 0
  1782.      * ArrayUtils.getLength([])              = 0
  1783.      * ArrayUtils.getLength([null])          = 1
  1784.      * ArrayUtils.getLength([true, false])   = 2
  1785.      * ArrayUtils.getLength([1, 2, 3])       = 3
  1786.      * ArrayUtils.getLength(["a", "b", "c"]) = 3
  1787.      * </pre>
  1788.      *
  1789.      * @param array  the array to retrieve the length from, may be null
  1790.      * @return The length of the array, or {@code 0} if the array is {@code null}
  1791.      * @throws IllegalArgumentException if the object argument is not an array.
  1792.      * @since 2.1
  1793.      */
  1794.     public static int getLength(final Object array) {
  1795.         return array != null ? Array.getLength(array) : 0;
  1796.     }

  1798.     /**
  1799.      * Gets a hash code for an array handling multidimensional arrays correctly.
  1800.      * <p>
  1801.      * Multi-dimensional primitive arrays are also handled correctly by this method.
  1802.      * </p>
  1803.      *
  1804.      * @param array  the array to get a hash code for, {@code null} returns zero
  1805.      * @return a hash code for the array
  1806.      */
  1807.     public static int hashCode(final Object array) {
  1808.         return new HashCodeBuilder().append(array).toHashCode();
  1809.     }

  1811.     /**
  1812.      * Finds the indices of the given value in the array.
  1813.      * <p>
  1814.      * This method returns an empty BitSet for a {@code null} input array.
  1815.      * </p>
  1816.      *
  1817.      * @param array  the array to search through for the object, may be {@code null}
  1818.      * @param valueToFind  the value to find
  1819.      * @return a BitSet of all the indices of the value within the array,
  1820.      *  an empty BitSet if not found or {@code null} array input
  1821.      * @since 3.10
  1822.      */
  1823.     public static BitSet indexesOf(final boolean[] array, final boolean valueToFind) {
  1824.         return indexesOf(array, valueToFind, 0);
  1825.     }

  1827.     /**
  1828.      * Finds the indices of the given value in the array starting at the given index.
  1829.      * <p>
  1830.      * This method returns an empty BitSet for a {@code null} input array.
  1831.      * </p>
  1832.      * <p>
  1833.      * A negative startIndex is treated as zero. A startIndex larger than the array
  1834.      * length will return an empty BitSet ({@code -1}).
  1835.      * </p>
  1836.      *
  1837.      * @param array  the array to search through for the object, may be {@code null}
  1838.      * @param valueToFind  the value to find
  1839.      * @param startIndex  the index to start searching at
  1840.      * @return a BitSet of all the indices of the value within the array,
  1841.      *  an empty BitSet if not found or {@code null}
  1842.      *  array input
  1843.      * @since 3.10
  1844.      */
  1845.     public static BitSet indexesOf(final boolean[] array, final boolean valueToFind, int startIndex) {
  1846.         final BitSet bitSet = new BitSet();
  1847.         if (array == null) {
  1848.             return bitSet;
  1849.         }
  1850.         while (startIndex < array.length) {
  1851.             startIndex = indexOf(array, valueToFind, startIndex);
  1852.             if (startIndex == INDEX_NOT_FOUND) {
  1853.                 break;
  1854.             }
  1855.             bitSet.set(startIndex);
  1856.             ++startIndex;
  1857.         }
  1858.         return bitSet;
  1859.     }

  1861.     /**
  1862.      * Finds the indices of the given value in the array.
  1863.      *
  1864.      * <p>This method returns an empty BitSet for a {@code null} input array.</p>
  1865.      *
  1866.      * @param array  the array to search through for the object, may be {@code null}
  1867.      * @param valueToFind  the value to find
  1868.      * @return a BitSet of all the indices of the value within the array,
  1869.      *  an empty BitSet if not found or {@code null} array input
  1870.      * @since 3.10
  1871.      */
  1872.     public static BitSet indexesOf(final byte[] array, final byte valueToFind) {
  1873.         return indexesOf(array, valueToFind, 0);
  1874.     }

  1876.     /**
  1877.      * Finds the indices of the given value in the array starting at the given index.
  1878.      *
  1879.      * <p>This method returns an empty BitSet for a {@code null} input array.</p>
  1880.      *
  1881.      * <p>A negative startIndex is treated as zero. A startIndex larger than the array
  1882.      * length will return an empty BitSet.</p>
  1883.      *
  1884.      * @param array  the array to search through for the object, may be {@code null}
  1885.      * @param valueToFind  the value to find
  1886.      * @param startIndex  the index to start searching at
  1887.      * @return a BitSet of all the indices of the value within the array,
  1888.      *  an empty BitSet if not found or {@code null} array input
  1889.      * @since 3.10
  1890.      */
  1891.     public static BitSet indexesOf(final byte[] array, final byte valueToFind, int startIndex) {
  1892.         final BitSet bitSet = new BitSet();
  1893.         if (array == null) {
  1894.             return bitSet;
  1895.         }
  1896.         while (startIndex < array.length) {
  1897.             startIndex = indexOf(array, valueToFind, startIndex);
  1898.             if (startIndex == INDEX_NOT_FOUND) {
  1899.                 break;
  1900.             }
  1901.             bitSet.set(startIndex);
  1902.             ++startIndex;
  1903.         }

  1905.         return bitSet;
  1906.     }

  1908.     /**
  1909.      * Finds the indices of the given value in the array.
  1910.      *
  1911.      * <p>This method returns an empty BitSet for a {@code null} input array.</p>
  1912.      *
  1913.      * @param array  the array to search through for the object, may be {@code null}
  1914.      * @param valueToFind  the value to find
  1915.      * @return a BitSet of all the indices of the value within the array,
  1916.      *  an empty BitSet if not found or {@code null} array input
  1917.      * @since 3.10
  1918.      */
  1919.     public static BitSet indexesOf(final char[] array, final char valueToFind) {
  1920.         return indexesOf(array, valueToFind, 0);
  1921.     }

  1923.     /**
  1924.      * Finds the indices of the given value in the array starting at the given index.
  1925.      *
  1926.      * <p>This method returns an empty BitSet for a {@code null} input array.</p>
  1927.      *
  1928.      * <p>A negative startIndex is treated as zero. A startIndex larger than the array
  1929.      * length will return an empty BitSet.</p>
  1930.      *
  1931.      * @param array  the array to search through for the object, may be {@code null}
  1932.      * @param valueToFind  the value to find
  1933.      * @param startIndex  the index to start searching at
  1934.      * @return a BitSet of all the indices of the value within the array,
  1935.      *  an empty BitSet if not found or {@code null} array input
  1936.      * @since 3.10
  1937.      */
  1938.     public static BitSet indexesOf(final char[] array, final char valueToFind, int startIndex) {
  1939.         final BitSet bitSet = new BitSet();
  1940.         if (array == null) {
  1941.             return bitSet;
  1942.         }
  1943.         while (startIndex < array.length) {
  1944.             startIndex = indexOf(array, valueToFind, startIndex);
  1945.             if (startIndex == INDEX_NOT_FOUND) {
  1946.                 break;
  1947.             }
  1948.             bitSet.set(startIndex);
  1949.             ++startIndex;
  1950.         }
  1951.         return bitSet;
  1952.     }

  1954.     /**
  1955.      * Finds the indices of the given value in the array.
  1956.      *
  1957.      * <p>This method returns empty BitSet for a {@code null} input array.</p>
  1958.      *
  1959.      * @param array  the array to search through for the object, may be {@code null}
  1960.      * @param valueToFind  the value to find
  1961.      * @return a BitSet of all the indices of the value within the array,
  1962.      *  an empty BitSet if not found or {@code null} array input
  1963.      * @since 3.10
  1964.      */
  1965.     public static BitSet indexesOf(final double[] array, final double valueToFind) {
  1966.         return indexesOf(array, valueToFind, 0);
  1967.     }

  1969.     /**
  1970.      * Finds the indices of the given value within a given tolerance in the array.
  1971.      *
  1972.      * <p>
  1973.      * This method will return all the indices of the value which fall between the region
  1974.      * defined by valueToFind - tolerance and valueToFind + tolerance, each time between the nearest integers.
  1975.      * </p>
  1976.      *
  1977.      * <p>This method returns an empty BitSet for a {@code null} input array.</p>
  1978.      *
  1979.      * @param array  the array to search through for the object, may be {@code null}
  1980.      * @param valueToFind  the value to find
  1981.      * @param tolerance tolerance of the search
  1982.      * @return a BitSet of all the indices of the value within the array,
  1983.      *  an empty BitSet if not found or {@code null} array input
  1984.      * @since 3.10
  1985.      */
  1986.     public static BitSet indexesOf(final double[] array, final double valueToFind, final double tolerance) {
  1987.         return indexesOf(array, valueToFind, 0, tolerance);
  1988.     }

  1990.     /**
  1991.      * Finds the indices of the given value in the array starting at the given index.
  1992.      *
  1993.      * <p>This method returns an empty BitSet for a {@code null} input array.</p>
  1994.      *
  1995.      * <p>A negative startIndex is treated as zero. A startIndex larger than the array
  1996.      * length will return an empty BitSet.</p>
  1997.      *
  1998.      * @param array  the array to search through for the object, may be {@code null}
  1999.      * @param valueToFind  the value to find
  2000.      * @param startIndex  the index to start searching at
  2001.      * @return a BitSet of the indices of the value within the array,
  2002.      *  an empty BitSet if not found or {@code null} array input
  2003.      * @since 3.10
  2004.      */
  2005.     public static BitSet indexesOf(final double[] array, final double valueToFind, int startIndex) {
  2006.         final BitSet bitSet = new BitSet();
  2007.         if (array == null) {
  2008.             return bitSet;
  2009.         }
  2010.         while (startIndex < array.length) {
  2011.             startIndex = indexOf(array, valueToFind, startIndex);
  2012.             if (startIndex == INDEX_NOT_FOUND) {
  2013.                 break;
  2014.             }
  2015.             bitSet.set(startIndex);
  2016.             ++startIndex;
  2017.         }
  2018.         return bitSet;
  2019.     }

  2021.     /**
  2022.      * Finds the indices of the given value in the array starting at the given index.
  2023.      *
  2024.      * <p>
  2025.      * This method will return the indices of the values which fall between the region
  2026.      * defined by valueToFind - tolerance and valueToFind + tolerance, between the nearest integers.
  2027.      * </p>
  2028.      *
  2029.      * <p>This method returns an empty BitSet for a {@code null} input array.</p>
  2030.      *
  2031.      * <p>A negative startIndex is treated as zero. A startIndex larger than the array
  2032.      * length will return an empty BitSet.</p>
  2033.      *
  2034.      * @param array  the array to search through for the object, may be {@code null}
  2035.      * @param valueToFind  the value to find
  2036.      * @param startIndex  the index to start searching at
  2037.      * @param tolerance tolerance of the search
  2038.      * @return a BitSet of the indices of the value within the array,
  2039.      *  an empty BitSet if not found or {@code null} array input
  2040.      * @since 3.10
  2041.      */
  2042.     public static BitSet indexesOf(final double[] array, final double valueToFind, int startIndex, final double tolerance) {
  2043.         final BitSet bitSet = new BitSet();
  2044.         if (array == null) {
  2045.             return bitSet;
  2046.         }
  2047.         while (startIndex < array.length) {
  2048.             startIndex = indexOf(array, valueToFind, startIndex, tolerance);
  2049.             if (startIndex == INDEX_NOT_FOUND) {
  2050.                 break;
  2051.             }
  2052.             bitSet.set(startIndex);
  2053.             ++startIndex;
  2054.         }
  2055.         return bitSet;
  2056.     }

  2058.     /**
  2059.      * Finds the indices of the given value in the array.
  2060.      *
  2061.      * <p>This method returns an empty BitSet for a {@code null} input array.</p>
  2062.      *
  2063.      * @param array  the array to search through for the object, may be {@code null}
  2064.      * @param valueToFind  the value to find
  2065.      * @return a BitSet of all the indices of the value within the array,
  2066.      *  an empty BitSet if not found or {@code null} array input
  2067.      * @since 3.10
  2068.      */
  2069.     public static BitSet indexesOf(final float[] array, final float valueToFind) {
  2070.         return indexesOf(array, valueToFind, 0);
  2071.     }

  2073.     /**
  2074.      * Finds the indices of the given value in the array starting at the given index.
  2075.      *
  2076.      * <p>This method returns an empty BitSet for a {@code null} input array.</p>
  2077.      *
  2078.      * <p>A negative startIndex is treated as zero. A startIndex larger than the array
  2079.      * length will return empty BitSet.</p>
  2080.      *
  2081.      * @param array  the array to search through for the object, may be {@code null}
  2082.      * @param valueToFind  the value to find
  2083.      * @param startIndex  the index to start searching at
  2084.      * @return a BitSet of all the indices of the value within the array,
  2085.      *  an empty BitSet if not found or {@code null} array input
  2086.      * @since 3.10
  2087.      */
  2088.     public static BitSet indexesOf(final float[] array, final float valueToFind, int startIndex) {
  2089.         final BitSet bitSet = new BitSet();
  2090.         if (array == null) {
  2091.             return bitSet;
  2092.         }
  2093.         while (startIndex < array.length) {
  2094.             startIndex = indexOf(array, valueToFind, startIndex);
  2095.             if (startIndex == INDEX_NOT_FOUND) {
  2096.                 break;
  2097.             }
  2098.             bitSet.set(startIndex);
  2099.             ++startIndex;
  2100.         }
  2101.         return bitSet;
  2102.     }

  2104.     /**
  2105.      * Finds the indices of the given value in the array.
  2106.      *
  2107.      * <p>This method returns an empty BitSet for a {@code null} input array.</p>
  2108.      *
  2109.      * @param array  the array to search through for the object, may be {@code null}
  2110.      * @param valueToFind  the value to find
  2111.      * @return a BitSet of all the indices of the value within the array,
  2112.      *  an empty BitSet if not found or {@code null} array input
  2113.      * @since 3.10
  2114.      */
  2115.     public static BitSet indexesOf(final int[] array, final int valueToFind) {
  2116.         return indexesOf(array, valueToFind, 0);
  2117.     }

  2119.     /**
  2120.      * Finds the indices of the given value in the array starting at the given index.
  2121.      *
  2122.      * <p>This method returns an empty BitSet for a {@code null} input array.</p>
  2123.      *
  2124.      * <p>A negative startIndex is treated as zero. A startIndex larger than the array
  2125.      * length will return an empty BitSet.</p>
  2126.      *
  2127.      * @param array  the array to search through for the object, may be {@code null}
  2128.      * @param valueToFind  the value to find
  2129.      * @param startIndex  the index to start searching at
  2130.      * @return a BitSet of all the indices of the value within the array,
  2131.      *  an empty BitSet if not found or {@code null} array input
  2132.      * @since 3.10
  2133.      */
  2134.     public static BitSet indexesOf(final int[] array, final int valueToFind, int startIndex) {
  2135.         final BitSet bitSet = new BitSet();
  2136.         if (array == null) {
  2137.             return bitSet;
  2138.         }
  2139.         while (startIndex < array.length) {
  2140.             startIndex = indexOf(array, valueToFind, startIndex);

  2142.             if (startIndex == INDEX_NOT_FOUND) {
  2143.                 break;
  2144.             }
  2145.             bitSet.set(startIndex);
  2146.             ++startIndex;
  2147.         }
  2148.         return bitSet;
  2149.     }

  2151.     /**
  2152.      * Finds the indices of the given value in the array.
  2153.      *
  2154.      * <p>This method returns an empty BitSet for a {@code null} input array.</p>
  2155.      *
  2156.      * @param array  the array to search through for the object, may be {@code null}
  2157.      * @param valueToFind  the value to find
  2158.      * @return a BitSet of all the indices of the value within the array,
  2159.      *  an empty BitSet if not found or {@code null} array input
  2160.      * @since 3.10
  2161.      */
  2162.     public static BitSet indexesOf(final long[] array, final long valueToFind) {
  2163.         return indexesOf(array, valueToFind, 0);
  2164.     }

  2166.     /**
  2167.      * Finds the indices of the given value in the array starting at the given index.
  2168.      *
  2169.      * <p>This method returns an empty BitSet for a {@code null} input array.</p>
  2170.      *
  2171.      * <p>A negative startIndex is treated as zero. A startIndex larger than the array
  2172.      * length will return an empty BitSet.</p>
  2173.      *
  2174.      * @param array  the array to search through for the object, may be {@code null}
  2175.      * @param valueToFind  the value to find
  2176.      * @param startIndex  the index to start searching at
  2177.      * @return a BitSet of all the indices of the value within the array,
  2178.      *  an empty BitSet if not found or {@code null} array input
  2179.      * @since 3.10
  2180.      */
  2181.     public static BitSet indexesOf(final long[] array, final long valueToFind, int startIndex) {
  2182.         final BitSet bitSet = new BitSet();
  2183.         if (array == null) {
  2184.             return bitSet;
  2185.         }
  2186.         while (startIndex < array.length) {
  2187.             startIndex = indexOf(array, valueToFind, startIndex);
  2188.             if (startIndex == INDEX_NOT_FOUND) {
  2189.                 break;
  2190.             }
  2191.             bitSet.set(startIndex);
  2192.             ++startIndex;
  2193.         }
  2194.         return bitSet;
  2195.     }

  2197.     /**
  2198.      * Finds the indices of the given object in the array.
  2199.      *
  2200.      * <p>This method returns an empty BitSet for a {@code null} input array.</p>
  2201.      *
  2202.      * @param array  the array to search through for the object, may be {@code null}
  2203.      * @param objectToFind  the object to find, may be {@code null}
  2204.      * @return a BitSet of all the indices of the object within the array,
  2205.      *  an empty BitSet if not found or {@code null} array input
  2206.      * @since 3.10
  2207.      */
  2208.     public static BitSet indexesOf(final Object[] array, final Object objectToFind) {
  2209.         return indexesOf(array, objectToFind, 0);
  2210.     }

  2212.     /**
  2213.      * Finds the indices of the given object in the array starting at the given index.
  2214.      *
  2215.      * <p>This method returns an empty BitSet for a {@code null} input array.</p>
  2216.      *
  2217.      * <p>A negative startIndex is treated as zero. A startIndex larger than the array
  2218.      * length will return an empty BitSet.</p>
  2219.      *
  2220.      * @param array  the array to search through for the object, may be {@code null}
  2221.      * @param objectToFind  the object to find, may be {@code null}
  2222.      * @param startIndex  the index to start searching at
  2223.      * @return a BitSet of all the indices of the object within the array starting at the index,
  2224.      *  an empty BitSet if not found or {@code null} array input
  2225.      * @since 3.10
  2226.      */
  2227.     public static BitSet indexesOf(final Object[] array, final Object objectToFind, int startIndex) {
  2228.         final BitSet bitSet = new BitSet();
  2229.         if (array == null) {
  2230.             return bitSet;
  2231.         }
  2232.         while (startIndex < array.length) {
  2233.             startIndex = indexOf(array, objectToFind, startIndex);
  2234.             if (startIndex == INDEX_NOT_FOUND) {
  2235.                 break;
  2236.             }
  2237.             bitSet.set(startIndex);
  2238.             ++startIndex;
  2239.         }
  2240.         return bitSet;
  2241.     }

  2243.     /**
  2244.      * Finds the indices of the given value in the array.
  2245.      *
  2246.      * <p>This method returns an empty BitSet for a {@code null} input array.</p>
  2247.      *
  2248.      * @param array  the array to search through for the object, may be {@code null}
  2249.      * @param valueToFind  the value to find
  2250.      * @return a BitSet of all the indices of the value within the array,
  2251.      *  an empty BitSet if not found or {@code null} array input
  2252.      * @since 3.10
  2253.      */
  2254.     public static BitSet indexesOf(final short[] array, final short valueToFind) {
  2255.         return indexesOf(array, valueToFind, 0);
  2256.     }

  2258.     /**
  2259.      * Finds the indices of the given value in the array starting at the given index.
  2260.      *
  2261.      * <p>This method returns an empty BitSet for a {@code null} input array.</p>
  2262.      *
  2263.      * <p>A negative startIndex is treated as zero. A startIndex larger than the array
  2264.      * length will return an empty BitSet.</p>
  2265.      *
  2266.      * @param array  the array to search through for the object, may be {@code null}
  2267.      * @param valueToFind  the value to find
  2268.      * @param startIndex  the index to start searching at
  2269.      * @return a BitSet of all the indices of the value within the array,
  2270.      *  an empty BitSet if not found or {@code null} array input
  2271.      * @since 3.10
  2272.      */
  2273.     public static BitSet indexesOf(final short[] array, final short valueToFind, int startIndex) {
  2274.         final BitSet bitSet = new BitSet();
  2275.         if (array == null) {
  2276.             return bitSet;
  2277.         }
  2278.         while (startIndex < array.length) {
  2279.             startIndex = indexOf(array, valueToFind, startIndex);
  2280.             if (startIndex == INDEX_NOT_FOUND) {
  2281.                 break;
  2282.             }
  2283.             bitSet.set(startIndex);
  2284.             ++startIndex;
  2285.         }
  2286.         return bitSet;
  2287.     }

  2289.     /**
  2290.      * Finds the index of the given value in the array.
  2291.      * <p>
  2292.      * This method returns {@link #INDEX_NOT_FOUND} ({@code -1}) for a {@code null} input array.
  2293.      * </p>
  2294.      *
  2295.      * @param array  the array to search through for the object, may be {@code null}
  2296.      * @param valueToFind  the value to find
  2297.      * @return the index of the value within the array,
  2298.      *  {@link #INDEX_NOT_FOUND} ({@code -1}) if not found or {@code null} array input
  2299.      */
  2300.     public static int indexOf(final boolean[] array, final boolean valueToFind) {
  2301.         return indexOf(array, valueToFind, 0);
  2302.     }

  2304.     /**
  2305.      * Finds the index of the given value in the array starting at the given index.
  2306.      * <p>
  2307.      * This method returns {@link #INDEX_NOT_FOUND} ({@code -1}) for a {@code null} input array.
  2308.      * </p>
  2309.      * <p>
  2310.      * A negative startIndex is treated as zero. A startIndex larger than the array
  2311.      * length will return {@link #INDEX_NOT_FOUND} ({@code -1}).
  2312.      * </p>
  2313.      *
  2314.      * @param array  the array to search through for the object, may be {@code null}
  2315.      * @param valueToFind  the value to find
  2316.      * @param startIndex  the index to start searching at
  2317.      * @return the index of the value within the array,
  2318.      *  {@link #INDEX_NOT_FOUND} ({@code -1}) if not found or {@code null}
  2319.      *  array input
  2320.      */
  2321.     public static int indexOf(final boolean[] array, final boolean valueToFind, final int startIndex) {
  2322.         if (isEmpty(array)) {
  2323.             return INDEX_NOT_FOUND;
  2324.         }
  2325.         for (int i = max0(startIndex); i < array.length; i++) {
  2326.             if (valueToFind == array[i]) {
  2327.                 return i;
  2328.             }
  2329.         }
  2330.         return INDEX_NOT_FOUND;
  2331.     }

  2333.     /**
  2334.      * Finds the index of the given value in the array.
  2335.      * <p>
  2336.      * This method returns {@link #INDEX_NOT_FOUND} ({@code -1}) for a {@code null} input array.
  2337.      * </p>
  2338.      *
  2339.      * @param array  the array to search through for the object, may be {@code null}
  2340.      * @param valueToFind  the value to find
  2341.      * @return the index of the value within the array,
  2342.      *  {@link #INDEX_NOT_FOUND} ({@code -1}) if not found or {@code null} array input
  2343.      */
  2344.     public static int indexOf(final byte[] array, final byte valueToFind) {
  2345.         return indexOf(array, valueToFind, 0);
  2346.     }

  2348.     /**
  2349.      * Finds the index of the given value in the array starting at the given index.
  2350.      * <p>
  2351.      * This method returns {@link #INDEX_NOT_FOUND} ({@code -1}) for a {@code null} input array.
  2352.      * </p>
  2353.      * <p>
  2354.      * A negative startIndex is treated as zero. A startIndex larger than the array
  2355.      * length will return {@link #INDEX_NOT_FOUND} ({@code -1}).
  2356.      * </p>
  2357.      *
  2358.      * @param array  the array to search through for the object, may be {@code null}
  2359.      * @param valueToFind  the value to find
  2360.      * @param startIndex  the index to start searching at
  2361.      * @return the index of the value within the array,
  2362.      *  {@link #INDEX_NOT_FOUND} ({@code -1}) if not found or {@code null} array input
  2363.      */
  2364.     public static int indexOf(final byte[] array, final byte valueToFind, final int startIndex) {
  2365.         if (array == null) {
  2366.             return INDEX_NOT_FOUND;
  2367.         }
  2368.         for (int i = max0(startIndex); i < array.length; i++) {
  2369.             if (valueToFind == array[i]) {
  2370.                 return i;
  2371.             }
  2372.         }
  2373.         return INDEX_NOT_FOUND;
  2374.     }

  2376.     /**
  2377.      * Finds the index of the given value in the array.
  2378.      * <p>
  2379.      * This method returns {@link #INDEX_NOT_FOUND} ({@code -1}) for a {@code null} input array.
  2380.      * </p>
  2381.      *
  2382.      * @param array  the array to search through for the object, may be {@code null}
  2383.      * @param valueToFind  the value to find
  2384.      * @return the index of the value within the array,
  2385.      *  {@link #INDEX_NOT_FOUND} ({@code -1}) if not found or {@code null} array input
  2386.      * @since 2.1
  2387.      */
  2388.     public static int indexOf(final char[] array, final char valueToFind) {
  2389.         return indexOf(array, valueToFind, 0);
  2390.     }

  2392.     /**
  2393.      * Finds the index of the given value in the array starting at the given index.
  2394.      * <p>
  2395.      * This method returns {@link #INDEX_NOT_FOUND} ({@code -1}) for a {@code null} input array.
  2396.      * </p>
  2397.      * <p>
  2398.      * A negative startIndex is treated as zero. A startIndex larger than the array
  2399.      * length will return {@link #INDEX_NOT_FOUND} ({@code -1}).
  2400.      * </p>
  2401.      *
  2402.      * @param array  the array to search through for the object, may be {@code null}
  2403.      * @param valueToFind  the value to find
  2404.      * @param startIndex  the index to start searching at
  2405.      * @return the index of the value within the array,
  2406.      *  {@link #INDEX_NOT_FOUND} ({@code -1}) if not found or {@code null} array input
  2407.      * @since 2.1
  2408.      */
  2409.     public static int indexOf(final char[] array, final char valueToFind, final int startIndex) {
  2410.         if (array == null) {
  2411.             return INDEX_NOT_FOUND;
  2412.         }
  2413.         for (int i = max0(startIndex); i < array.length; i++) {
  2414.             if (valueToFind == array[i]) {
  2415.                 return i;
  2416.             }
  2417.         }
  2418.         return INDEX_NOT_FOUND;
  2419.     }

  2421.     /**
  2422.      * Finds the index of the given value in the array.
  2423.      * <p>
  2424.      * This method returns {@link #INDEX_NOT_FOUND} ({@code -1}) for a {@code null} input array.
  2425.      * </p>
  2426.      *
  2427.      * @param array  the array to search through for the object, may be {@code null}
  2428.      * @param valueToFind  the value to find
  2429.      * @return the index of the value within the array,
  2430.      *  {@link #INDEX_NOT_FOUND} ({@code -1}) if not found or {@code null} array input
  2431.      */
  2432.     public static int indexOf(final double[] array, final double valueToFind) {
  2433.         return indexOf(array, valueToFind, 0);
  2434.     }

  2436.     /**
  2437.      * Finds the index of the given value within a given tolerance in the array.
  2438.      * This method will return the index of the first value which falls between the region
  2439.      * defined by valueToFind - tolerance and valueToFind + tolerance.
  2440.      * <p>
  2441.      * This method returns {@link #INDEX_NOT_FOUND} ({@code -1}) for a {@code null} input array.
  2442.      * </p>
  2443.      *
  2444.      * @param array  the array to search through for the object, may be {@code null}
  2445.      * @param valueToFind  the value to find
  2446.      * @param tolerance tolerance of the search
  2447.      * @return the index of the value within the array,
  2448.      *  {@link #INDEX_NOT_FOUND} ({@code -1}) if not found or {@code null} array input
  2449.      */
  2450.     public static int indexOf(final double[] array, final double valueToFind, final double tolerance) {
  2451.         return indexOf(array, valueToFind, 0, tolerance);
  2452.     }

  2454.     /**
  2455.      * Finds the index of the given value in the array starting at the given index.
  2456.      * <p>
  2457.      * This method returns {@link #INDEX_NOT_FOUND} ({@code -1}) for a {@code null} input array.
  2458.      * </p>
  2459.      * <p>
  2460.      * A negative startIndex is treated as zero. A startIndex larger than the array
  2461.      * length will return {@link #INDEX_NOT_FOUND} ({@code -1}).
  2462.      * </p>
  2463.      *
  2464.      * @param array  the array to search through for the object, may be {@code null}
  2465.      * @param valueToFind  the value to find
  2466.      * @param startIndex  the index to start searching at
  2467.      * @return the index of the value within the array,
  2468.      *  {@link #INDEX_NOT_FOUND} ({@code -1}) if not found or {@code null} array input
  2469.      */
  2470.     public static int indexOf(final double[] array, final double valueToFind, final int startIndex) {
  2471.         if (isEmpty(array)) {
  2472.             return INDEX_NOT_FOUND;
  2473.         }
  2474.         final boolean searchNaN = Double.isNaN(valueToFind);
  2475.         for (int i = max0(startIndex); i < array.length; i++) {
  2476.             final double element = array[i];
  2477.             if (valueToFind == element || searchNaN && Double.isNaN(element)) {
  2478.                 return i;
  2479.             }
  2480.         }
  2481.         return INDEX_NOT_FOUND;
  2482.     }

  2484.     /**
  2485.      * Finds the index of the given value in the array starting at the given index.
  2486.      * This method will return the index of the first value which falls between the region
  2487.      * defined by valueToFind - tolerance and valueToFind + tolerance.
  2488.      * <p>
  2489.      * This method returns {@link #INDEX_NOT_FOUND} ({@code -1}) for a {@code null} input array.
  2490.      * </p>
  2491.      * <p>
  2492.      * A negative startIndex is treated as zero. A startIndex larger than the array
  2493.      * length will return {@link #INDEX_NOT_FOUND} ({@code -1}).
  2494.      * </p>
  2495.      *
  2496.      * @param array  the array to search through for the object, may be {@code null}
  2497.      * @param valueToFind  the value to find
  2498.      * @param startIndex  the index to start searching at
  2499.      * @param tolerance tolerance of the search
  2500.      * @return the index of the value within the array,
  2501.      *  {@link #INDEX_NOT_FOUND} ({@code -1}) if not found or {@code null} array input
  2502.      */
  2503.     public static int indexOf(final double[] array, final double valueToFind, final int startIndex, final double tolerance) {
  2504.         if (isEmpty(array)) {
  2505.             return INDEX_NOT_FOUND;
  2506.         }
  2507.         final double min = valueToFind - tolerance;
  2508.         final double max = valueToFind + tolerance;
  2509.         for (int i = max0(startIndex); i < array.length; i++) {
  2510.             if (array[i] >= min && array[i] <= max) {
  2511.                 return i;
  2512.             }
  2513.         }
  2514.         return INDEX_NOT_FOUND;
  2515.     }

  2517.     /**
  2518.      * Finds the index of the given value in the array.
  2519.      * <p>
  2520.      * This method returns {@link #INDEX_NOT_FOUND} ({@code -1}) for a {@code null} input array.
  2521.      * </p>
  2522.      *
  2523.      * @param array  the array to search through for the object, may be {@code null}
  2524.      * @param valueToFind  the value to find
  2525.      * @return the index of the value within the array,
  2526.      *  {@link #INDEX_NOT_FOUND} ({@code -1}) if not found or {@code null} array input
  2527.      */
  2528.     public static int indexOf(final float[] array, final float valueToFind) {
  2529.         return indexOf(array, valueToFind, 0);
  2530.     }

  2532.     /**
  2533.      * Finds the index of the given value in the array starting at the given index.
  2534.      * <p>
  2535.      * This method returns {@link #INDEX_NOT_FOUND} ({@code -1}) for a {@code null} input array.
  2536.      * </p>
  2537.      * <p>
  2538.      * A negative startIndex is treated as zero. A startIndex larger than the array
  2539.      * length will return {@link #INDEX_NOT_FOUND} ({@code -1}).
  2540.      * </p>
  2541.      *
  2542.      * @param array  the array to search through for the object, may be {@code null}
  2543.      * @param valueToFind  the value to find
  2544.      * @param startIndex  the index to start searching at
  2545.      * @return the index of the value within the array,
  2546.      *  {@link #INDEX_NOT_FOUND} ({@code -1}) if not found or {@code null} array input
  2547.      */
  2548.     public static int indexOf(final float[] array, final float valueToFind, final int startIndex) {
  2549.         if (isEmpty(array)) {
  2550.             return INDEX_NOT_FOUND;
  2551.         }
  2552.         final boolean searchNaN = Float.isNaN(valueToFind);
  2553.         for (int i = max0(startIndex); i < array.length; i++) {
  2554.             final float element = array[i];
  2555.             if (valueToFind == element || searchNaN && Float.isNaN(element)) {
  2556.                 return i;
  2557.             }
  2558.         }
  2559.         return INDEX_NOT_FOUND;
  2560.     }

  2562.     /**
  2563.      * Finds the index of the given value in the array.
  2564.      * <p>
  2565.      * This method returns {@link #INDEX_NOT_FOUND} ({@code -1}) for a {@code null} input array.
  2566.      * </p>
  2567.      *
  2568.      * @param array  the array to search through for the object, may be {@code null}
  2569.      * @param valueToFind  the value to find
  2570.      * @return the index of the value within the array,
  2571.      *  {@link #INDEX_NOT_FOUND} ({@code -1}) if not found or {@code null} array input
  2572.      */
  2573.     public static int indexOf(final int[] array, final int valueToFind) {
  2574.         return indexOf(array, valueToFind, 0);
  2575.     }

  2577.     /**
  2578.      * Finds the index of the given value in the array starting at the given index.
  2579.      * <p>
  2580.      * This method returns {@link #INDEX_NOT_FOUND} ({@code -1}) for a {@code null} input array.
  2581.      * </p>
  2582.      * <p>
  2583.      * A negative startIndex is treated as zero. A startIndex larger than the array
  2584.      * length will return {@link #INDEX_NOT_FOUND} ({@code -1}).
  2585.      * </p>
  2586.      *
  2587.      * @param array  the array to search through for the object, may be {@code null}
  2588.      * @param valueToFind  the value to find
  2589.      * @param startIndex  the index to start searching at
  2590.      * @return the index of the value within the array,
  2591.      *  {@link #INDEX_NOT_FOUND} ({@code -1}) if not found or {@code null} array input
  2592.      */
  2593.     public static int indexOf(final int[] array, final int valueToFind, final int startIndex) {
  2594.         if (array == null) {
  2595.             return INDEX_NOT_FOUND;
  2596.         }
  2597.         for (int i = max0(startIndex); i < array.length; i++) {
  2598.             if (valueToFind == array[i]) {
  2599.                 return i;
  2600.             }
  2601.         }
  2602.         return INDEX_NOT_FOUND;
  2603.     }

  2605.     /**
  2606.      * Finds the index of the given value in the array.
  2607.      * <p>
  2608.      * This method returns {@link #INDEX_NOT_FOUND} ({@code -1}) for a {@code null} input array.
  2609.      * </p>
  2610.      *
  2611.      * @param array the array to search through for the object, may be {@code null}
  2612.      * @param valueToFind the value to find
  2613.      * @return the index of the value within the array, {@link #INDEX_NOT_FOUND} ({@code -1}) if not found or {@code null}
  2614.      *         array input
  2615.      */
  2616.     public static int indexOf(final long[] array, final long valueToFind) {
  2617.         return indexOf(array, valueToFind, 0);
  2618.     }

  2620.     /**
  2621.      * Finds the index of the given value in the array starting at the given index.
  2622.      * <p>
  2623.      * This method returns {@link #INDEX_NOT_FOUND} ({@code -1}) for a {@code null} input array.
  2624.      * </p>
  2625.      * <p>
  2626.      * A negative startIndex is treated as zero. A startIndex larger than the array
  2627.      * length will return {@link #INDEX_NOT_FOUND} ({@code -1}).
  2628.      * </p>
  2629.      *
  2630.      * @param array  the array to search through for the object, may be {@code null}
  2631.      * @param valueToFind  the value to find
  2632.      * @param startIndex  the index to start searching at
  2633.      * @return the index of the value within the array,
  2634.      *  {@link #INDEX_NOT_FOUND} ({@code -1}) if not found or {@code null} array input
  2635.      */
  2636.     public static int indexOf(final long[] array, final long valueToFind, final int startIndex) {
  2637.         if (array == null) {
  2638.             return INDEX_NOT_FOUND;
  2639.         }
  2640.         for (int i = max0(startIndex); i < array.length; i++) {
  2641.             if (valueToFind == array[i]) {
  2642.                 return i;
  2643.             }
  2644.         }
  2645.         return INDEX_NOT_FOUND;
  2646.     }

  2648.     /**
  2649.      * Finds the index of the given object in the array.
  2650.      * <p>
  2651.      * This method returns {@link #INDEX_NOT_FOUND} ({@code -1}) for a {@code null} input array.
  2652.      * </p>
  2653.      *
  2654.      * @param array  the array to search through for the object, may be {@code null}
  2655.      * @param objectToFind  the object to find, may be {@code null}
  2656.      * @return the index of the object within the array,
  2657.      *  {@link #INDEX_NOT_FOUND} ({@code -1}) if not found or {@code null} array input
  2658.      */
  2659.     public static int indexOf(final Object[] array, final Object objectToFind) {
  2660.         return indexOf(array, objectToFind, 0);
  2661.     }

  2663.     /**
  2664.      * Finds the index of the given object in the array starting at the given index.
  2665.      * <p>
  2666.      * This method returns {@link #INDEX_NOT_FOUND} ({@code -1}) for a {@code null} input array.
  2667.      * </p>
  2668.      * <p>
  2669.      * A negative startIndex is treated as zero. A startIndex larger than the array
  2670.      * length will return {@link #INDEX_NOT_FOUND} ({@code -1}).
  2671.      * </p>
  2672.      *
  2673.      * @param array  the array to search through for the object, may be {@code null}
  2674.      * @param objectToFind  the object to find, may be {@code null}
  2675.      * @param startIndex  the index to start searching at
  2676.      * @return the index of the object within the array starting at the index,
  2677.      *  {@link #INDEX_NOT_FOUND} ({@code -1}) if not found or {@code null} array input
  2678.      */
  2679.     public static int indexOf(final Object[] array, final Object objectToFind, int startIndex) {
  2680.         if (array == null) {
  2681.             return INDEX_NOT_FOUND;
  2682.         }
  2683.         startIndex = max0(startIndex);
  2684.         if (objectToFind == null) {
  2685.             for (int i = startIndex; i < array.length; i++) {
  2686.                 if (array[i] == null) {
  2687.                     return i;
  2688.                 }
  2689.             }
  2690.         } else {
  2691.             for (int i = startIndex; i < array.length; i++) {
  2692.                 if (objectToFind.equals(array[i])) {
  2693.                     return i;
  2694.                 }
  2695.             }
  2696.         }
  2697.         return INDEX_NOT_FOUND;
  2698.     }

  2700.     /**
  2701.      * Finds the index of the given value in the array.
  2702.      * <p>
  2703.      * This method returns {@link #INDEX_NOT_FOUND} ({@code -1}) for a {@code null} input array.
  2704.      * </p>
  2705.      *
  2706.      * @param array  the array to search through for the object, may be {@code null}
  2707.      * @param valueToFind  the value to find
  2708.      * @return the index of the value within the array,
  2709.      *  {@link #INDEX_NOT_FOUND} ({@code -1}) if not found or {@code null} array input
  2710.      */
  2711.     public static int indexOf(final short[] array, final short valueToFind) {
  2712.         return indexOf(array, valueToFind, 0);
  2713.     }

  2715.     /**
  2716.      * Finds the index of the given value in the array starting at the given index.
  2717.      * <p>
  2718.      * This method returns {@link #INDEX_NOT_FOUND} ({@code -1}) for a {@code null} input array.
  2719.      * </p>
  2720.      * <p>
  2721.      * A negative startIndex is treated as zero. A startIndex larger than the array
  2722.      * length will return {@link #INDEX_NOT_FOUND} ({@code -1}).
  2723.      * </p>
  2724.      *
  2725.      * @param array  the array to search through for the object, may be {@code null}
  2726.      * @param valueToFind  the value to find
  2727.      * @param startIndex  the index to start searching at
  2728.      * @return the index of the value within the array,
  2729.      *  {@link #INDEX_NOT_FOUND} ({@code -1}) if not found or {@code null} array input
  2730.      */
  2731.     public static int indexOf(final short[] array, final short valueToFind, final int startIndex) {
  2732.         if (array == null) {
  2733.             return INDEX_NOT_FOUND;
  2734.         }
  2735.         for (int i = max0(startIndex); i < array.length; i++) {
  2736.             if (valueToFind == array[i]) {
  2737.                 return i;
  2738.             }
  2739.         }
  2740.         return INDEX_NOT_FOUND;
  2741.     }

  2743.     /**
  2744.      * Inserts elements into an array at the given index (starting from zero).
  2745.      *
  2746.      * <p>When an array is returned, it is always a new array.</p>
  2747.      *
  2748.      * <pre>
  2749.      * ArrayUtils.insert(index, null, null)      = null
  2750.      * ArrayUtils.insert(index, array, null)     = cloned copy of 'array'
  2751.      * ArrayUtils.insert(index, null, values)    = null
  2752.      * </pre>
  2753.      *
  2754.      * @param index the position within {@code array} to insert the new values
  2755.      * @param array the array to insert the values into, may be {@code null}
  2756.      * @param values the new values to insert, may be {@code null}
  2757.      * @return The new array or {@code null} if the given array is {@code null}.
  2758.      * @throws IndexOutOfBoundsException if {@code array} is provided
  2759.      * and either {@code index < 0} or {@code index > array.length}
  2760.      * @since 3.6
  2761.      */
  2762.     public static boolean[] insert(final int index, final boolean[] array, final boolean... values) {
  2763.         if (array == null) {
  2764.             return null;
  2765.         }
  2766.         if (isEmpty(values)) {
  2767.             return clone(array);
  2768.         }
  2769.         if (index < 0 || index > array.length) {
  2770.             throw new IndexOutOfBoundsException("Index: " + index + ", Length: " + array.length);
  2771.         }
  2772.         final boolean[] result = new boolean[array.length + values.length];
  2773.         System.arraycopy(values, 0, result, index, values.length);
  2774.         if (index > 0) {
  2775.             System.arraycopy(array, 0, result, 0, index);
  2776.         }
  2777.         if (index < array.length) {
  2778.             System.arraycopy(array, index, result, index + values.length, array.length - index);
  2779.         }
  2780.         return result;
  2781.     }

  2783.     /**
  2784.      * Inserts elements into an array at the given index (starting from zero).
  2785.      *
  2786.      * <p>When an array is returned, it is always a new array.</p>
  2787.      *
  2788.      * <pre>
  2789.      * ArrayUtils.insert(index, null, null)      = null
  2790.      * ArrayUtils.insert(index, array, null)     = cloned copy of 'array'
  2791.      * ArrayUtils.insert(index, null, values)    = null
  2792.      * </pre>
  2793.      *
  2794.      * @param index the position within {@code array} to insert the new values
  2795.      * @param array the array to insert the values into, may be {@code null}
  2796.      * @param values the new values to insert, may be {@code null}
  2797.      * @return The new array or {@code null} if the given array is {@code null}.
  2798.      * @throws IndexOutOfBoundsException if {@code array} is provided
  2799.      * and either {@code index < 0} or {@code index > array.length}
  2800.      * @since 3.6
  2801.      */
  2802.     public static byte[] insert(final int index, final byte[] array, final byte... values) {
  2803.         if (array == null) {
  2804.             return null;
  2805.         }
  2806.         if (isEmpty(values)) {
  2807.             return clone(array);
  2808.         }
  2809.         if (index < 0 || index > array.length) {
  2810.             throw new IndexOutOfBoundsException("Index: " + index + ", Length: " + array.length);
  2811.         }
  2812.         final byte[] result = new byte[array.length + values.length];
  2813.         System.arraycopy(values, 0, result, index, values.length);
  2814.         if (index > 0) {
  2815.             System.arraycopy(array, 0, result, 0, index);
  2816.         }
  2817.         if (index < array.length) {
  2818.             System.arraycopy(array, index, result, index + values.length, array.length - index);
  2819.         }
  2820.         return result;
  2821.     }

  2823.     /**
  2824.      * Inserts elements into an array at the given index (starting from zero).
  2825.      *
  2826.      * <p>When an array is returned, it is always a new array.</p>
  2827.      *
  2828.      * <pre>
  2829.      * ArrayUtils.insert(index, null, null)      = null
  2830.      * ArrayUtils.insert(index, array, null)     = cloned copy of 'array'
  2831.      * ArrayUtils.insert(index, null, values)    = null
  2832.      * </pre>
  2833.      *
  2834.      * @param index the position within {@code array} to insert the new values
  2835.      * @param array the array to insert the values into, may be {@code null}
  2836.      * @param values the new values to insert, may be {@code null}
  2837.      * @return The new array or {@code null} if the given array is {@code null}.
  2838.      * @throws IndexOutOfBoundsException if {@code array} is provided
  2839.      * and either {@code index < 0} or {@code index > array.length}
  2840.      * @since 3.6
  2841.      */
  2842.     public static char[] insert(final int index, final char[] array, final char... values) {
  2843.         if (array == null) {
  2844.             return null;
  2845.         }
  2846.         if (isEmpty(values)) {
  2847.             return clone(array);
  2848.         }
  2849.         if (index < 0 || index > array.length) {
  2850.             throw new IndexOutOfBoundsException("Index: " + index + ", Length: " + array.length);
  2851.         }
  2852.         final char[] result = new char[array.length + values.length];
  2853.         System.arraycopy(values, 0, result, index, values.length);
  2854.         if (index > 0) {
  2855.             System.arraycopy(array, 0, result, 0, index);
  2856.         }
  2857.         if (index < array.length) {
  2858.             System.arraycopy(array, index, result, index + values.length, array.length - index);
  2859.         }
  2860.         return result;
  2861.     }

  2863.     /**
  2864.      * Inserts elements into an array at the given index (starting from zero).
  2865.      *
  2866.      * <p>When an array is returned, it is always a new array.</p>
  2867.      *
  2868.      * <pre>
  2869.      * ArrayUtils.insert(index, null, null)      = null
  2870.      * ArrayUtils.insert(index, array, null)     = cloned copy of 'array'
  2871.      * ArrayUtils.insert(index, null, values)    = null
  2872.      * </pre>
  2873.      *
  2874.      * @param index the position within {@code array} to insert the new values
  2875.      * @param array the array to insert the values into, may be {@code null}
  2876.      * @param values the new values to insert, may be {@code null}
  2877.      * @return The new array or {@code null} if the given array is {@code null}.
  2878.      * @throws IndexOutOfBoundsException if {@code array} is provided
  2879.      * and either {@code index < 0} or {@code index > array.length}
  2880.      * @since 3.6
  2881.      */
  2882.     public static double[] insert(final int index, final double[] array, final double... values) {
  2883.         if (array == null) {
  2884.             return null;
  2885.         }
  2886.         if (isEmpty(values)) {
  2887.             return clone(array);
  2888.         }
  2889.         if (index < 0 || index > array.length) {
  2890.             throw new IndexOutOfBoundsException("Index: " + index + ", Length: " + array.length);
  2891.         }
  2892.         final double[] result = new double[array.length + values.length];
  2893.         System.arraycopy(values, 0, result, index, values.length);
  2894.         if (index > 0) {
  2895.             System.arraycopy(array, 0, result, 0, index);
  2896.         }
  2897.         if (index < array.length) {
  2898.             System.arraycopy(array, index, result, index + values.length, array.length - index);
  2899.         }
  2900.         return result;
  2901.     }

  2903.     /**
  2904.      * Inserts elements into an array at the given index (starting from zero).
  2905.      *
  2906.      * <p>When an array is returned, it is always a new array.</p>
  2907.      *
  2908.      * <pre>
  2909.      * ArrayUtils.insert(index, null, null)      = null
  2910.      * ArrayUtils.insert(index, array, null)     = cloned copy of 'array'
  2911.      * ArrayUtils.insert(index, null, values)    = null
  2912.      * </pre>
  2913.      *
  2914.      * @param index the position within {@code array} to insert the new values
  2915.      * @param array the array to insert the values into, may be {@code null}
  2916.      * @param values the new values to insert, may be {@code null}
  2917.      * @return The new array or {@code null} if the given array is {@code null}.
  2918.      * @throws IndexOutOfBoundsException if {@code array} is provided
  2919.      * and either {@code index < 0} or {@code index > array.length}
  2920.      * @since 3.6
  2921.      */
  2922.     public static float[] insert(final int index, final float[] array, final float... values) {
  2923.         if (array == null) {
  2924.             return null;
  2925.         }
  2926.         if (isEmpty(values)) {
  2927.             return clone(array);
  2928.         }
  2929.         if (index < 0 || index > array.length) {
  2930.             throw new IndexOutOfBoundsException("Index: " + index + ", Length: " + array.length);
  2931.         }
  2932.         final float[] result = new float[array.length + values.length];
  2933.         System.arraycopy(values, 0, result, index, values.length);
  2934.         if (index > 0) {
  2935.             System.arraycopy(array, 0, result, 0, index);
  2936.         }
  2937.         if (index < array.length) {
  2938.             System.arraycopy(array, index, result, index + values.length, array.length - index);
  2939.         }
  2940.         return result;
  2941.     }

  2943.     /**
  2944.      * Inserts elements into an array at the given index (starting from zero).
  2945.      *
  2946.      * <p>When an array is returned, it is always a new array.</p>
  2947.      *
  2948.      * <pre>
  2949.      * ArrayUtils.insert(index, null, null)      = null
  2950.      * ArrayUtils.insert(index, array, null)     = cloned copy of 'array'
  2951.      * ArrayUtils.insert(index, null, values)    = null
  2952.      * </pre>
  2953.      *
  2954.      * @param index the position within {@code array} to insert the new values
  2955.      * @param array the array to insert the values into, may be {@code null}
  2956.      * @param values the new values to insert, may be {@code null}
  2957.      * @return The new array or {@code null} if the given array is {@code null}.
  2958.      * @throws IndexOutOfBoundsException if {@code array} is provided
  2959.      * and either {@code index < 0} or {@code index > array.length}
  2960.      * @since 3.6
  2961.      */
  2962.     public static int[] insert(final int index, final int[] array, final int... values) {
  2963.         if (array == null) {
  2964.             return null;
  2965.         }
  2966.         if (isEmpty(values)) {
  2967.             return clone(array);
  2968.         }
  2969.         if (index < 0 || index > array.length) {
  2970.             throw new IndexOutOfBoundsException("Index: " + index + ", Length: " + array.length);
  2971.         }
  2972.         final int[] result = new int[array.length + values.length];
  2973.         System.arraycopy(values, 0, result, index, values.length);
  2974.         if (index > 0) {
  2975.             System.arraycopy(array, 0, result, 0, index);
  2976.         }
  2977.         if (index < array.length) {
  2978.             System.arraycopy(array, index, result, index + values.length, array.length - index);
  2979.         }
  2980.         return result;
  2981.     }

  2983.     /**
  2984.      * Inserts elements into an array at the given index (starting from zero).
  2985.      *
  2986.      * <p>When an array is returned, it is always a new array.</p>
  2987.      *
  2988.      * <pre>
  2989.      * ArrayUtils.insert(index, null, null)      = null
  2990.      * ArrayUtils.insert(index, array, null)     = cloned copy of 'array'
  2991.      * ArrayUtils.insert(index, null, values)    = null
  2992.      * </pre>
  2993.      *
  2994.      * @param index the position within {@code array} to insert the new values
  2995.      * @param array the array to insert the values into, may be {@code null}
  2996.      * @param values the new values to insert, may be {@code null}
  2997.      * @return The new array or {@code null} if the given array is {@code null}.
  2998.      * @throws IndexOutOfBoundsException if {@code array} is provided
  2999.      * and either {@code index < 0} or {@code index > array.length}
  3000.      * @since 3.6
  3001.      */
  3002.     public static long[] insert(final int index, final long[] array, final long... values) {
  3003.         if (array == null) {
  3004.             return null;
  3005.         }
  3006.         if (isEmpty(values)) {
  3007.             return clone(array);
  3008.         }
  3009.         if (index < 0 || index > array.length) {
  3010.             throw new IndexOutOfBoundsException("Index: " + index + ", Length: " + array.length);
  3011.         }
  3012.         final long[] result = new long[array.length + values.length];
  3013.         System.arraycopy(values, 0, result, index, values.length);
  3014.         if (index > 0) {
  3015.             System.arraycopy(array, 0, result, 0, index);
  3016.         }
  3017.         if (index < array.length) {
  3018.             System.arraycopy(array, index, result, index + values.length, array.length - index);
  3019.         }
  3020.         return result;
  3021.     }

  3023.     /**
  3024.      * Inserts elements into an array at the given index (starting from zero).
  3025.      *
  3026.      * <p>When an array is returned, it is always a new array.</p>
  3027.      *
  3028.      * <pre>
  3029.      * ArrayUtils.insert(index, null, null)      = null
  3030.      * ArrayUtils.insert(index, array, null)     = cloned copy of 'array'
  3031.      * ArrayUtils.insert(index, null, values)    = null
  3032.      * </pre>
  3033.      *
  3034.      * @param index the position within {@code array} to insert the new values
  3035.      * @param array the array to insert the values into, may be {@code null}
  3036.      * @param values the new values to insert, may be {@code null}
  3037.      * @return The new array or {@code null} if the given array is {@code null}.
  3038.      * @throws IndexOutOfBoundsException if {@code array} is provided
  3039.      * and either {@code index < 0} or {@code index > array.length}
  3040.      * @since 3.6
  3041.      */
  3042.     public static short[] insert(final int index, final short[] array, final short... values) {
  3043.         if (array == null) {
  3044.             return null;
  3045.         }
  3046.         if (isEmpty(values)) {
  3047.             return clone(array);
  3048.         }
  3049.         if (index < 0 || index > array.length) {
  3050.             throw new IndexOutOfBoundsException("Index: " + index + ", Length: " + array.length);
  3051.         }
  3052.         final short[] result = new short[array.length + values.length];
  3053.         System.arraycopy(values, 0, result, index, values.length);
  3054.         if (index > 0) {
  3055.             System.arraycopy(array, 0, result, 0, index);
  3056.         }
  3057.         if (index < array.length) {
  3058.             System.arraycopy(array, index, result, index + values.length, array.length - index);
  3059.         }
  3060.         return result;
  3061.     }

  3063.     /**
  3064.      * Inserts elements into an array at the given index (starting from zero).
  3065.      *
  3066.      * <p>When an array is returned, it is always a new array.</p>
  3067.      *
  3068.      * <pre>
  3069.      * ArrayUtils.insert(index, null, null)      = null
  3070.      * ArrayUtils.insert(index, array, null)     = cloned copy of 'array'
  3071.      * ArrayUtils.insert(index, null, values)    = null
  3072.      * </pre>
  3073.      *
  3074.      * @param <T> The type of elements in {@code array} and {@code values}
  3075.      * @param index the position within {@code array} to insert the new values
  3076.      * @param array the array to insert the values into, may be {@code null}
  3077.      * @param values the new values to insert, may be {@code null}
  3078.      * @return The new array or {@code null} if the given array is {@code null}.
  3079.      * @throws IndexOutOfBoundsException if {@code array} is provided
  3080.      * and either {@code index < 0} or {@code index > array.length}
  3081.      * @since 3.6
  3082.      */
  3083.     @SafeVarargs
  3084.     public static <T> T[] insert(final int index, final T[] array, final T... values) {
  3085.         /*
  3086.          * Note on use of @SafeVarargs:
  3087.          *
  3088.          * By returning null when 'array' is null, we avoid returning the vararg
  3089.          * array to the caller. We also avoid relying on the type of the vararg
  3090.          * array, by inspecting the component type of 'array'.
  3091.          */
  3092.         if (array == null) {
  3093.             return null;
  3094.         }
  3095.         if (isEmpty(values)) {
  3096.             return clone(array);
  3097.         }
  3098.         if (index < 0 || index > array.length) {
  3099.             throw new IndexOutOfBoundsException("Index: " + index + ", Length: " + array.length);
  3100.         }
  3101.         final Class<T> type = getComponentType(array);
  3102.         final int length = array.length + values.length;
  3103.         final T[] result = newInstance(type, length);
  3104.         System.arraycopy(values, 0, result, index, values.length);
  3105.         if (index > 0) {
  3106.             System.arraycopy(array, 0, result, 0, index);
  3107.         }
  3108.         if (index < array.length) {
  3109.             System.arraycopy(array, index, result, index + values.length, array.length - index);
  3110.         }
  3111.         return result;
  3112.     }

  3114.     /**
  3115.      * Checks if an array is empty or {@code null}.
  3116.      *
  3117.      * @param array the array to test
  3118.      * @return {@code true} if the array is empty or {@code null}
  3119.      */
  3120.     private static boolean isArrayEmpty(final Object array) {
  3121.         return getLength(array) == 0;
  3122.     }

  3124.     /**
  3125.      * Returns whether a given array can safely be accessed at the given index.
  3126.      *
  3127.      * <pre>
  3128.      * ArrayUtils.isArrayIndexValid(null, 0)       = false
  3129.      * ArrayUtils.isArrayIndexValid([], 0)         = false
  3130.      * ArrayUtils.isArrayIndexValid(["a"], 0)      = true
  3131.      * </pre>
  3132.      *
  3133.      * @param <T> the component type of the array
  3134.      * @param array the array to inspect, may be null
  3135.      * @param index the index of the array to be inspected
  3136.      * @return Whether the given index is safely-accessible in the given array
  3137.      * @since 3.8
  3138.      */
  3139.     public static <T> boolean isArrayIndexValid(final T[] array, final int index) {
  3140.         return index >= 0 && getLength(array) > index;
  3141.     }

  3143.     /**
  3144.      * Checks if an array of primitive booleans is empty or {@code null}.
  3145.      *
  3146.      * @param array  the array to test
  3147.      * @return {@code true} if the array is empty or {@code null}
  3148.      * @since 2.1
  3149.      */
  3150.     public static boolean isEmpty(final boolean[] array) {
  3151.         return isArrayEmpty(array);
  3152.     }

  3154.     /**
  3155.      * Checks if an array of primitive bytes is empty or {@code null}.
  3156.      *
  3157.      * @param array  the array to test
  3158.      * @return {@code true} if the array is empty or {@code null}
  3159.      * @since 2.1
  3160.      */
  3161.     public static boolean isEmpty(final byte[] array) {
  3162.         return isArrayEmpty(array);
  3163.     }

  3165.     /**
  3166.      * Checks if an array of primitive chars is empty or {@code null}.
  3167.      *
  3168.      * @param array  the array to test
  3169.      * @return {@code true} if the array is empty or {@code null}
  3170.      * @since 2.1
  3171.      */
  3172.     public static boolean isEmpty(final char[] array) {
  3173.         return isArrayEmpty(array);
  3174.     }

  3176.     /**
  3177.      * Checks if an array of primitive doubles is empty or {@code null}.
  3178.      *
  3179.      * @param array  the array to test
  3180.      * @return {@code true} if the array is empty or {@code null}
  3181.      * @since 2.1
  3182.      */
  3183.     public static boolean isEmpty(final double[] array) {
  3184.         return isArrayEmpty(array);
  3185.     }

  3187.     /**
  3188.      * Checks if an array of primitive floats is empty or {@code null}.
  3189.      *
  3190.      * @param array  the array to test
  3191.      * @return {@code true} if the array is empty or {@code null}
  3192.      * @since 2.1
  3193.      */
  3194.     public static boolean isEmpty(final float[] array) {
  3195.         return isArrayEmpty(array);
  3196.     }

  3198.     /**
  3199.      * Checks if an array of primitive ints is empty or {@code null}.
  3200.      *
  3201.      * @param array  the array to test
  3202.      * @return {@code true} if the array is empty or {@code null}
  3203.      * @since 2.1
  3204.      */
  3205.     public static boolean isEmpty(final int[] array) {
  3206.         return isArrayEmpty(array);
  3207.     }

  3209.     /**
  3210.      * Checks if an array of primitive longs is empty or {@code null}.
  3211.      *
  3212.      * @param array  the array to test
  3213.      * @return {@code true} if the array is empty or {@code null}
  3214.      * @since 2.1
  3215.      */
  3216.     public static boolean isEmpty(final long[] array) {
  3217.         return isArrayEmpty(array);
  3218.     }

  3220.     /**
  3221.      * Checks if an array of Objects is empty or {@code null}.
  3222.      *
  3223.      * @param array  the array to test
  3224.      * @return {@code true} if the array is empty or {@code null}
  3225.      * @since 2.1
  3226.      */
  3227.     public static boolean isEmpty(final Object[] array) {
  3228.         return isArrayEmpty(array);
  3229.     }

  3231.     /**
  3232.      * Checks if an array of primitive shorts is empty or {@code null}.
  3233.      *
  3234.      * @param array  the array to test
  3235.      * @return {@code true} if the array is empty or {@code null}
  3236.      * @since 2.1
  3237.      */
  3238.     public static boolean isEmpty(final short[] array) {
  3239.         return isArrayEmpty(array);
  3240.     }

  3242.     /**
  3243.      * Compares two arrays, using equals(), handling multidimensional arrays
  3244.      * correctly.
  3245.      * <p>
  3246.      * Multi-dimensional primitive arrays are also handled correctly by this method.
  3247.      * </p>
  3248.      *
  3249.      * @param array1  the left-hand side array to compare, may be {@code null}
  3250.      * @param array2  the right-hand side array to compare, may be {@code null}
  3251.      * @return {@code true} if the arrays are equal
  3252.      * @deprecated this method has been replaced by {@code java.util.Objects.deepEquals(Object, Object)} and will be
  3253.      * removed from future releases.
  3254.      */
  3255.     @Deprecated
  3256.     public static boolean isEquals(final Object array1, final Object array2) {
  3257.         return new EqualsBuilder().append(array1, array2).isEquals();
  3258.     }

  3260.     /**
  3261.      * Checks if an array of primitive booleans is not empty and not {@code null}.
  3262.      *
  3263.      * @param array  the array to test
  3264.      * @return {@code true} if the array is not empty and not {@code null}
  3265.      * @since 2.5
  3266.      */
  3267.     public static boolean isNotEmpty(final boolean[] array) {
  3268.         return !isEmpty(array);
  3269.     }

  3271.     /**
  3272.      * Checks if an array of primitive bytes is not empty and not {@code null}.
  3273.      *
  3274.      * @param array  the array to test
  3275.      * @return {@code true} if the array is not empty and not {@code null}
  3276.      * @since 2.5
  3277.      */
  3278.     public static boolean isNotEmpty(final byte[] array) {
  3279.         return !isEmpty(array);
  3280.     }

  3282.     /**
  3283.      * Checks if an array of primitive chars is not empty and not {@code null}.
  3284.      *
  3285.      * @param array  the array to test
  3286.      * @return {@code true} if the array is not empty and not {@code null}
  3287.      * @since 2.5
  3288.      */
  3289.     public static boolean isNotEmpty(final char[] array) {
  3290.         return !isEmpty(array);
  3291.     }

  3293.     /**
  3294.      * Checks if an array of primitive doubles is not empty and not {@code null}.
  3295.      *
  3296.      * @param array  the array to test
  3297.      * @return {@code true} if the array is not empty and not {@code null}
  3298.      * @since 2.5
  3299.      */
  3300.     public static boolean isNotEmpty(final double[] array) {
  3301.         return !isEmpty(array);
  3302.     }

  3304.     /**
  3305.      * Checks if an array of primitive floats is not empty and not {@code null}.
  3306.      *
  3307.      * @param array  the array to test
  3308.      * @return {@code true} if the array is not empty and not {@code null}
  3309.      * @since 2.5
  3310.      */
  3311.     public static boolean isNotEmpty(final float[] array) {
  3312.         return !isEmpty(array);
  3313.     }

  3315.     /**
  3316.      * Checks if an array of primitive ints is not empty and not {@code null}.
  3317.      *
  3318.      * @param array  the array to test
  3319.      * @return {@code true} if the array is not empty and not {@code null}
  3320.      * @since 2.5
  3321.      */
  3322.     public static boolean isNotEmpty(final int[] array) {
  3323.         return !isEmpty(array);
  3324.     }

  3326.     /**
  3327.      * Checks if an array of primitive longs is not empty and not {@code null}.
  3328.      *
  3329.      * @param array  the array to test
  3330.      * @return {@code true} if the array is not empty and not {@code null}
  3331.      * @since 2.5
  3332.      */
  3333.     public static boolean isNotEmpty(final long[] array) {
  3334.         return !isEmpty(array);
  3335.     }

  3337.     /**
  3338.      * Checks if an array of primitive shorts is not empty and not {@code null}.
  3339.      *
  3340.      * @param array  the array to test
  3341.      * @return {@code true} if the array is not empty and not {@code null}
  3342.      * @since 2.5
  3343.      */
  3344.     public static boolean isNotEmpty(final short[] array) {
  3345.         return !isEmpty(array);
  3346.     }

  3348.     /**
  3349.      * Checks if an array of Objects is not empty and not {@code null}.
  3350.      *
  3351.      * @param <T> the component type of the array
  3352.      * @param array  the array to test
  3353.      * @return {@code true} if the array is not empty and not {@code null}
  3354.      * @since 2.5
  3355.      */
  3356.      public static <T> boolean isNotEmpty(final T[] array) {
  3357.          return !isEmpty(array);
  3358.      }

  3360.     /**
  3361.      * Checks whether two arrays are the same length, treating
  3362.      * {@code null} arrays as length {@code 0}.
  3363.      *
  3364.      * @param array1 the first array, may be {@code null}
  3365.      * @param array2 the second array, may be {@code null}
  3366.      * @return {@code true} if length of arrays matches, treating
  3367.      *  {@code null} as an empty array
  3368.      */
  3369.     public static boolean isSameLength(final boolean[] array1, final boolean[] array2) {
  3370.         return getLength(array1) == getLength(array2);
  3371.     }

  3373.     /**
  3374.      * Checks whether two arrays are the same length, treating
  3375.      * {@code null} arrays as length {@code 0}.
  3376.      *
  3377.      * @param array1 the first array, may be {@code null}
  3378.      * @param array2 the second array, may be {@code null}
  3379.      * @return {@code true} if length of arrays matches, treating
  3380.      *  {@code null} as an empty array
  3381.      */
  3382.     public static boolean isSameLength(final byte[] array1, final byte[] array2) {
  3383.         return getLength(array1) == getLength(array2);
  3384.     }

  3386.     /**
  3387.      * Checks whether two arrays are the same length, treating
  3388.      * {@code null} arrays as length {@code 0}.
  3389.      *
  3390.      * @param array1 the first array, may be {@code null}
  3391.      * @param array2 the second array, may be {@code null}
  3392.      * @return {@code true} if length of arrays matches, treating
  3393.      *  {@code null} as an empty array
  3394.      */
  3395.     public static boolean isSameLength(final char[] array1, final char[] array2) {
  3396.         return getLength(array1) == getLength(array2);
  3397.     }

  3399.     /**
  3400.      * Checks whether two arrays are the same length, treating
  3401.      * {@code null} arrays as length {@code 0}.
  3402.      *
  3403.      * @param array1 the first array, may be {@code null}
  3404.      * @param array2 the second array, may be {@code null}
  3405.      * @return {@code true} if length of arrays matches, treating
  3406.      *  {@code null} as an empty array
  3407.      */
  3408.     public static boolean isSameLength(final double[] array1, final double[] array2) {
  3409.         return getLength(array1) == getLength(array2);
  3410.     }

  3412.     /**
  3413.      * Checks whether two arrays are the same length, treating
  3414.      * {@code null} arrays as length {@code 0}.
  3415.      *
  3416.      * @param array1 the first array, may be {@code null}
  3417.      * @param array2 the second array, may be {@code null}
  3418.      * @return {@code true} if length of arrays matches, treating
  3419.      *  {@code null} as an empty array
  3420.      */
  3421.     public static boolean isSameLength(final float[] array1, final float[] array2) {
  3422.         return getLength(array1) == getLength(array2);
  3423.     }

  3425.     /**
  3426.      * Checks whether two arrays are the same length, treating
  3427.      * {@code null} arrays as length {@code 0}.
  3428.      *
  3429.      * @param array1 the first array, may be {@code null}
  3430.      * @param array2 the second array, may be {@code null}
  3431.      * @return {@code true} if length of arrays matches, treating
  3432.      *  {@code null} as an empty array
  3433.      */
  3434.     public static boolean isSameLength(final int[] array1, final int[] array2) {
  3435.         return getLength(array1) == getLength(array2);
  3436.     }

  3438.     /**
  3439.      * Checks whether two arrays are the same length, treating
  3440.      * {@code null} arrays as length {@code 0}.
  3441.      *
  3442.      * @param array1 the first array, may be {@code null}
  3443.      * @param array2 the second array, may be {@code null}
  3444.      * @return {@code true} if length of arrays matches, treating
  3445.      *  {@code null} as an empty array
  3446.      */
  3447.     public static boolean isSameLength(final long[] array1, final long[] array2) {
  3448.         return getLength(array1) == getLength(array2);
  3449.     }

  3451.     /**
  3452.      * Checks whether two arrays are the same length, treating
  3453.      * {@code null} arrays as length {@code 0}.
  3454.      * <p>
  3455.      * Any multi-dimensional aspects of the arrays are ignored.
  3456.      * </p>
  3457.      *
  3458.      * @param array1 the first array, may be {@code null}
  3459.      * @param array2 the second array, may be {@code null}
  3460.      * @return {@code true} if length of arrays matches, treating
  3461.      *  {@code null} as an empty array
  3462.      * @since 3.11
  3463.      */
  3464.     public static boolean isSameLength(final Object array1, final Object array2) {
  3465.         return getLength(array1) == getLength(array2);
  3466.     }

  3468.     /**
  3469.      * Checks whether two arrays are the same length, treating
  3470.      * {@code null} arrays as length {@code 0}.
  3471.      * <p>
  3472.      * Any multi-dimensional aspects of the arrays are ignored.
  3473.      * </p>
  3474.      *
  3475.      * @param array1 the first array, may be {@code null}
  3476.      * @param array2 the second array, may be {@code null}
  3477.      * @return {@code true} if length of arrays matches, treating
  3478.      *  {@code null} as an empty array
  3479.      */
  3480.     public static boolean isSameLength(final Object[] array1, final Object[] array2) {
  3481.         return getLength(array1) == getLength(array2);
  3482.     }

  3484.     /**
  3485.      * Checks whether two arrays are the same length, treating
  3486.      * {@code null} arrays as length {@code 0}.
  3487.      *
  3488.      * @param array1 the first array, may be {@code null}
  3489.      * @param array2 the second array, may be {@code null}
  3490.      * @return {@code true} if length of arrays matches, treating
  3491.      *  {@code null} as an empty array
  3492.      */
  3493.     public static boolean isSameLength(final short[] array1, final short[] array2) {
  3494.         return getLength(array1) == getLength(array2);
  3495.     }

  3497.     /**
  3498.      * Checks whether two arrays are the same type taking into account
  3499.      * multidimensional arrays.
  3500.      *
  3501.      * @param array1 the first array, must not be {@code null}
  3502.      * @param array2 the second array, must not be {@code null}
  3503.      * @return {@code true} if type of arrays matches
  3504.      * @throws IllegalArgumentException if either array is {@code null}
  3505.      */
  3506.     public static boolean isSameType(final Object array1, final Object array2) {
  3507.         if (array1 == null || array2 == null) {
  3508.             throw new IllegalArgumentException("The Array must not be null");
  3509.         }
  3510.         return array1.getClass().getName().equals(array2.getClass().getName());
  3511.     }

  3513.     /**
  3514.      * This method checks whether the provided array is sorted according to natural ordering
  3515.      * ({@code false} before {@code true}).
  3516.      *
  3517.      * @param array the array to check
  3518.      * @return whether the array is sorted according to natural ordering
  3519.      * @since 3.4
  3520.      */
  3521.     public static boolean isSorted(final boolean[] array) {
  3522.         if (getLength(array) < 2) {
  3523.             return true;
  3524.         }
  3525.         boolean previous = array[0];
  3526.         final int n = array.length;
  3527.         for (int i = 1; i < n; i++) {
  3528.             final boolean current = array[i];
  3529.             if (BooleanUtils.compare(previous, current) > 0) {
  3530.                 return false;
  3531.             }
  3532.             previous = current;
  3533.         }
  3534.         return true;
  3535.     }

  3537.     /**
  3538.      * Checks whether the provided array is sorted according to natural ordering.
  3539.      *
  3540.      * @param array the array to check
  3541.      * @return whether the array is sorted according to natural ordering
  3542.      * @since 3.4
  3543.      */
  3544.     public static boolean isSorted(final byte[] array) {
  3545.         if (getLength(array) < 2) {
  3546.             return true;
  3547.         }
  3548.         byte previous = array[0];
  3549.         final int n = array.length;
  3550.         for (int i = 1; i < n; i++) {
  3551.             final byte current = array[i];
  3552.             if (NumberUtils.compare(previous, current) > 0) {
  3553.                 return false;
  3554.             }
  3555.             previous = current;
  3556.         }
  3557.         return true;
  3558.     }

  3560.     /**
  3561.      * Checks whether the provided array is sorted according to natural ordering.
  3562.      *
  3563.      * @param array the array to check
  3564.      * @return whether the array is sorted according to natural ordering
  3565.      * @since 3.4
  3566.      */
  3567.     public static boolean isSorted(final char[] array) {
  3568.         if (getLength(array) < 2) {
  3569.             return true;
  3570.         }
  3571.         char previous = array[0];
  3572.         final int n = array.length;
  3573.         for (int i = 1; i < n; i++) {
  3574.             final char current = array[i];
  3575.             if (CharUtils.compare(previous, current) > 0) {
  3576.                 return false;
  3577.             }
  3578.             previous = current;
  3579.         }
  3580.         return true;
  3581.     }

  3583.     /**
  3584.      * This method checks whether the provided array is sorted according to natural ordering.
  3585.      *
  3586.      * @param array the array to check
  3587.      * @return whether the array is sorted according to natural ordering
  3588.      * @since 3.4
  3589.      */
  3590.     public static boolean isSorted(final double[] array) {
  3591.         if (getLength(array) < 2) {
  3592.             return true;
  3593.         }
  3594.         double previous = array[0];
  3595.         final int n = array.length;
  3596.         for (int i = 1; i < n; i++) {
  3597.             final double current = array[i];
  3598.             if (Double.compare(previous, current) > 0) {
  3599.                 return false;
  3600.             }
  3601.             previous = current;
  3602.         }
  3603.         return true;
  3604.     }

  3606.     /**
  3607.      * This method checks whether the provided array is sorted according to natural ordering.
  3608.      *
  3609.      * @param array the array to check
  3610.      * @return whether the array is sorted according to natural ordering
  3611.      * @since 3.4
  3612.      */
  3613.     public static boolean isSorted(final float[] array) {
  3614.         if (getLength(array) < 2) {
  3615.             return true;
  3616.         }
  3617.         float previous = array[0];
  3618.         final int n = array.length;
  3619.         for (int i = 1; i < n; i++) {
  3620.             final float current = array[i];
  3621.             if (Float.compare(previous, current) > 0) {
  3622.                 return false;
  3623.             }
  3624.             previous = current;
  3625.         }
  3626.         return true;
  3627.     }

  3629.     /**
  3630.      * This method checks whether the provided array is sorted according to natural ordering.
  3631.      *
  3632.      * @param array the array to check
  3633.      * @return whether the array is sorted according to natural ordering
  3634.      * @since 3.4
  3635.      */
  3636.     public static boolean isSorted(final int[] array) {
  3637.         if (getLength(array) < 2) {
  3638.             return true;
  3639.         }
  3640.         int previous = array[0];
  3641.         final int n = array.length;
  3642.         for (int i = 1; i < n; i++) {
  3643.             final int current = array[i];
  3644.             if (NumberUtils.compare(previous, current) > 0) {
  3645.                 return false;
  3646.             }
  3647.             previous = current;
  3648.         }
  3649.         return true;
  3650.     }

  3652.     /**
  3653.      * This method checks whether the provided array is sorted according to natural ordering.
  3654.      *
  3655.      * @param array the array to check
  3656.      * @return whether the array is sorted according to natural ordering
  3657.      * @since 3.4
  3658.      */
  3659.     public static boolean isSorted(final long[] array) {
  3660.         if (getLength(array) < 2) {
  3661.             return true;
  3662.         }
  3663.         long previous = array[0];
  3664.         final int n = array.length;
  3665.         for (int i = 1; i < n; i++) {
  3666.             final long current = array[i];
  3667.             if (NumberUtils.compare(previous, current) > 0) {
  3668.                 return false;
  3669.             }
  3670.             previous = current;
  3671.         }
  3672.         return true;
  3673.     }

  3675.     /**
  3676.      * This method checks whether the provided array is sorted according to natural ordering.
  3677.      *
  3678.      * @param array the array to check
  3679.      * @return whether the array is sorted according to natural ordering
  3680.      * @since 3.4
  3681.      */
  3682.     public static boolean isSorted(final short[] array) {
  3683.         if (getLength(array) < 2) {
  3684.             return true;
  3685.         }
  3686.         short previous = array[0];
  3687.         final int n = array.length;
  3688.         for (int i = 1; i < n; i++) {
  3689.             final short current = array[i];
  3690.             if (NumberUtils.compare(previous, current) > 0) {
  3691.                 return false;
  3692.             }
  3693.             previous = current;
  3694.         }
  3695.         return true;
  3696.     }

  3698.     /**
  3699.      * This method checks whether the provided array is sorted according to the class's
  3700.      * {@code compareTo} method.
  3701.      *
  3702.      * @param array the array to check
  3703.      * @param <T> the datatype of the array to check, it must implement {@link Comparable}
  3704.      * @return whether the array is sorted
  3705.      * @since 3.4
  3706.      */
  3707.     public static <T extends Comparable<? super T>> boolean isSorted(final T[] array) {
  3708.         return isSorted(array, Comparable::compareTo);
  3709.     }

  3711.     /**
  3712.      * This method checks whether the provided array is sorted according to the provided {@link Comparator}.
  3713.      *
  3714.      * @param array the array to check
  3715.      * @param comparator the {@link Comparator} to compare over
  3716.      * @param <T> the datatype of the array
  3717.      * @return whether the array is sorted
  3718.      * @throws NullPointerException if {@code comparator} is {@code null}
  3719.      * @since 3.4
  3720.      */
  3721.     public static <T> boolean isSorted(final T[] array, final Comparator<T> comparator) {
  3722.         Objects.requireNonNull(comparator, "comparator");
  3723.         if (getLength(array) < 2) {
  3724.             return true;
  3725.         }
  3726.         T previous = array[0];
  3727.         final int n = array.length;
  3728.         for (int i = 1; i < n; i++) {
  3729.             final T current = array[i];
  3730.             if (comparator.compare(previous, current) > 0) {
  3731.                 return false;
  3732.             }
  3733.             previous = current;
  3734.         }
  3735.         return true;
  3736.     }

  3738.     /**
  3739.      * Finds the last index of the given value within the array.
  3740.      * <p>
  3741.      * This method returns {@link #INDEX_NOT_FOUND} ({@code -1}) if
  3742.      * {@code null} array input.
  3743.      * </p>
  3744.      *
  3745.      * @param array  the array to traverse backwards looking for the object, may be {@code null}
  3746.      * @param valueToFind  the object to find
  3747.      * @return the last index of the value within the array,
  3748.      *  {@link #INDEX_NOT_FOUND} ({@code -1}) if not found or {@code null} array input
  3749.      */
  3750.     public static int lastIndexOf(final boolean[] array, final boolean valueToFind) {
  3751.         return lastIndexOf(array, valueToFind, Integer.MAX_VALUE);
  3752.     }

  3754.     /**
  3755.      * Finds the last index of the given value in the array starting at the given index.
  3756.      * <p>
  3757.      * This method returns {@link #INDEX_NOT_FOUND} ({@code -1}) for a {@code null} input array.
  3758.      * </p>
  3759.      * <p>
  3760.      * A negative startIndex will return {@link #INDEX_NOT_FOUND} ({@code -1}). A startIndex larger than
  3761.      * the array length will search from the end of the array.
  3762.      * </p>
  3763.      *
  3764.      * @param array  the array to traverse for looking for the object, may be {@code null}
  3765.      * @param valueToFind  the value to find
  3766.      * @param startIndex  the start index to traverse backwards from
  3767.      * @return the last index of the value within the array,
  3768.      *  {@link #INDEX_NOT_FOUND} ({@code -1}) if not found or {@code null} array input
  3769.      */
  3770.     public static int lastIndexOf(final boolean[] array, final boolean valueToFind, int startIndex) {
  3771.         if (isEmpty(array) || startIndex < 0) {
  3772.             return INDEX_NOT_FOUND;
  3773.         }
  3774.         if (startIndex >= array.length) {
  3775.             startIndex = array.length - 1;
  3776.         }
  3777.         for (int i = startIndex; i >= 0; i--) {
  3778.             if (valueToFind == array[i]) {
  3779.                 return i;
  3780.             }
  3781.         }
  3782.         return INDEX_NOT_FOUND;
  3783.     }

  3785.     /**
  3786.      * Finds the last index of the given value within the array.
  3787.      * <p>
  3788.      * This method returns {@link #INDEX_NOT_FOUND} ({@code -1}) for a {@code null} input array.
  3789.      * </p>
  3790.      *
  3791.      * @param array  the array to traverse backwards looking for the object, may be {@code null}
  3792.      * @param valueToFind  the object to find
  3793.      * @return the last index of the value within the array,
  3794.      *  {@link #INDEX_NOT_FOUND} ({@code -1}) if not found or {@code null} array input
  3795.      */
  3796.     public static int lastIndexOf(final byte[] array, final byte valueToFind) {
  3797.         return lastIndexOf(array, valueToFind, Integer.MAX_VALUE);
  3798.     }

  3800.     /**
  3801.      * Finds the last index of the given value in the array starting at the given index.
  3802.      * <p>
  3803.      * This method returns {@link #INDEX_NOT_FOUND} ({@code -1}) for a {@code null} input array.
  3804.      * </p>
  3805.      * <p>
  3806.      * A negative startIndex will return {@link #INDEX_NOT_FOUND} ({@code -1}). A startIndex larger than the
  3807.      * array length will search from the end of the array.
  3808.      * </p>
  3809.      *
  3810.      * @param array  the array to traverse for looking for the object, may be {@code null}
  3811.      * @param valueToFind  the value to find
  3812.      * @param startIndex  the start index to traverse backwards from
  3813.      * @return the last index of the value within the array,
  3814.      *  {@link #INDEX_NOT_FOUND} ({@code -1}) if not found or {@code null} array input
  3815.      */
  3816.     public static int lastIndexOf(final byte[] array, final byte valueToFind, int startIndex) {
  3817.         if (array == null || startIndex < 0) {
  3818.             return INDEX_NOT_FOUND;
  3819.         }
  3820.         if (startIndex >= array.length) {
  3821.             startIndex = array.length - 1;
  3822.         }
  3823.         for (int i = startIndex; i >= 0; i--) {
  3824.             if (valueToFind == array[i]) {
  3825.                 return i;
  3826.             }
  3827.         }
  3828.         return INDEX_NOT_FOUND;
  3829.     }

  3831.     /**
  3832.      * Finds the last index of the given value within the array.
  3833.      * <p>
  3834.      * This method returns {@link #INDEX_NOT_FOUND} ({@code -1}) for a {@code null} input array.
  3835.      * </p>
  3836.      *
  3837.      * @param array  the array to traverse backwards looking for the object, may be {@code null}
  3838.      * @param valueToFind  the object to find
  3839.      * @return the last index of the value within the array,
  3840.      *  {@link #INDEX_NOT_FOUND} ({@code -1}) if not found or {@code null} array input
  3841.      * @since 2.1
  3842.      */
  3843.     public static int lastIndexOf(final char[] array, final char valueToFind) {
  3844.         return lastIndexOf(array, valueToFind, Integer.MAX_VALUE);
  3845.     }

  3847.     /**
  3848.      * Finds the last index of the given value in the array starting at the given index.
  3849.      * <p>
  3850.      * This method returns {@link #INDEX_NOT_FOUND} ({@code -1}) for a {@code null} input array.
  3851.      * </p>
  3852.      * <p>
  3853.      * A negative startIndex will return {@link #INDEX_NOT_FOUND} ({@code -1}). A startIndex larger than the
  3854.      * array length will search from the end of the array.
  3855.      * </p>
  3856.      *
  3857.      * @param array  the array to traverse for looking for the object, may be {@code null}
  3858.      * @param valueToFind  the value to find
  3859.      * @param startIndex  the start index to traverse backwards from
  3860.      * @return the last index of the value within the array,
  3861.      *  {@link #INDEX_NOT_FOUND} ({@code -1}) if not found or {@code null} array input
  3862.      * @since 2.1
  3863.      */
  3864.     public static int lastIndexOf(final char[] array, final char valueToFind, int startIndex) {
  3865.         if (array == null || startIndex < 0) {
  3866.             return INDEX_NOT_FOUND;
  3867.         }
  3868.         if (startIndex >= array.length) {
  3869.             startIndex = array.length - 1;
  3870.         }
  3871.         for (int i = startIndex; i >= 0; i--) {
  3872.             if (valueToFind == array[i]) {
  3873.                 return i;
  3874.             }
  3875.         }
  3876.         return INDEX_NOT_FOUND;
  3877.     }

  3879.     /**
  3880.      * Finds the last index of the given value within the array.
  3881.      * <p>
  3882.      * This method returns {@link #INDEX_NOT_FOUND} ({@code -1}) for a {@code null} input array.
  3883.      * </p>
  3884.      *
  3885.      * @param array  the array to traverse backwards looking for the object, may be {@code null}
  3886.      * @param valueToFind  the object to find
  3887.      * @return the last index of the value within the array,
  3888.      *  {@link #INDEX_NOT_FOUND} ({@code -1}) if not found or {@code null} array input
  3889.      */
  3890.     public static int lastIndexOf(final double[] array, final double valueToFind) {
  3891.         return lastIndexOf(array, valueToFind, Integer.MAX_VALUE);
  3892.     }

  3894.     /**
  3895.      * Finds the last index of the given value within a given tolerance in the array.
  3896.      * This method will return the index of the last value which falls between the region
  3897.      * defined by valueToFind - tolerance and valueToFind + tolerance.
  3898.      * <p>
  3899.      * This method returns {@link #INDEX_NOT_FOUND} ({@code -1}) for a {@code null} input array.
  3900.      * </p>
  3901.      *
  3902.      * @param array  the array to search through for the object, may be {@code null}
  3903.      * @param valueToFind  the value to find
  3904.      * @param tolerance tolerance of the search
  3905.      * @return the index of the value within the array,
  3906.      *  {@link #INDEX_NOT_FOUND} ({@code -1}) if not found or {@code null} array input
  3907.      */
  3908.     public static int lastIndexOf(final double[] array, final double valueToFind, final double tolerance) {
  3909.         return lastIndexOf(array, valueToFind, Integer.MAX_VALUE, tolerance);
  3910.     }

  3912.     /**
  3913.      * Finds the last index of the given value in the array starting at the given index.
  3914.      * <p>
  3915.      * This method returns {@link #INDEX_NOT_FOUND} ({@code -1}) for a {@code null} input array.
  3916.      * </p>
  3917.      * <p>
  3918.      * A negative startIndex will return {@link #INDEX_NOT_FOUND} ({@code -1}). A startIndex larger than the
  3919.      * array length will search from the end of the array.
  3920.      * </p>
  3921.      *
  3922.      * @param array  the array to traverse for looking for the object, may be {@code null}
  3923.      * @param valueToFind  the value to find
  3924.      * @param startIndex  the start index to traverse backwards from
  3925.      * @return the last index of the value within the array,
  3926.      *  {@link #INDEX_NOT_FOUND} ({@code -1}) if not found or {@code null} array input
  3927.      */
  3928.     public static int lastIndexOf(final double[] array, final double valueToFind, int startIndex) {
  3929.         if (isEmpty(array) || startIndex < 0) {
  3930.             return INDEX_NOT_FOUND;
  3931.         }
  3932.         if (startIndex >= array.length) {
  3933.             startIndex = array.length - 1;
  3934.         }
  3935.         for (int i = startIndex; i >= 0; i--) {
  3936.             if (valueToFind == array[i]) {
  3937.                 return i;
  3938.             }
  3939.         }
  3940.         return INDEX_NOT_FOUND;
  3941.     }

  3943.     /**
  3944.      * Finds the last index of the given value in the array starting at the given index.
  3945.      * This method will return the index of the last value which falls between the region
  3946.      * defined by valueToFind - tolerance and valueToFind + tolerance.
  3947.      * <p>
  3948.      * This method returns {@link #INDEX_NOT_FOUND} ({@code -1}) for a {@code null} input array.
  3949.      * </p>
  3950.      * <p>
  3951.      * A negative startIndex will return {@link #INDEX_NOT_FOUND} ({@code -1}). A startIndex larger than the
  3952.      * array length will search from the end of the array.
  3953.      * </p>
  3954.      *
  3955.      * @param array  the array to traverse for looking for the object, may be {@code null}
  3956.      * @param valueToFind  the value to find
  3957.      * @param startIndex  the start index to traverse backwards from
  3958.      * @param tolerance  search for value within plus/minus this amount
  3959.      * @return the last index of the value within the array,
  3960.      *  {@link #INDEX_NOT_FOUND} ({@code -1}) if not found or {@code null} array input
  3961.      */
  3962.     public static int lastIndexOf(final double[] array, final double valueToFind, int startIndex, final double tolerance) {
  3963.         if (isEmpty(array) || startIndex < 0) {
  3964.             return INDEX_NOT_FOUND;
  3965.         }
  3966.         if (startIndex >= array.length) {
  3967.             startIndex = array.length - 1;
  3968.         }
  3969.         final double min = valueToFind - tolerance;
  3970.         final double max = valueToFind + tolerance;
  3971.         for (int i = startIndex; i >= 0; i--) {
  3972.             if (array[i] >= min && array[i] <= max) {
  3973.                 return i;
  3974.             }
  3975.         }
  3976.         return INDEX_NOT_FOUND;
  3977.     }

  3979.     /**
  3980.      * Finds the last index of the given value within the array.
  3981.      * <p>
  3982.      * This method returns {@link #INDEX_NOT_FOUND} ({@code -1}) for a {@code null} input array.
  3983.      * </p>
  3984.      *
  3985.      * @param array  the array to traverse backwards looking for the object, may be {@code null}
  3986.      * @param valueToFind  the object to find
  3987.      * @return the last index of the value within the array,
  3988.      *  {@link #INDEX_NOT_FOUND} ({@code -1}) if not found or {@code null} array input
  3989.      */
  3990.     public static int lastIndexOf(final float[] array, final float valueToFind) {
  3991.         return lastIndexOf(array, valueToFind, Integer.MAX_VALUE);
  3992.     }

  3994.     /**
  3995.      * Finds the last index of the given value in the array starting at the given index.
  3996.      * <p>
  3997.      * This method returns {@link #INDEX_NOT_FOUND} ({@code -1}) for a {@code null} input array.
  3998.      * </p>
  3999.      * <p>
  4000.      * A negative startIndex will return {@link #INDEX_NOT_FOUND} ({@code -1}). A startIndex larger than the
  4001.      * array length will search from the end of the array.
  4002.      * </p>
  4003.      *
  4004.      * @param array  the array to traverse for looking for the object, may be {@code null}
  4005.      * @param valueToFind  the value to find
  4006.      * @param startIndex  the start index to traverse backwards from
  4007.      * @return the last index of the value within the array,
  4008.      *  {@link #INDEX_NOT_FOUND} ({@code -1}) if not found or {@code null} array input
  4009.      */
  4010.     public static int lastIndexOf(final float[] array, final float valueToFind, int startIndex) {
  4011.         if (isEmpty(array) || startIndex < 0) {
  4012.             return INDEX_NOT_FOUND;
  4013.         }
  4014.         if (startIndex >= array.length) {
  4015.             startIndex = array.length - 1;
  4016.         }
  4017.         for (int i = startIndex; i >= 0; i--) {
  4018.             if (valueToFind == array[i]) {
  4019.                 return i;
  4020.             }
  4021.         }
  4022.         return INDEX_NOT_FOUND;
  4023.     }

  4025.     /**
  4026.      * Finds the last index of the given value within the array.
  4027.      * <p>
  4028.      * This method returns {@link #INDEX_NOT_FOUND} ({@code -1}) for a {@code null} input array.
  4029.      * </p>
  4030.      *
  4031.      * @param array  the array to traverse backwards looking for the object, may be {@code null}
  4032.      * @param valueToFind  the object to find
  4033.      * @return the last index of the value within the array,
  4034.      *  {@link #INDEX_NOT_FOUND} ({@code -1}) if not found or {@code null} array input
  4035.      */
  4036.     public static int lastIndexOf(final int[] array, final int valueToFind) {
  4037.         return lastIndexOf(array, valueToFind, Integer.MAX_VALUE);
  4038.     }

  4040.     /**
  4041.      * Finds the last index of the given value in the array starting at the given index.
  4042.      * <p>
  4043.      * This method returns {@link #INDEX_NOT_FOUND} ({@code -1}) for a {@code null} input array.
  4044.      * </p>
  4045.      * <p>
  4046.      * A negative startIndex will return {@link #INDEX_NOT_FOUND} ({@code -1}). A startIndex larger than the
  4047.      * array length will search from the end of the array.
  4048.      * </p>
  4049.      *
  4050.      * @param array  the array to traverse for looking for the object, may be {@code null}
  4051.      * @param valueToFind  the value to find
  4052.      * @param startIndex  the start index to traverse backwards from
  4053.      * @return the last index of the value within the array,
  4054.      *  {@link #INDEX_NOT_FOUND} ({@code -1}) if not found or {@code null} array input
  4055.      */
  4056.     public static int lastIndexOf(final int[] array, final int valueToFind, int startIndex) {
  4057.         if (array == null || startIndex < 0) {
  4058.             return INDEX_NOT_FOUND;
  4059.         }
  4060.         if (startIndex >= array.length) {
  4061.             startIndex = array.length - 1;
  4062.         }
  4063.         for (int i = startIndex; i >= 0; i--) {
  4064.             if (valueToFind == array[i]) {
  4065.                 return i;
  4066.             }
  4067.         }
  4068.         return INDEX_NOT_FOUND;
  4069.     }

  4071.     /**
  4072.      * Finds the last index of the given value within the array.
  4073.      * <p>
  4074.      * This method returns {@link #INDEX_NOT_FOUND} ({@code -1}) for a {@code null} input array.
  4075.      * </p>
  4076.      *
  4077.      * @param array  the array to traverse backwards looking for the object, may be {@code null}
  4078.      * @param valueToFind  the object to find
  4079.      * @return the last index of the value within the array,
  4080.      *  {@link #INDEX_NOT_FOUND} ({@code -1}) if not found or {@code null} array input
  4081.      */
  4082.     public static int lastIndexOf(final long[] array, final long valueToFind) {
  4083.         return lastIndexOf(array, valueToFind, Integer.MAX_VALUE);
  4084.     }

  4086.     /**
  4087.      * Finds the last index of the given value in the array starting at the given index.
  4088.      * <p>
  4089.      * This method returns {@link #INDEX_NOT_FOUND} ({@code -1}) for a {@code null} input array.
  4090.      * </p>
  4091.      * <p>
  4092.      * A negative startIndex will return {@link #INDEX_NOT_FOUND} ({@code -1}). A startIndex larger than the
  4093.      * array length will search from the end of the array.
  4094.      * </p>
  4095.      *
  4096.      * @param array  the array to traverse for looking for the object, may be {@code null}
  4097.      * @param valueToFind  the value to find
  4098.      * @param startIndex  the start index to traverse backwards from
  4099.      * @return the last index of the value within the array,
  4100.      *  {@link #INDEX_NOT_FOUND} ({@code -1}) if not found or {@code null} array input
  4101.      */
  4102.     public static int lastIndexOf(final long[] array, final long valueToFind, int startIndex) {
  4103.         if (array == null || startIndex < 0) {
  4104.             return INDEX_NOT_FOUND;
  4105.         }
  4106.         if (startIndex >= array.length) {
  4107.             startIndex = array.length - 1;
  4108.         }
  4109.         for (int i = startIndex; i >= 0; i--) {
  4110.             if (valueToFind == array[i]) {
  4111.                 return i;
  4112.             }
  4113.         }
  4114.         return INDEX_NOT_FOUND;
  4115.     }

  4117.     /**
  4118.      * Finds the last index of the given object within the array.
  4119.      * <p>
  4120.      * This method returns {@link #INDEX_NOT_FOUND} ({@code -1}) for a {@code null} input array.
  4121.      * </p>
  4122.      *
  4123.      * @param array  the array to traverse backwards looking for the object, may be {@code null}
  4124.      * @param objectToFind  the object to find, may be {@code null}
  4125.      * @return the last index of the object within the array,
  4126.      *  {@link #INDEX_NOT_FOUND} ({@code -1}) if not found or {@code null} array input
  4127.      */
  4128.     public static int lastIndexOf(final Object[] array, final Object objectToFind) {
  4129.         return lastIndexOf(array, objectToFind, Integer.MAX_VALUE);
  4130.     }

  4132.     /**
  4133.      * Finds the last index of the given object in the array starting at the given index.
  4134.      * <p>
  4135.      * This method returns {@link #INDEX_NOT_FOUND} ({@code -1}) for a {@code null} input array.
  4136.      * </p>
  4137.      * <p>
  4138.      * A negative startIndex will return {@link #INDEX_NOT_FOUND} ({@code -1}). A startIndex larger than
  4139.      * the array length will search from the end of the array.
  4140.      * </p>
  4141.      *
  4142.      * @param array  the array to traverse for looking for the object, may be {@code null}
  4143.      * @param objectToFind  the object to find, may be {@code null}
  4144.      * @param startIndex  the start index to traverse backwards from
  4145.      * @return the last index of the object within the array,
  4146.      *  {@link #INDEX_NOT_FOUND} ({@code -1}) if not found or {@code null} array input
  4147.      */
  4148.     public static int lastIndexOf(final Object[] array, final Object objectToFind, int startIndex) {
  4149.         if (array == null || startIndex < 0) {
  4150.             return INDEX_NOT_FOUND;
  4151.         }
  4152.         if (startIndex >= array.length) {
  4153.             startIndex = array.length - 1;
  4154.         }
  4155.         if (objectToFind == null) {
  4156.             for (int i = startIndex; i >= 0; i--) {
  4157.                 if (array[i] == null) {
  4158.                     return i;
  4159.                 }
  4160.             }
  4161.         } else if (array.getClass().getComponentType().isInstance(objectToFind)) {
  4162.             for (int i = startIndex; i >= 0; i--) {
  4163.                 if (objectToFind.equals(array[i])) {
  4164.                     return i;
  4165.                 }
  4166.             }
  4167.         }
  4168.         return INDEX_NOT_FOUND;
  4169.     }

  4171.     /**
  4172.      * Finds the last index of the given value within the array.
  4173.      * <p>
  4174.      * This method returns {@link #INDEX_NOT_FOUND} ({@code -1}) for a {@code null} input array.
  4175.      * </p>
  4176.      *
  4177.      * @param array  the array to traverse backwards looking for the object, may be {@code null}
  4178.      * @param valueToFind  the object to find
  4179.      * @return the last index of the value within the array,
  4180.      *  {@link #INDEX_NOT_FOUND} ({@code -1}) if not found or {@code null} array input
  4181.      */
  4182.     public static int lastIndexOf(final short[] array, final short valueToFind) {
  4183.         return lastIndexOf(array, valueToFind, Integer.MAX_VALUE);
  4184.     }

  4186.     /**
  4187.      * Finds the last index of the given value in the array starting at the given index.
  4188.      * <p>
  4189.      * This method returns {@link #INDEX_NOT_FOUND} ({@code -1}) for a {@code null} input array.
  4190.      * </p>
  4191.      * <p>
  4192.      * A negative startIndex will return {@link #INDEX_NOT_FOUND} ({@code -1}). A startIndex larger than the
  4193.      * array length will search from the end of the array.
  4194.      * </p>
  4195.      *
  4196.      * @param array  the array to traverse for looking for the object, may be {@code null}
  4197.      * @param valueToFind  the value to find
  4198.      * @param startIndex  the start index to traverse backwards from
  4199.      * @return the last index of the value within the array,
  4200.      *  {@link #INDEX_NOT_FOUND} ({@code -1}) if not found or {@code null} array input
  4201.      */
  4202.     public static int lastIndexOf(final short[] array, final short valueToFind, int startIndex) {
  4203.         if (array == null || startIndex < 0) {
  4204.             return INDEX_NOT_FOUND;
  4205.         }
  4206.         if (startIndex >= array.length) {
  4207.             startIndex = array.length - 1;
  4208.         }
  4209.         for (int i = startIndex; i >= 0; i--) {
  4210.             if (valueToFind == array[i]) {
  4211.                 return i;
  4212.             }
  4213.         }
  4214.         return INDEX_NOT_FOUND;
  4215.     }

  4217.     private static int max0(int other) {
  4218.         return Math.max(0, other);
  4219.     }

  4221.     /**
  4222.      * Delegates to {@link Array#newInstance(Class,int)} using generics.
  4223.      *
  4224.      * @param <T> The array type.
  4225.      * @param componentType The array class.
  4226.      * @param length the array length
  4227.      * @return The new array.
  4228.      * @throws NullPointerException if the specified {@code componentType} parameter is null.
  4229.      * @since 3.13.0
  4230.      */
  4231.     @SuppressWarnings("unchecked") // OK, because array and values are of type T
  4232.     public static <T> T[] newInstance(final Class<T> componentType, final int length) {
  4233.         return (T[]) Array.newInstance(componentType, length);
  4234.     }

  4236.     /**
  4237.      * Defensive programming technique to change a {@code null}
  4238.      * reference to an empty one.
  4239.      * <p>
  4240.      * This method returns a default array for a {@code null} input array.
  4241.      * </p>
  4242.      * <p>
  4243.      * As a memory optimizing technique an empty array passed in will be overridden with
  4244.      * the empty {@code public static} references in this class.
  4245.      * </p>
  4246.      *
  4247.      * @param <T> The array type.
  4248.      * @param array  the array to check for {@code null} or empty
  4249.      * @param defaultArray A default array, usually empty.
  4250.      * @return the same array, or defaultArray if {@code null} or empty input.
  4251.      * @since 3.15.0
  4252.      */
  4253.     public static  <T> T[] nullTo(final T[] array, final T[] defaultArray) {
  4254.         return isEmpty(array) ? defaultArray : array;
  4255.     }

  4257.     /**
  4258.      * Defensive programming technique to change a {@code null}
  4259.      * reference to an empty one.
  4260.      * <p>
  4261.      * This method returns an empty array for a {@code null} input array.
  4262.      * </p>
  4263.      * <p>
  4264.      * As a memory optimizing technique an empty array passed in will be overridden with
  4265.      * the empty {@code public static} references in this class.
  4266.      * </p>
  4267.      *
  4268.      * @param array  the array to check for {@code null} or empty
  4269.      * @return the same array, {@code public static} empty array if {@code null} or empty input
  4270.      * @since 2.5
  4271.      */
  4272.     public static boolean[] nullToEmpty(final boolean[] array) {
  4273.         return isEmpty(array) ? EMPTY_BOOLEAN_ARRAY : array;
  4274.     }

  4276.     /**
  4277.      * Defensive programming technique to change a {@code null}
  4278.      * reference to an empty one.
  4279.      * <p>
  4280.      * This method returns an empty array for a {@code null} input array.
  4281.      * </p>
  4282.      * <p>
  4283.      * As a memory optimizing technique an empty array passed in will be overridden with
  4284.      * the empty {@code public static} references in this class.
  4285.      * </p>
  4286.      *
  4287.      * @param array  the array to check for {@code null} or empty
  4288.      * @return the same array, {@code public static} empty array if {@code null} or empty input
  4289.      * @since 2.5
  4290.      */
  4291.     public static Boolean[] nullToEmpty(final Boolean[] array) {
  4292.         return nullTo(array, EMPTY_BOOLEAN_OBJECT_ARRAY);
  4293.     }

  4295.     /**
  4296.      * Defensive programming technique to change a {@code null}
  4297.      * reference to an empty one.
  4298.      * <p>
  4299.      * This method returns an empty array for a {@code null} input array.
  4300.      * </p>
  4301.      * <p>
  4302.      * As a memory optimizing technique an empty array passed in will be overridden with
  4303.      * the empty {@code public static} references in this class.
  4304.      * </p>
  4305.      *
  4306.      * @param array  the array to check for {@code null} or empty
  4307.      * @return the same array, {@code public static} empty array if {@code null} or empty input
  4308.      * @since 2.5
  4309.      */
  4310.     public static byte[] nullToEmpty(final byte[] array) {
  4311.         return isEmpty(array) ? EMPTY_BYTE_ARRAY : array;
  4312.     }

  4314.     /**
  4315.      * Defensive programming technique to change a {@code null}
  4316.      * reference to an empty one.
  4317.      * <p>
  4318.      * This method returns an empty array for a {@code null} input array.
  4319.      * </p>
  4320.      * <p>
  4321.      * As a memory optimizing technique an empty array passed in will be overridden with
  4322.      * the empty {@code public static} references in this class.
  4323.      * </p>
  4324.      *
  4325.      * @param array  the array to check for {@code null} or empty
  4326.      * @return the same array, {@code public static} empty array if {@code null} or empty input
  4327.      * @since 2.5
  4328.      */
  4329.     public static Byte[] nullToEmpty(final Byte[] array) {
  4330.         return nullTo(array, EMPTY_BYTE_OBJECT_ARRAY);
  4331.     }

  4333.     /**
  4334.      * Defensive programming technique to change a {@code null}
  4335.      * reference to an empty one.
  4336.      * <p>
  4337.      * This method returns an empty array for a {@code null} input array.
  4338.      * </p>
  4339.      * <p>
  4340.      * As a memory optimizing technique an empty array passed in will be overridden with
  4341.      * the empty {@code public static} references in this class.
  4342.      * </p>
  4343.      *
  4344.      * @param array  the array to check for {@code null} or empty
  4345.      * @return the same array, {@code public static} empty array if {@code null} or empty input
  4346.      * @since 2.5
  4347.      */
  4348.     public static char[] nullToEmpty(final char[] array) {
  4349.         return isEmpty(array) ? EMPTY_CHAR_ARRAY : array;
  4350.     }

  4352.     /**
  4353.      * Defensive programming technique to change a {@code null}
  4354.      * reference to an empty one.
  4355.      * <p>
  4356.      * This method returns an empty array for a {@code null} input array.
  4357.      * </p>
  4358.      * <p>
  4359.      * As a memory optimizing technique an empty array passed in will be overridden with
  4360.      * the empty {@code public static} references in this class.
  4361.      * </p>
  4362.      *
  4363.      * @param array  the array to check for {@code null} or empty
  4364.      * @return the same array, {@code public static} empty array if {@code null} or empty input
  4365.      * @since 2.5
  4366.      */
  4367.     public static Character[] nullToEmpty(final Character[] array) {
  4368.         return nullTo(array, EMPTY_CHARACTER_OBJECT_ARRAY);
  4369.     }

  4371.     /**
  4372.      * Defensive programming technique to change a {@code null}
  4373.      * reference to an empty one.
  4374.      * <p>
  4375.      * This method returns an empty array for a {@code null} input array.
  4376.      * </p>
  4377.      * <p>
  4378.      * As a memory optimizing technique an empty array passed in will be overridden with
  4379.      * the empty {@code public static} references in this class.
  4380.      * </p>
  4381.      *
  4382.      * @param array  the array to check for {@code null} or empty
  4383.      * @return the same array, {@code public static} empty array if {@code null} or empty input
  4384.      * @since 3.2
  4385.      */
  4386.     public static Class<?>[] nullToEmpty(final Class<?>[] array) {
  4387.         return nullTo(array, EMPTY_CLASS_ARRAY);
  4388.     }

  4390.     /**
  4391.      * Defensive programming technique to change a {@code null}
  4392.      * reference to an empty one.
  4393.      * <p>
  4394.      * This method returns an empty array for a {@code null} input array.
  4395.      * </p>
  4396.      * <p>
  4397.      * As a memory optimizing technique an empty array passed in will be overridden with
  4398.      * the empty {@code public static} references in this class.
  4399.      * </p>
  4400.      *
  4401.      * @param array  the array to check for {@code null} or empty
  4402.      * @return the same array, {@code public static} empty array if {@code null} or empty input
  4403.      * @since 2.5
  4404.      */
  4405.     public static double[] nullToEmpty(final double[] array) {
  4406.         return isEmpty(array) ? EMPTY_DOUBLE_ARRAY : array;
  4407.     }

  4409.     /**
  4410.      * Defensive programming technique to change a {@code null}
  4411.      * reference to an empty one.
  4412.      * <p>
  4413.      * This method returns an empty array for a {@code null} input array.
  4414.      * </p>
  4415.      * <p>
  4416.      * As a memory optimizing technique an empty array passed in will be overridden with
  4417.      * the empty {@code public static} references in this class.
  4418.      * </p>
  4419.      *
  4420.      * @param array  the array to check for {@code null} or empty
  4421.      * @return the same array, {@code public static} empty array if {@code null} or empty input
  4422.      * @since 2.5
  4423.      */
  4424.     public static Double[] nullToEmpty(final Double[] array) {
  4425.         return nullTo(array, EMPTY_DOUBLE_OBJECT_ARRAY);
  4426.     }

  4428.     /**
  4429.      * Defensive programming technique to change a {@code null}
  4430.      * reference to an empty one.
  4431.      * <p>
  4432.      * This method returns an empty array for a {@code null} input array.
  4433.      * </p>
  4434.      * <p>
  4435.      * As a memory optimizing technique an empty array passed in will be overridden with
  4436.      * the empty {@code public static} references in this class.
  4437.      * </p>
  4438.      *
  4439.      * @param array  the array to check for {@code null} or empty
  4440.      * @return the same array, {@code public static} empty array if {@code null} or empty input
  4441.      * @since 2.5
  4442.      */
  4443.     public static float[] nullToEmpty(final float[] array) {
  4444.         return isEmpty(array) ? EMPTY_FLOAT_ARRAY : array;
  4445.     }

  4447.     /**
  4448.      * Defensive programming technique to change a {@code null}
  4449.      * reference to an empty one.
  4450.      * <p>
  4451.      * This method returns an empty array for a {@code null} input array.
  4452.      * </p>
  4453.      * <p>
  4454.      * As a memory optimizing technique an empty array passed in will be overridden with
  4455.      * the empty {@code public static} references in this class.
  4456.      * </p>
  4457.      *
  4458.      * @param array  the array to check for {@code null} or empty
  4459.      * @return the same array, {@code public static} empty array if {@code null} or empty input
  4460.      * @since 2.5
  4461.      */
  4462.     public static Float[] nullToEmpty(final Float[] array) {
  4463.         return nullTo(array, EMPTY_FLOAT_OBJECT_ARRAY);
  4464.     }

  4466.     /**
  4467.      * Defensive programming technique to change a {@code null}
  4468.      * reference to an empty one.
  4469.      * <p>
  4470.      * This method returns an empty array for a {@code null} input array.
  4471.      * </p>
  4472.      * <p>
  4473.      * As a memory optimizing technique an empty array passed in will be overridden with
  4474.      * the empty {@code public static} references in this class.
  4475.      * </p>
  4476.      *
  4477.      * @param array  the array to check for {@code null} or empty
  4478.      * @return the same array, {@code public static} empty array if {@code null} or empty input
  4479.      * @since 2.5
  4480.      */
  4481.     public static int[] nullToEmpty(final int[] array) {
  4482.         return isEmpty(array) ? EMPTY_INT_ARRAY : array;
  4483.     }

  4485.     /**
  4486.      * Defensive programming technique to change a {@code null}
  4487.      * reference to an empty one.
  4488.      * <p>
  4489.      * This method returns an empty array for a {@code null} input array.
  4490.      * </p>
  4491.      * <p>
  4492.      * As a memory optimizing technique an empty array passed in will be overridden with
  4493.      * the empty {@code public static} references in this class.
  4494.      * </p>
  4495.      *
  4496.      * @param array  the array to check for {@code null} or empty
  4497.      * @return the same array, {@code public static} empty array if {@code null} or empty input
  4498.      * @since 2.5
  4499.      */
  4500.     public static Integer[] nullToEmpty(final Integer[] array) {
  4501.         return nullTo(array, EMPTY_INTEGER_OBJECT_ARRAY);
  4502.     }

  4504.     /**
  4505.      * Defensive programming technique to change a {@code null}
  4506.      * reference to an empty one.
  4507.      * <p>
  4508.      * This method returns an empty array for a {@code null} input array.
  4509.      * </p>
  4510.      * <p>
  4511.      * As a memory optimizing technique an empty array passed in will be overridden with
  4512.      * the empty {@code public static} references in this class.
  4513.      * </p>
  4514.      *
  4515.      * @param array  the array to check for {@code null} or empty
  4516.      * @return the same array, {@code public static} empty array if {@code null} or empty input
  4517.      * @since 2.5
  4518.      */
  4519.     public static long[] nullToEmpty(final long[] array) {
  4520.         return isEmpty(array) ? EMPTY_LONG_ARRAY : array;
  4521.     }

  4523.     /**
  4524.      * Defensive programming technique to change a {@code null}
  4525.      * reference to an empty one.
  4526.      * <p>
  4527.      * This method returns an empty array for a {@code null} input array.
  4528.      * </p>
  4529.      * <p>
  4530.      * As a memory optimizing technique an empty array passed in will be overridden with
  4531.      * the empty {@code public static} references in this class.
  4532.      * </p>
  4533.      *
  4534.      * @param array  the array to check for {@code null} or empty
  4535.      * @return the same array, {@code public static} empty array if {@code null} or empty input
  4536.      * @since 2.5
  4537.      */
  4538.     public static Long[] nullToEmpty(final Long[] array) {
  4539.         return nullTo(array, EMPTY_LONG_OBJECT_ARRAY);
  4540.     }

  4542.     /**
  4543.      * Defensive programming technique to change a {@code null}
  4544.      * reference to an empty one.
  4545.      * <p>
  4546.      * This method returns an empty array for a {@code null} input array.
  4547.      * </p>
  4548.      * <p>
  4549.      * As a memory optimizing technique an empty array passed in will be overridden with
  4550.      * the empty {@code public static} references in this class.
  4551.      * </p>
  4552.      *
  4553.      * @param array  the array to check for {@code null} or empty
  4554.      * @return the same array, {@code public static} empty array if {@code null} or empty input
  4555.      * @since 2.5
  4556.      */
  4557.     public static Object[] nullToEmpty(final Object[] array) {
  4558.         return nullTo(array, EMPTY_OBJECT_ARRAY);
  4559.     }

  4561.     /**
  4562.      * Defensive programming technique to change a {@code null}
  4563.      * reference to an empty one.
  4564.      * <p>
  4565.      * This method returns an empty array for a {@code null} input array.
  4566.      * </p>
  4567.      * <p>
  4568.      * As a memory optimizing technique an empty array passed in will be overridden with
  4569.      * the empty {@code public static} references in this class.
  4570.      * </p>
  4571.      *
  4572.      * @param array  the array to check for {@code null} or empty
  4573.      * @return the same array, {@code public static} empty array if {@code null} or empty input
  4574.      * @since 2.5
  4575.      */
  4576.     public static short[] nullToEmpty(final short[] array) {
  4577.         return isEmpty(array) ? EMPTY_SHORT_ARRAY : array;
  4578.     }

  4580.     /**
  4581.      * Defensive programming technique to change a {@code null}
  4582.      * reference to an empty one.
  4583.      * <p>
  4584.      * This method returns an empty array for a {@code null} input array.
  4585.      * </p>
  4586.      * <p>
  4587.      * As a memory optimizing technique an empty array passed in will be overridden with
  4588.      * the empty {@code public static} references in this class.
  4589.      * </p>
  4590.      *
  4591.      * @param array  the array to check for {@code null} or empty
  4592.      * @return the same array, {@code public static} empty array if {@code null} or empty input
  4593.      * @since 2.5
  4594.      */
  4595.     public static Short[] nullToEmpty(final Short[] array) {
  4596.         return nullTo(array, EMPTY_SHORT_OBJECT_ARRAY);
  4597.     }

  4599.     /**
  4600.      * Defensive programming technique to change a {@code null}
  4601.      * reference to an empty one.
  4602.      * <p>
  4603.      * This method returns an empty array for a {@code null} input array.
  4604.      * </p>
  4605.      * <p>
  4606.      * As a memory optimizing technique an empty array passed in will be overridden with
  4607.      * the empty {@code public static} references in this class.
  4608.      * </p>
  4609.      *
  4610.      * @param array  the array to check for {@code null} or empty
  4611.      * @return the same array, {@code public static} empty array if {@code null} or empty input
  4612.      * @since 2.5
  4613.      */
  4614.     public static String[] nullToEmpty(final String[] array) {
  4615.         return nullTo(array, EMPTY_STRING_ARRAY);
  4616.     }

  4618.     /**
  4619.      * Defensive programming technique to change a {@code null}
  4620.      * reference to an empty one.
  4621.      * <p>
  4622.      * This method returns an empty array for a {@code null} input array.
  4623.      * </p>
  4624.      *
  4625.      * @param array  the array to check for {@code null} or empty
  4626.      * @param type   the class representation of the desired array
  4627.      * @param <T>  the class type
  4628.      * @return the same array, {@code public static} empty array if {@code null}
  4629.      * @throws IllegalArgumentException if the type argument is null
  4630.      * @since 3.5
  4631.      */
  4632.     public static <T> T[] nullToEmpty(final T[] array, final Class<T[]> type) {
  4633.         if (type == null) {
  4634.             throw new IllegalArgumentException("The type must not be null");
  4635.         }
  4636.         if (array == null) {
  4637.             return type.cast(Array.newInstance(type.getComponentType(), 0));
  4638.         }
  4639.         return array;
  4640.     }

  4642.     private static ThreadLocalRandom random() {
  4643.         return ThreadLocalRandom.current();
  4644.     }

  4646.     /**
  4647.      * Removes the element at the specified position from the specified array.
  4648.      * All subsequent elements are shifted to the left (subtracts one from
  4649.      * their indices).
  4650.      * <p>
  4651.      * This method returns a new array with the same elements of the input
  4652.      * array except the element on the specified position. The component
  4653.      * type of the returned array is always the same as that of the input
  4654.      * array.
  4655.      * </p>
  4656.      * <p>
  4657.      * If the input array is {@code null}, an IndexOutOfBoundsException
  4658.      * will be thrown, because in that case no valid index can be specified.
  4659.      * </p>
  4660.      * <pre>
  4661.      * ArrayUtils.remove([true], 0)              = []
  4662.      * ArrayUtils.remove([true, false], 0)       = [false]
  4663.      * ArrayUtils.remove([true, false], 1)       = [true]
  4664.      * ArrayUtils.remove([true, true, false], 1) = [true, false]
  4665.      * </pre>
  4666.      *
  4667.      * @param array  the array to remove the element from, may not be {@code null}
  4668.      * @param index  the position of the element to be removed
  4669.      * @return A new array containing the existing elements except the element
  4670.      *         at the specified position.
  4671.      * @throws IndexOutOfBoundsException if the index is out of range
  4672.      * (index &lt; 0 || index &gt;= array.length), or if the array is {@code null}.
  4673.      * @since 2.1
  4674.      */
  4675.     public static boolean[] remove(final boolean[] array, final int index) {
  4676.         return (boolean[]) remove((Object) array, index);
  4677.     }

  4679.     /**
  4680.      * Removes the element at the specified position from the specified array.
  4681.      * All subsequent elements are shifted to the left (subtracts one from
  4682.      * their indices).
  4683.      * <p>
  4684.      * This method returns a new array with the same elements of the input
  4685.      * array except the element on the specified position. The component
  4686.      * type of the returned array is always the same as that of the input
  4687.      * array.
  4688.      * </p>
  4689.      * <p>
  4690.      * If the input array is {@code null}, an IndexOutOfBoundsException
  4691.      * will be thrown, because in that case no valid index can be specified.
  4692.      * </p>
  4693.      * <pre>
  4694.      * ArrayUtils.remove([1], 0)          = []
  4695.      * ArrayUtils.remove([1, 0], 0)       = [0]
  4696.      * ArrayUtils.remove([1, 0], 1)       = [1]
  4697.      * ArrayUtils.remove([1, 0, 1], 1)    = [1, 1]
  4698.      * </pre>
  4699.      *
  4700.      * @param array  the array to remove the element from, may not be {@code null}
  4701.      * @param index  the position of the element to be removed
  4702.      * @return A new array containing the existing elements except the element
  4703.      *         at the specified position.
  4704.      * @throws IndexOutOfBoundsException if the index is out of range
  4705.      * (index &lt; 0 || index &gt;= array.length), or if the array is {@code null}.
  4706.      * @since 2.1
  4707.      */
  4708.     public static byte[] remove(final byte[] array, final int index) {
  4709.         return (byte[]) remove((Object) array, index);
  4710.     }

  4712.     /**
  4713.      * Removes the element at the specified position from the specified array.
  4714.      * All subsequent elements are shifted to the left (subtracts one from
  4715.      * their indices).
  4716.      * <p>
  4717.      * This method returns a new array with the same elements of the input
  4718.      * array except the element on the specified position. The component
  4719.      * type of the returned array is always the same as that of the input
  4720.      * array.
  4721.      * </p>
  4722.      * <p>
  4723.      * If the input array is {@code null}, an IndexOutOfBoundsException
  4724.      * will be thrown, because in that case no valid index can be specified.
  4725.      * </p>
  4726.      * <pre>
  4727.      * ArrayUtils.remove(['a'], 0)           = []
  4728.      * ArrayUtils.remove(['a', 'b'], 0)      = ['b']
  4729.      * ArrayUtils.remove(['a', 'b'], 1)      = ['a']
  4730.      * ArrayUtils.remove(['a', 'b', 'c'], 1) = ['a', 'c']
  4731.      * </pre>
  4732.      *
  4733.      * @param array  the array to remove the element from, may not be {@code null}
  4734.      * @param index  the position of the element to be removed
  4735.      * @return A new array containing the existing elements except the element
  4736.      *         at the specified position.
  4737.      * @throws IndexOutOfBoundsException if the index is out of range
  4738.      * (index &lt; 0 || index &gt;= array.length), or if the array is {@code null}.
  4739.      * @since 2.1
  4740.      */
  4741.     public static char[] remove(final char[] array, final int index) {
  4742.         return (char[]) remove((Object) array, index);
  4743.     }

  4745.     /**
  4746.      * Removes the element at the specified position from the specified array.
  4747.      * All subsequent elements are shifted to the left (subtracts one from
  4748.      * their indices).
  4749.      * <p>
  4750.      * This method returns a new array with the same elements of the input
  4751.      * array except the element on the specified position. The component
  4752.      * type of the returned array is always the same as that of the input
  4753.      * array.
  4754.      * </p>
  4755.      * <p>
  4756.      * If the input array is {@code null}, an IndexOutOfBoundsException
  4757.      * will be thrown, because in that case no valid index can be specified.
  4758.      * </p>
  4759.      * <pre>
  4760.      * ArrayUtils.remove([1.1], 0)           = []
  4761.      * ArrayUtils.remove([2.5, 6.0], 0)      = [6.0]
  4762.      * ArrayUtils.remove([2.5, 6.0], 1)      = [2.5]
  4763.      * ArrayUtils.remove([2.5, 6.0, 3.8], 1) = [2.5, 3.8]
  4764.      * </pre>
  4765.      *
  4766.      * @param array  the array to remove the element from, may not be {@code null}
  4767.      * @param index  the position of the element to be removed
  4768.      * @return A new array containing the existing elements except the element
  4769.      *         at the specified position.
  4770.      * @throws IndexOutOfBoundsException if the index is out of range
  4771.      * (index &lt; 0 || index &gt;= array.length), or if the array is {@code null}.
  4772.      * @since 2.1
  4773.      */
  4774.     public static double[] remove(final double[] array, final int index) {
  4775.         return (double[]) remove((Object) array, index);
  4776.     }

  4778.     /**
  4779.      * Removes the element at the specified position from the specified array.
  4780.      * All subsequent elements are shifted to the left (subtracts one from
  4781.      * their indices).
  4782.      * <p>
  4783.      * This method returns a new array with the same elements of the input
  4784.      * array except the element on the specified position. The component
  4785.      * type of the returned array is always the same as that of the input
  4786.      * array.
  4787.      * </p>
  4788.      * <p>
  4789.      * If the input array is {@code null}, an IndexOutOfBoundsException
  4790.      * will be thrown, because in that case no valid index can be specified.
  4791.      * </p>
  4792.      * <pre>
  4793.      * ArrayUtils.remove([1.1], 0)           = []
  4794.      * ArrayUtils.remove([2.5, 6.0], 0)      = [6.0]
  4795.      * ArrayUtils.remove([2.5, 6.0], 1)      = [2.5]
  4796.      * ArrayUtils.remove([2.5, 6.0, 3.8], 1) = [2.5, 3.8]
  4797.      * </pre>
  4798.      *
  4799.      * @param array  the array to remove the element from, may not be {@code null}
  4800.      * @param index  the position of the element to be removed
  4801.      * @return A new array containing the existing elements except the element
  4802.      *         at the specified position.
  4803.      * @throws IndexOutOfBoundsException if the index is out of range
  4804.      * (index &lt; 0 || index &gt;= array.length), or if the array is {@code null}.
  4805.      * @since 2.1
  4806.      */
  4807.     public static float[] remove(final float[] array, final int index) {
  4808.         return (float[]) remove((Object) array, index);
  4809.     }

  4811.     /**
  4812.      * Removes the element at the specified position from the specified array.
  4813.      * All subsequent elements are shifted to the left (subtracts one from
  4814.      * their indices).
  4815.      * <p>
  4816.      * This method returns a new array with the same elements of the input
  4817.      * array except the element on the specified position. The component
  4818.      * type of the returned array is always the same as that of the input
  4819.      * array.
  4820.      * </p>
  4821.      * <p>
  4822.      * If the input array is {@code null}, an IndexOutOfBoundsException
  4823.      * will be thrown, because in that case no valid index can be specified.
  4824.      * </p>
  4825.      * <pre>
  4826.      * ArrayUtils.remove([1], 0)         = []
  4827.      * ArrayUtils.remove([2, 6], 0)      = [6]
  4828.      * ArrayUtils.remove([2, 6], 1)      = [2]
  4829.      * ArrayUtils.remove([2, 6, 3], 1)   = [2, 3]
  4830.      * </pre>
  4831.      *
  4832.      * @param array  the array to remove the element from, may not be {@code null}
  4833.      * @param index  the position of the element to be removed
  4834.      * @return A new array containing the existing elements except the element
  4835.      *         at the specified position.
  4836.      * @throws IndexOutOfBoundsException if the index is out of range
  4837.      * (index &lt; 0 || index &gt;= array.length), or if the array is {@code null}.
  4838.      * @since 2.1
  4839.      */
  4840.     public static int[] remove(final int[] array, final int index) {
  4841.         return (int[]) remove((Object) array, index);
  4842.     }

  4844.     /**
  4845.      * Removes the element at the specified position from the specified array.
  4846.      * All subsequent elements are shifted to the left (subtracts one from
  4847.      * their indices).
  4848.      * <p>
  4849.      * This method returns a new array with the same elements of the input
  4850.      * array except the element on the specified position. The component
  4851.      * type of the returned array is always the same as that of the input
  4852.      * array.
  4853.      * </p>
  4854.      * <p>
  4855.      * If the input array is {@code null}, an IndexOutOfBoundsException
  4856.      * will be thrown, because in that case no valid index can be specified.
  4857.      * </p>
  4858.      * <pre>
  4859.      * ArrayUtils.remove([1], 0)         = []
  4860.      * ArrayUtils.remove([2, 6], 0)      = [6]
  4861.      * ArrayUtils.remove([2, 6], 1)      = [2]
  4862.      * ArrayUtils.remove([2, 6, 3], 1)   = [2, 3]
  4863.      * </pre>
  4864.      *
  4865.      * @param array  the array to remove the element from, may not be {@code null}
  4866.      * @param index  the position of the element to be removed
  4867.      * @return A new array containing the existing elements except the element
  4868.      *         at the specified position.
  4869.      * @throws IndexOutOfBoundsException if the index is out of range
  4870.      * (index &lt; 0 || index &gt;= array.length), or if the array is {@code null}.
  4871.      * @since 2.1
  4872.      */
  4873.     public static long[] remove(final long[] array, final int index) {
  4874.         return (long[]) remove((Object) array, index);
  4875.     }

  4877.     /**
  4878.      * Removes the element at the specified position from the specified array.
  4879.      * All subsequent elements are shifted to the left (subtracts one from
  4880.      * their indices).
  4881.      * <p>
  4882.      * This method returns a new array with the same elements of the input
  4883.      * array except the element on the specified position. The component
  4884.      * type of the returned array is always the same as that of the input
  4885.      * array.
  4886.      * </p>
  4887.      * <p>
  4888.      * If the input array is {@code null}, an IndexOutOfBoundsException
  4889.      * will be thrown, because in that case no valid index can be specified.
  4890.      * </p>
  4891.      *
  4892.      * @param array  the array to remove the element from, may not be {@code null}
  4893.      * @param index  the position of the element to be removed
  4894.      * @return A new array containing the existing elements except the element
  4895.      *         at the specified position.
  4896.      * @throws IndexOutOfBoundsException if the index is out of range
  4897.      * (index &lt; 0 || index &gt;= array.length), or if the array is {@code null}.
  4898.      * @since 2.1
  4899.      */
  4900.     private static Object remove(final Object array, final int index) {
  4901.         final int length = getLength(array);
  4902.         if (index < 0 || index >= length) {
  4903.             throw new IndexOutOfBoundsException("Index: " + index + ", Length: " + length);
  4904.         }
  4905.         final Object result = Array.newInstance(array.getClass().getComponentType(), length - 1);
  4906.         System.arraycopy(array, 0, result, 0, index);
  4907.         if (index < length - 1) {
  4908.             System.arraycopy(array, index + 1, result, index, length - index - 1);
  4909.         }
  4910.         return result;
  4911.     }

  4913.     /**
  4914.      * Removes the element at the specified position from the specified array.
  4915.      * All subsequent elements are shifted to the left (subtracts one from
  4916.      * their indices).
  4917.      * <p>
  4918.      * This method returns a new array with the same elements of the input
  4919.      * array except the element on the specified position. The component
  4920.      * type of the returned array is always the same as that of the input
  4921.      * array.
  4922.      * </p>
  4923.      * <p>
  4924.      * If the input array is {@code null}, an IndexOutOfBoundsException
  4925.      * will be thrown, because in that case no valid index can be specified.
  4926.      * </p>
  4927.      * <pre>
  4928.      * ArrayUtils.remove([1], 0)         = []
  4929.      * ArrayUtils.remove([2, 6], 0)      = [6]
  4930.      * ArrayUtils.remove([2, 6], 1)      = [2]
  4931.      * ArrayUtils.remove([2, 6, 3], 1)   = [2, 3]
  4932.      * </pre>
  4933.      *
  4934.      * @param array  the array to remove the element from, may not be {@code null}
  4935.      * @param index  the position of the element to be removed
  4936.      * @return A new array containing the existing elements except the element
  4937.      *         at the specified position.
  4938.      * @throws IndexOutOfBoundsException if the index is out of range
  4939.      * (index &lt; 0 || index &gt;= array.length), or if the array is {@code null}.
  4940.      * @since 2.1
  4941.      */
  4942.     public static short[] remove(final short[] array, final int index) {
  4943.         return (short[]) remove((Object) array, index);
  4944.     }

  4946.     /**
  4947.      * Removes the element at the specified position from the specified array.
  4948.      * All subsequent elements are shifted to the left (subtracts one from
  4949.      * their indices).
  4950.      * <p>
  4951.      * This method returns a new array with the same elements of the input
  4952.      * array except the element on the specified position. The component
  4953.      * type of the returned array is always the same as that of the input
  4954.      * array.
  4955.      * </p>
  4956.      * <p>
  4957.      * If the input array is {@code null}, an IndexOutOfBoundsException
  4958.      * will be thrown, because in that case no valid index can be specified.
  4959.      * </p>
  4960.      * <pre>
  4961.      * ArrayUtils.remove(["a"], 0)           = []
  4962.      * ArrayUtils.remove(["a", "b"], 0)      = ["b"]
  4963.      * ArrayUtils.remove(["a", "b"], 1)      = ["a"]
  4964.      * ArrayUtils.remove(["a", "b", "c"], 1) = ["a", "c"]
  4965.      * </pre>
  4966.      *
  4967.      * @param <T> the component type of the array
  4968.      * @param array  the array to remove the element from, may not be {@code null}
  4969.      * @param index  the position of the element to be removed
  4970.      * @return A new array containing the existing elements except the element
  4971.      *         at the specified position.
  4972.      * @throws IndexOutOfBoundsException if the index is out of range
  4973.      * (index &lt; 0 || index &gt;= array.length), or if the array is {@code null}.
  4974.      * @since 2.1
  4975.      */
  4976.     @SuppressWarnings("unchecked") // remove() always creates an array of the same type as its input
  4977.     public static <T> T[] remove(final T[] array, final int index) {
  4978.         return (T[]) remove((Object) array, index);
  4979.     }

  4981.     /**
  4982.      * Removes the elements at the specified positions from the specified array.
  4983.      * All remaining elements are shifted to the left.
  4984.      * <p>
  4985.      * This method returns a new array with the same elements of the input
  4986.      * array except those at the specified positions. The component
  4987.      * type of the returned array is always the same as that of the input
  4988.      * array.
  4989.      * </p>
  4990.      * <p>
  4991.      * If the input array is {@code null}, an IndexOutOfBoundsException
  4992.      * will be thrown, because in that case no valid index can be specified.
  4993.      * </p>
  4994.      * <pre>
  4995.      * ArrayUtils.removeAll([true, false, true], 0, 2) = [false]
  4996.      * ArrayUtils.removeAll([true, false, true], 1, 2) = [true]
  4997.      * </pre>
  4998.      *
  4999.      * @param array   the array to remove the element from, may not be {@code null}
  5000.      * @param indices the positions of the elements to be removed
  5001.      * @return A new array containing the existing elements except those
  5002.      *         at the specified positions.
  5003.      * @throws IndexOutOfBoundsException if any index is out of range
  5004.      * (index &lt; 0 || index &gt;= array.length), or if the array is {@code null}.
  5005.      * @since 3.0.1
  5006.      */
  5007.     public static boolean[] removeAll(final boolean[] array, final int... indices) {
  5008.         return (boolean[]) removeAll((Object) array, indices);
  5009.     }

  5011.     /**
  5012.      * Removes the elements at the specified positions from the specified array.
  5013.      * All remaining elements are shifted to the left.
  5014.      * <p>
  5015.      * This method returns a new array with the same elements of the input
  5016.      * array except those at the specified positions. The component
  5017.      * type of the returned array is always the same as that of the input
  5018.      * array.
  5019.      * </p>
  5020.      * <p>
  5021.      * If the input array is {@code null}, an IndexOutOfBoundsException
  5022.      * will be thrown, because in that case no valid index can be specified.
  5023.      * </p>
  5024.      * <pre>
  5025.      * ArrayUtils.removeAll([1], 0)             = []
  5026.      * ArrayUtils.removeAll([2, 6], 0)          = [6]
  5027.      * ArrayUtils.removeAll([2, 6], 0, 1)       = []
  5028.      * ArrayUtils.removeAll([2, 6, 3], 1, 2)    = [2]
  5029.      * ArrayUtils.removeAll([2, 6, 3], 0, 2)    = [6]
  5030.      * ArrayUtils.removeAll([2, 6, 3], 0, 1, 2) = []
  5031.      * </pre>
  5032.      *
  5033.      * @param array   the array to remove the element from, may not be {@code null}
  5034.      * @param indices the positions of the elements to be removed
  5035.      * @return A new array containing the existing elements except those
  5036.      *         at the specified positions.
  5037.      * @throws IndexOutOfBoundsException if any index is out of range
  5038.      * (index &lt; 0 || index &gt;= array.length), or if the array is {@code null}.
  5039.      * @since 3.0.1
  5040.      */
  5041.     public static byte[] removeAll(final byte[] array, final int... indices) {
  5042.         return (byte[]) removeAll((Object) array, indices);
  5043.     }

  5045.     /**
  5046.      * Removes the elements at the specified positions from the specified array.
  5047.      * All remaining elements are shifted to the left.
  5048.      * <p>
  5049.      * This method returns a new array with the same elements of the input
  5050.      * array except those at the specified positions. The component
  5051.      * type of the returned array is always the same as that of the input
  5052.      * array.
  5053.      * </p>
  5054.      * <p>
  5055.      * If the input array is {@code null}, an IndexOutOfBoundsException
  5056.      * will be thrown, because in that case no valid index can be specified.
  5057.      * </p>
  5058.      * <pre>
  5059.      * ArrayUtils.removeAll([1], 0)             = []
  5060.      * ArrayUtils.removeAll([2, 6], 0)          = [6]
  5061.      * ArrayUtils.removeAll([2, 6], 0, 1)       = []
  5062.      * ArrayUtils.removeAll([2, 6, 3], 1, 2)    = [2]
  5063.      * ArrayUtils.removeAll([2, 6, 3], 0, 2)    = [6]
  5064.      * ArrayUtils.removeAll([2, 6, 3], 0, 1, 2) = []
  5065.      * </pre>
  5066.      *
  5067.      * @param array   the array to remove the element from, may not be {@code null}
  5068.      * @param indices the positions of the elements to be removed
  5069.      * @return A new array containing the existing elements except those
  5070.      *         at the specified positions.
  5071.      * @throws IndexOutOfBoundsException if any index is out of range
  5072.      * (index &lt; 0 || index &gt;= array.length), or if the array is {@code null}.
  5073.      * @since 3.0.1
  5074.      */
  5075.     public static char[] removeAll(final char[] array, final int... indices) {
  5076.         return (char[]) removeAll((Object) array, indices);
  5077.     }

  5079.     /**
  5080.      * Removes the elements at the specified positions from the specified array.
  5081.      * All remaining elements are shifted to the left.
  5082.      * <p>
  5083.      * This method returns a new array with the same elements of the input
  5084.      * array except those at the specified positions. The component
  5085.      * type of the returned array is always the same as that of the input
  5086.      * array.
  5087.      * </p>
  5088.      * <p>
  5089.      * If the input array is {@code null}, an IndexOutOfBoundsException
  5090.      * will be thrown, because in that case no valid index can be specified.
  5091.      * </p>
  5092.      * <pre>
  5093.      * ArrayUtils.removeAll([1], 0)             = []
  5094.      * ArrayUtils.removeAll([2, 6], 0)          = [6]
  5095.      * ArrayUtils.removeAll([2, 6], 0, 1)       = []
  5096.      * ArrayUtils.removeAll([2, 6, 3], 1, 2)    = [2]
  5097.      * ArrayUtils.removeAll([2, 6, 3], 0, 2)    = [6]
  5098.      * ArrayUtils.removeAll([2, 6, 3], 0, 1, 2) = []
  5099.      * </pre>
  5100.      *
  5101.      * @param array   the array to remove the element from, may not be {@code null}
  5102.      * @param indices the positions of the elements to be removed
  5103.      * @return A new array containing the existing elements except those
  5104.      *         at the specified positions.
  5105.      * @throws IndexOutOfBoundsException if any index is out of range
  5106.      * (index &lt; 0 || index &gt;= array.length), or if the array is {@code null}.
  5107.      * @since 3.0.1
  5108.      */
  5109.     public static double[] removeAll(final double[] array, final int... indices) {
  5110.         return (double[]) removeAll((Object) array, indices);
  5111.     }

  5113.     /**
  5114.      * Removes the elements at the specified positions from the specified array.
  5115.      * All remaining elements are shifted to the left.
  5116.      * <p>
  5117.      * This method returns a new array with the same elements of the input
  5118.      * array except those at the specified positions. The component
  5119.      * type of the returned array is always the same as that of the input
  5120.      * array.
  5121.      * </p>
  5122.      * <p>
  5123.      * If the input array is {@code null}, an IndexOutOfBoundsException
  5124.      * will be thrown, because in that case no valid index can be specified.
  5125.      * </p>
  5126.      * <pre>
  5127.      * ArrayUtils.removeAll([1], 0)             = []
  5128.      * ArrayUtils.removeAll([2, 6], 0)          = [6]
  5129.      * ArrayUtils.removeAll([2, 6], 0, 1)       = []
  5130.      * ArrayUtils.removeAll([2, 6, 3], 1, 2)    = [2]
  5131.      * ArrayUtils.removeAll([2, 6, 3], 0, 2)    = [6]
  5132.      * ArrayUtils.removeAll([2, 6, 3], 0, 1, 2) = []
  5133.      * </pre>
  5134.      *
  5135.      * @param array   the array to remove the element from, may not be {@code null}
  5136.      * @param indices the positions of the elements to be removed
  5137.      * @return A new array containing the existing elements except those
  5138.      *         at the specified positions.
  5139.      * @throws IndexOutOfBoundsException if any index is out of range
  5140.      * (index &lt; 0 || index &gt;= array.length), or if the array is {@code null}.
  5141.      * @since 3.0.1
  5142.      */
  5143.     public static float[] removeAll(final float[] array, final int... indices) {
  5144.         return (float[]) removeAll((Object) array, indices);
  5145.     }

  5147.     /**
  5148.      * Removes the elements at the specified positions from the specified array.
  5149.      * All remaining elements are shifted to the left.
  5150.      * <p>
  5151.      * This method returns a new array with the same elements of the input
  5152.      * array except those at the specified positions. The component
  5153.      * type of the returned array is always the same as that of the input
  5154.      * array.
  5155.      * </p>
  5156.      * <p>
  5157.      * If the input array is {@code null}, an IndexOutOfBoundsException
  5158.      * will be thrown, because in that case no valid index can be specified.
  5159.      * </p>
  5160.      * <pre>
  5161.      * ArrayUtils.removeAll([1], 0)             = []
  5162.      * ArrayUtils.removeAll([2, 6], 0)          = [6]
  5163.      * ArrayUtils.removeAll([2, 6], 0, 1)       = []
  5164.      * ArrayUtils.removeAll([2, 6, 3], 1, 2)    = [2]
  5165.      * ArrayUtils.removeAll([2, 6, 3], 0, 2)    = [6]
  5166.      * ArrayUtils.removeAll([2, 6, 3], 0, 1, 2) = []
  5167.      * </pre>
  5168.      *
  5169.      * @param array   the array to remove the element from, may not be {@code null}
  5170.      * @param indices the positions of the elements to be removed
  5171.      * @return A new array containing the existing elements except those
  5172.      *         at the specified positions.
  5173.      * @throws IndexOutOfBoundsException if any index is out of range
  5174.      * (index &lt; 0 || index &gt;= array.length), or if the array is {@code null}.
  5175.      * @since 3.0.1
  5176.      */
  5177.     public static int[] removeAll(final int[] array, final int... indices) {
  5178.         return (int[]) removeAll((Object) array, indices);
  5179.     }

  5181.     /**
  5182.      * Removes the elements at the specified positions from the specified array.
  5183.      * All remaining elements are shifted to the left.
  5184.      * <p>
  5185.      * This method returns a new array with the same elements of the input
  5186.      * array except those at the specified positions. The component
  5187.      * type of the returned array is always the same as that of the input
  5188.      * array.
  5189.      * </p>
  5190.      * <p>
  5191.      * If the input array is {@code null}, an IndexOutOfBoundsException
  5192.      * will be thrown, because in that case no valid index can be specified.
  5193.      * </p>
  5194.      * <pre>
  5195.      * ArrayUtils.removeAll([1], 0)             = []
  5196.      * ArrayUtils.removeAll([2, 6], 0)          = [6]
  5197.      * ArrayUtils.removeAll([2, 6], 0, 1)       = []
  5198.      * ArrayUtils.removeAll([2, 6, 3], 1, 2)    = [2]
  5199.      * ArrayUtils.removeAll([2, 6, 3], 0, 2)    = [6]
  5200.      * ArrayUtils.removeAll([2, 6, 3], 0, 1, 2) = []
  5201.      * </pre>
  5202.      *
  5203.      * @param array   the array to remove the element from, may not be {@code null}
  5204.      * @param indices the positions of the elements to be removed
  5205.      * @return A new array containing the existing elements except those
  5206.      *         at the specified positions.
  5207.      * @throws IndexOutOfBoundsException if any index is out of range
  5208.      * (index &lt; 0 || index &gt;= array.length), or if the array is {@code null}.
  5209.      * @since 3.0.1
  5210.      */
  5211.     public static long[] removeAll(final long[] array, final int... indices) {
  5212.         return (long[]) removeAll((Object) array, indices);
  5213.     }

  5215.     /**
  5216.      * Removes multiple array elements specified by indices.
  5217.      *
  5218.      * @param array source
  5219.      * @param indices to remove
  5220.      * @return new array of same type minus elements specified by the set bits in {@code indices}
  5221.      * @since 3.2
  5222.      */
  5223.     // package protected for access by unit tests
  5224.     static Object removeAll(final Object array, final BitSet indices) {
  5225.         if (array == null) {
  5226.             return null;
  5227.         }
  5228.         final int srcLength = getLength(array);
  5229.         // No need to check maxIndex here, because method only currently called from removeElements()
  5230.         // which guarantee to generate only valid bit entries.
  5231. //        final int maxIndex = indices.length();
  5232. //        if (maxIndex > srcLength) {
  5233. //            throw new IndexOutOfBoundsException("Index: " + (maxIndex-1) + ", Length: " + srcLength);
  5234. //        }
  5235.         final int removals = indices.cardinality(); // true bits are items to remove
  5236.         final Object result = Array.newInstance(array.getClass().getComponentType(), srcLength - removals);
  5237.         int srcIndex = 0;
  5238.         int destIndex = 0;
  5239.         int count;
  5240.         int set;
  5241.         while ((set = indices.nextSetBit(srcIndex)) != -1) {
  5242.             count = set - srcIndex;
  5243.             if (count > 0) {
  5244.                 System.arraycopy(array, srcIndex, result, destIndex, count);
  5245.                 destIndex += count;
  5246.             }
  5247.             srcIndex = indices.nextClearBit(set);
  5248.         }
  5249.         count = srcLength - srcIndex;
  5250.         if (count > 0) {
  5251.             System.arraycopy(array, srcIndex, result, destIndex, count);
  5252.         }
  5253.         return result;
  5254.     }

  5256.     /**
  5257.      * Removes multiple array elements specified by index.
  5258.      *
  5259.      * @param array source
  5260.      * @param indices to remove
  5261.      * @return new array of same type minus elements specified by unique values of {@code indices}
  5262.      */
  5263.     // package protected for access by unit tests
  5264.     static Object removeAll(final Object array, final int... indices) {
  5265.         if (array == null) {
  5266.             return null;
  5267.         }
  5268.         final int length = getLength(array);
  5269.         int diff = 0; // number of distinct indexes, i.e. number of entries that will be removed
  5270.         final int[] clonedIndices = ArraySorter.sort(clone(indices));
  5271.         // identify length of result array
  5272.         if (isNotEmpty(clonedIndices)) {
  5273.             int i = clonedIndices.length;
  5274.             int prevIndex = length;
  5275.             while (--i >= 0) {
  5276.                 final int index = clonedIndices[i];
  5277.                 if (index < 0 || index >= length) {
  5278.                     throw new IndexOutOfBoundsException("Index: " + index + ", Length: " + length);
  5279.                 }
  5280.                 if (index >= prevIndex) {
  5281.                     continue;
  5282.                 }
  5283.                 diff++;
  5284.                 prevIndex = index;
  5285.             }
  5286.         }
  5287.         // create result array
  5288.         final Object result = Array.newInstance(array.getClass().getComponentType(), length - diff);
  5289.         if (diff < length && clonedIndices != null) {
  5290.             int end = length; // index just after last copy
  5291.             int dest = length - diff; // number of entries so far not copied
  5292.             for (int i = clonedIndices.length - 1; i >= 0; i--) {
  5293.                 final int index = clonedIndices[i];
  5294.                 if (end - index > 1) { // same as (cp > 0)
  5295.                     final int cp = end - index - 1;
  5296.                     dest -= cp;
  5297.                     System.arraycopy(array, index + 1, result, dest, cp);
  5298.                     // After this copy, we still have room for dest items.
  5299.                 }
  5300.                 end = index;
  5301.             }
  5302.             if (end > 0) {
  5303.                 System.arraycopy(array, 0, result, 0, end);
  5304.             }
  5305.         }
  5306.         return result;
  5307.     }

  5309.     /**
  5310.      * Removes the elements at the specified positions from the specified array.
  5311.      * All remaining elements are shifted to the left.
  5312.      * <p>
  5313.      * This method returns a new array with the same elements of the input
  5314.      * array except those at the specified positions. The component
  5315.      * type of the returned array is always the same as that of the input
  5316.      * array.
  5317.      * </p>
  5318.      * <p>
  5319.      * If the input array is {@code null}, an IndexOutOfBoundsException
  5320.      * will be thrown, because in that case no valid index can be specified.
  5321.      * </p>
  5322.      * <pre>
  5323.      * ArrayUtils.removeAll([1], 0)             = []
  5324.      * ArrayUtils.removeAll([2, 6], 0)          = [6]
  5325.      * ArrayUtils.removeAll([2, 6], 0, 1)       = []
  5326.      * ArrayUtils.removeAll([2, 6, 3], 1, 2)    = [2]
  5327.      * ArrayUtils.removeAll([2, 6, 3], 0, 2)    = [6]
  5328.      * ArrayUtils.removeAll([2, 6, 3], 0, 1, 2) = []
  5329.      * </pre>
  5330.      *
  5331.      * @param array   the array to remove the element from, may not be {@code null}
  5332.      * @param indices the positions of the elements to be removed
  5333.      * @return A new array containing the existing elements except those
  5334.      *         at the specified positions.
  5335.      * @throws IndexOutOfBoundsException if any index is out of range
  5336.      * (index &lt; 0 || index &gt;= array.length), or if the array is {@code null}.
  5337.      * @since 3.0.1
  5338.      */
  5339.     public static short[] removeAll(final short[] array, final int... indices) {
  5340.         return (short[]) removeAll((Object) array, indices);
  5341.     }

  5343.     /**
  5344.      * Removes the elements at the specified positions from the specified array.
  5345.      * All remaining elements are shifted to the left.
  5346.      * <p>
  5347.      * This method returns a new array with the same elements of the input
  5348.      * array except those at the specified positions. The component
  5349.      * type of the returned array is always the same as that of the input
  5350.      * array.
  5351.      * </p>
  5352.      * <p>
  5353.      * If the input array is {@code null}, an IndexOutOfBoundsException
  5354.      * will be thrown, because in that case no valid index can be specified.
  5355.      * </p>
  5356.      * <pre>
  5357.      * ArrayUtils.removeAll(["a", "b", "c"], 0, 2) = ["b"]
  5358.      * ArrayUtils.removeAll(["a", "b", "c"], 1, 2) = ["a"]
  5359.      * </pre>
  5360.      *
  5361.      * @param <T> the component type of the array
  5362.      * @param array   the array to remove the element from, may not be {@code null}
  5363.      * @param indices the positions of the elements to be removed
  5364.      * @return A new array containing the existing elements except those
  5365.      *         at the specified positions.
  5366.      * @throws IndexOutOfBoundsException if any index is out of range
  5367.      * (index &lt; 0 || index &gt;= array.length), or if the array is {@code null}.
  5368.      * @since 3.0.1
  5369.      */
  5370.     @SuppressWarnings("unchecked") // removeAll() always creates an array of the same type as its input
  5371.     public static <T> T[] removeAll(final T[] array, final int... indices) {
  5372.         return (T[]) removeAll((Object) array, indices);
  5373.     }

  5375.     /**
  5376.      * Removes the occurrences of the specified element from the specified boolean array.
  5377.      * <p>
  5378.      * All subsequent elements are shifted to the left (subtracts one from their indices).
  5379.      * If the array doesn't contain such an element, no elements are removed from the array.
  5380.      * {@code null} will be returned if the input array is {@code null}.
  5381.      * </p>
  5382.      *
  5383.      * @param element the element to remove
  5384.      * @param array the input array
  5385.      *
  5386.      * @return A new array containing the existing elements except the occurrences of the specified element.
  5387.      * @since 3.5
  5388.      * @deprecated Use {@link #removeAllOccurrences(boolean[], boolean)}
  5389.      */
  5390.     @Deprecated
  5391.     public static boolean[] removeAllOccurences(final boolean[] array, final boolean element) {
  5392.         return (boolean[]) removeAll((Object) array, indexesOf(array, element));
  5393.     }

  5395.     /**
  5396.      * Removes the occurrences of the specified element from the specified byte array.
  5397.      * <p>
  5398.      * All subsequent elements are shifted to the left (subtracts one from their indices).
  5399.      * If the array doesn't contain such an element, no elements are removed from the array.
  5400.      * {@code null} will be returned if the input array is {@code null}.
  5401.      * </p>
  5402.      *
  5403.      * @param element the element to remove
  5404.      * @param array the input array
  5405.      *
  5406.      * @return A new array containing the existing elements except the occurrences of the specified element.
  5407.      * @since 3.5
  5408.      * @deprecated Use {@link #removeAllOccurrences(byte[], byte)}
  5409.      */
  5410.     @Deprecated
  5411.     public static byte[] removeAllOccurences(final byte[] array, final byte element) {
  5412.         return (byte[]) removeAll((Object) array, indexesOf(array, element));
  5413.     }

  5415.     /**
  5416.      * Removes the occurrences of the specified element from the specified char array.
  5417.      * <p>
  5418.      * All subsequent elements are shifted to the left (subtracts one from their indices).
  5419.      * If the array doesn't contain such an element, no elements are removed from the array.
  5420.      * {@code null} will be returned if the input array is {@code null}.
  5421.      * </p>
  5422.      *
  5423.      * @param element the element to remove
  5424.      * @param array the input array
  5425.      *
  5426.      * @return A new array containing the existing elements except the occurrences of the specified element.
  5427.      * @since 3.5
  5428.      * @deprecated Use {@link #removeAllOccurrences(char[], char)}
  5429.      */
  5430.     @Deprecated
  5431.     public static char[] removeAllOccurences(final char[] array, final char element) {
  5432.         return (char[]) removeAll((Object) array, indexesOf(array, element));
  5433.     }

  5435.     /**
  5436.      * Removes the occurrences of the specified element from the specified double array.
  5437.      * <p>
  5438.      * All subsequent elements are shifted to the left (subtracts one from their indices).
  5439.      * If the array doesn't contain such an element, no elements are removed from the array.
  5440.      * {@code null} will be returned if the input array is {@code null}.
  5441.      * </p>
  5442.      *
  5443.      * @param element the element to remove
  5444.      * @param array the input array
  5445.      *
  5446.      * @return A new array containing the existing elements except the occurrences of the specified element.
  5447.      * @since 3.5
  5448.      * @deprecated Use {@link #removeAllOccurrences(double[], double)}
  5449.      */
  5450.     @Deprecated
  5451.     public static double[] removeAllOccurences(final double[] array, final double element) {
  5452.         return (double[]) removeAll((Object) array, indexesOf(array, element));
  5453.     }

  5455.     /**
  5456.      * Removes the occurrences of the specified element from the specified float array.
  5457.      * <p>
  5458.      * All subsequent elements are shifted to the left (subtracts one from their indices).
  5459.      * If the array doesn't contain such an element, no elements are removed from the array.
  5460.      * {@code null} will be returned if the input array is {@code null}.
  5461.      * </p>
  5462.      *
  5463.      * @param element the element to remove
  5464.      * @param array the input array
  5465.      *
  5466.      * @return A new array containing the existing elements except the occurrences of the specified element.
  5467.      * @since 3.5
  5468.      * @deprecated Use {@link #removeAllOccurrences(float[], float)}
  5469.      */
  5470.     @Deprecated
  5471.     public static float[] removeAllOccurences(final float[] array, final float element) {
  5472.         return (float[]) removeAll((Object) array, indexesOf(array, element));
  5473.     }

  5475.     /**
  5476.      * Removes the occurrences of the specified element from the specified int array.
  5477.      * <p>
  5478.      * All subsequent elements are shifted to the left (subtracts one from their indices).
  5479.      * If the array doesn't contain such an element, no elements are removed from the array.
  5480.      * {@code null} will be returned if the input array is {@code null}.
  5481.      * </p>
  5482.      *
  5483.      * @param element the element to remove
  5484.      * @param array the input array
  5485.      *
  5486.      * @return A new array containing the existing elements except the occurrences of the specified element.
  5487.      * @since 3.5
  5488.      * @deprecated Use {@link #removeAllOccurrences(int[], int)}
  5489.      */
  5490.     @Deprecated
  5491.     public static int[] removeAllOccurences(final int[] array, final int element) {
  5492.         return (int[]) removeAll((Object) array, indexesOf(array, element));
  5493.     }

  5495.     /**
  5496.      * Removes the occurrences of the specified element from the specified long array.
  5497.      * <p>
  5498.      * All subsequent elements are shifted to the left (subtracts one from their indices).
  5499.      * If the array doesn't contain such an element, no elements are removed from the array.
  5500.      * {@code null} will be returned if the input array is {@code null}.
  5501.      * </p>
  5502.      *
  5503.      * @param element the element to remove
  5504.      * @param array the input array
  5505.      *
  5506.      * @return A new array containing the existing elements except the occurrences of the specified element.
  5507.      * @since 3.5
  5508.      * @deprecated Use {@link #removeAllOccurrences(long[], long)}
  5509.      */
  5510.     @Deprecated
  5511.     public static long[] removeAllOccurences(final long[] array, final long element) {
  5512.         return (long[]) removeAll((Object) array, indexesOf(array, element));
  5513.     }

  5515.     /**
  5516.      * Removes the occurrences of the specified element from the specified short array.
  5517.      * <p>
  5518.      * All subsequent elements are shifted to the left (subtracts one from their indices).
  5519.      * If the array doesn't contain such an element, no elements are removed from the array.
  5520.      * {@code null} will be returned if the input array is {@code null}.
  5521.      * </p>
  5522.      *
  5523.      * @param element the element to remove
  5524.      * @param array the input array
  5525.      *
  5526.      * @return A new array containing the existing elements except the occurrences of the specified element.
  5527.      * @since 3.5
  5528.      * @deprecated Use {@link #removeAllOccurrences(short[], short)}
  5529.      */
  5530.     @Deprecated
  5531.     public static short[] removeAllOccurences(final short[] array, final short element) {
  5532.         return (short[]) removeAll((Object) array, indexesOf(array, element));
  5533.     }

  5535.     /**
  5536.      * Removes the occurrences of the specified element from the specified array.
  5537.      * <p>
  5538.      * All subsequent elements are shifted to the left (subtracts one from their indices).
  5539.      * If the array doesn't contain such an element, no elements are removed from the array.
  5540.      * {@code null} will be returned if the input array is {@code null}.
  5541.      * </p>
  5542.      *
  5543.      * @param <T> the type of object in the array
  5544.      * @param element the element to remove
  5545.      * @param array the input array
  5546.      *
  5547.      * @return A new array containing the existing elements except the occurrences of the specified element.
  5548.      * @since 3.5
  5549.      * @deprecated Use {@link #removeAllOccurrences(Object[], Object)}
  5550.      */
  5551.     @Deprecated
  5552.     public static <T> T[] removeAllOccurences(final T[] array, final T element) {
  5553.         return (T[]) removeAll((Object) array, indexesOf(array, element));
  5554.     }

  5556.     /**
  5557.      * Removes the occurrences of the specified element from the specified boolean array.
  5558.      * <p>
  5559.      * All subsequent elements are shifted to the left (subtracts one from their indices).
  5560.      * If the array doesn't contain such an element, no elements are removed from the array.
  5561.      * {@code null} will be returned if the input array is {@code null}.
  5562.      * </p>
  5563.      *
  5564.      * @param element the element to remove
  5565.      * @param array the input array
  5566.      *
  5567.      * @return A new array containing the existing elements except the occurrences of the specified element.
  5568.      * @since 3.10
  5569.      */
  5570.     public static boolean[] removeAllOccurrences(final boolean[] array, final boolean element) {
  5571.         return (boolean[]) removeAll((Object) array, indexesOf(array, element));
  5572.     }

  5574.     /**
  5575.      * Removes the occurrences of the specified element from the specified byte array.
  5576.      * <p>
  5577.      * All subsequent elements are shifted to the left (subtracts one from their indices).
  5578.      * If the array doesn't contain such an element, no elements are removed from the array.
  5579.      * {@code null} will be returned if the input array is {@code null}.
  5580.      * </p>
  5581.      *
  5582.      * @param element the element to remove
  5583.      * @param array the input array
  5584.      *
  5585.      * @return A new array containing the existing elements except the occurrences of the specified element.
  5586.      * @since 3.10
  5587.      */
  5588.     public static byte[] removeAllOccurrences(final byte[] array, final byte element) {
  5589.         return (byte[]) removeAll((Object) array, indexesOf(array, element));
  5590.     }

  5592.     /**
  5593.      * Removes the occurrences of the specified element from the specified char array.
  5594.      * <p>
  5595.      * All subsequent elements are shifted to the left (subtracts one from their indices).
  5596.      * If the array doesn't contain such an element, no elements are removed from the array.
  5597.      * {@code null} will be returned if the input array is {@code null}.
  5598.      * </p>
  5599.      *
  5600.      * @param element the element to remove
  5601.      * @param array the input array
  5602.      *
  5603.      * @return A new array containing the existing elements except the occurrences of the specified element.
  5604.      * @since 3.10
  5605.      */
  5606.     public static char[] removeAllOccurrences(final char[] array, final char element) {
  5607.         return (char[]) removeAll((Object) array, indexesOf(array, element));
  5608.     }

  5610.     /**
  5611.      * Removes the occurrences of the specified element from the specified double array.
  5612.      * <p>
  5613.      * All subsequent elements are shifted to the left (subtracts one from their indices).
  5614.      * If the array doesn't contain such an element, no elements are removed from the array.
  5615.      * {@code null} will be returned if the input array is {@code null}.
  5616.      * </p>
  5617.      *
  5618.      * @param element the element to remove
  5619.      * @param array the input array
  5620.      *
  5621.      * @return A new array containing the existing elements except the occurrences of the specified element.
  5622.      * @since 3.10
  5623.      */
  5624.     public static double[] removeAllOccurrences(final double[] array, final double element) {
  5625.         return (double[]) removeAll((Object) array, indexesOf(array, element));
  5626.     }

  5628.     /**
  5629.      * Removes the occurrences of the specified element from the specified float array.
  5630.      * <p>
  5631.      * All subsequent elements are shifted to the left (subtracts one from their indices).
  5632.      * If the array doesn't contain such an element, no elements are removed from the array.
  5633.      * {@code null} will be returned if the input array is {@code null}.
  5634.      * </p>
  5635.      *
  5636.      * @param element the element to remove
  5637.      * @param array the input array
  5638.      *
  5639.      * @return A new array containing the existing elements except the occurrences of the specified element.
  5640.      * @since 3.10
  5641.      */
  5642.     public static float[] removeAllOccurrences(final float[] array, final float element) {
  5643.         return (float[]) removeAll((Object) array, indexesOf(array, element));
  5644.     }

  5646.     /**
  5647.      * Removes the occurrences of the specified element from the specified int array.
  5648.      * <p>
  5649.      * All subsequent elements are shifted to the left (subtracts one from their indices).
  5650.      * If the array doesn't contain such an element, no elements are removed from the array.
  5651.      * {@code null} will be returned if the input array is {@code null}.
  5652.      * </p>
  5653.      *
  5654.      * @param element the element to remove
  5655.      * @param array the input array
  5656.      *
  5657.      * @return A new array containing the existing elements except the occurrences of the specified element.
  5658.      * @since 3.10
  5659.      */
  5660.     public static int[] removeAllOccurrences(final int[] array, final int element) {
  5661.         return (int[]) removeAll((Object) array, indexesOf(array, element));
  5662.     }

  5664.     /**
  5665.      * Removes the occurrences of the specified element from the specified long array.
  5666.      * <p>
  5667.      * All subsequent elements are shifted to the left (subtracts one from their indices).
  5668.      * If the array doesn't contain such an element, no elements are removed from the array.
  5669.      * {@code null} will be returned if the input array is {@code null}.
  5670.      * </p>
  5671.      *
  5672.      * @param element the element to remove
  5673.      * @param array the input array
  5674.      *
  5675.      * @return A new array containing the existing elements except the occurrences of the specified element.
  5676.      * @since 3.10
  5677.      */
  5678.     public static long[] removeAllOccurrences(final long[] array, final long element) {
  5679.         return (long[]) removeAll((Object) array, indexesOf(array, element));
  5680.     }

  5682.     /**
  5683.      * Removes the occurrences of the specified element from the specified short array.
  5684.      * <p>
  5685.      * All subsequent elements are shifted to the left (subtracts one from their indices).
  5686.      * If the array doesn't contain such an element, no elements are removed from the array.
  5687.      * {@code null} will be returned if the input array is {@code null}.
  5688.      * </p>
  5689.      *
  5690.      * @param element the element to remove
  5691.      * @param array the input array
  5692.      *
  5693.      * @return A new array containing the existing elements except the occurrences of the specified element.
  5694.      * @since 3.10
  5695.      */
  5696.     public static short[] removeAllOccurrences(final short[] array, final short element) {
  5697.         return (short[]) removeAll((Object) array, indexesOf(array, element));
  5698.     }

  5700.     /**
  5701.      * Removes the occurrences of the specified element from the specified array.
  5702.      * <p>
  5703.      * All subsequent elements are shifted to the left (subtracts one from their indices).
  5704.      * If the array doesn't contain such an element, no elements are removed from the array.
  5705.      * {@code null} will be returned if the input array is {@code null}.
  5706.      * </p>
  5707.      *
  5708.      * @param <T> the type of object in the array
  5709.      * @param element the element to remove
  5710.      * @param array the input array
  5711.      *
  5712.      * @return A new array containing the existing elements except the occurrences of the specified element.
  5713.      * @since 3.10
  5714.      */
  5715.     public static <T> T[] removeAllOccurrences(final T[] array, final T element) {
  5716.         return (T[]) removeAll((Object) array, indexesOf(array, element));
  5717.     }

  5719.     /**
  5720.      * Removes the first occurrence of the specified element from the
  5721.      * specified array. All subsequent elements are shifted to the left
  5722.      * (subtracts one from their indices). If the array doesn't contain
  5723.      * such an element, no elements are removed from the array.
  5724.      * <p>
  5725.      * This method returns a new array with the same elements of the input
  5726.      * array except the first occurrence of the specified element. The component
  5727.      * type of the returned array is always the same as that of the input
  5728.      * array.
  5729.      * </p>
  5730.      * <pre>
  5731.      * ArrayUtils.removeElement(null, true)                = null
  5732.      * ArrayUtils.removeElement([], true)                  = []
  5733.      * ArrayUtils.removeElement([true], false)             = [true]
  5734.      * ArrayUtils.removeElement([true, false], false)      = [true]
  5735.      * ArrayUtils.removeElement([true, false, true], true) = [false, true]
  5736.      * </pre>
  5737.      *
  5738.      * @param array  the array to remove the element from, may be {@code null}
  5739.      * @param element  the element to be removed
  5740.      * @return A new array containing the existing elements except the first
  5741.      *         occurrence of the specified element.
  5742.      * @since 2.1
  5743.      */
  5744.     public static boolean[] removeElement(final boolean[] array, final boolean element) {
  5745.         final int index = indexOf(array, element);
  5746.         return index == INDEX_NOT_FOUND ? clone(array) : remove(array, index);
  5747.     }

  5749.     /**
  5750.      * Removes the first occurrence of the specified element from the
  5751.      * specified array. All subsequent elements are shifted to the left
  5752.      * (subtracts one from their indices). If the array doesn't contain
  5753.      * such an element, no elements are removed from the array.
  5754.      * <p>
  5755.      * This method returns a new array with the same elements of the input
  5756.      * array except the first occurrence of the specified element. The component
  5757.      * type of the returned array is always the same as that of the input
  5758.      * array.
  5759.      * </p>
  5760.      * <pre>
  5761.      * ArrayUtils.removeElement(null, 1)        = null
  5762.      * ArrayUtils.removeElement([], 1)          = []
  5763.      * ArrayUtils.removeElement([1], 0)         = [1]
  5764.      * ArrayUtils.removeElement([1, 0], 0)      = [1]
  5765.      * ArrayUtils.removeElement([1, 0, 1], 1)   = [0, 1]
  5766.      * </pre>
  5767.      *
  5768.      * @param array  the array to remove the element from, may be {@code null}
  5769.      * @param element  the element to be removed
  5770.      * @return A new array containing the existing elements except the first
  5771.      *         occurrence of the specified element.
  5772.      * @since 2.1
  5773.      */
  5774.     public static byte[] removeElement(final byte[] array, final byte element) {
  5775.         final int index = indexOf(array, element);
  5776.         return index == INDEX_NOT_FOUND ? clone(array) : remove(array, index);
  5777.     }

  5779.     /**
  5780.      * Removes the first occurrence of the specified element from the
  5781.      * specified array. All subsequent elements are shifted to the left
  5782.      * (subtracts one from their indices). If the array doesn't contain
  5783.      * such an element, no elements are removed from the array.
  5784.      * <p>
  5785.      * This method returns a new array with the same elements of the input
  5786.      * array except the first occurrence of the specified element. The component
  5787.      * type of the returned array is always the same as that of the input
  5788.      * array.
  5789.      * </p>
  5790.      * <pre>
  5791.      * ArrayUtils.removeElement(null, 'a')            = null
  5792.      * ArrayUtils.removeElement([], 'a')              = []
  5793.      * ArrayUtils.removeElement(['a'], 'b')           = ['a']
  5794.      * ArrayUtils.removeElement(['a', 'b'], 'a')      = ['b']
  5795.      * ArrayUtils.removeElement(['a', 'b', 'a'], 'a') = ['b', 'a']
  5796.      * </pre>
  5797.      *
  5798.      * @param array  the array to remove the element from, may be {@code null}
  5799.      * @param element  the element to be removed
  5800.      * @return A new array containing the existing elements except the first
  5801.      *         occurrence of the specified element.
  5802.      * @since 2.1
  5803.      */
  5804.     public static char[] removeElement(final char[] array, final char element) {
  5805.         final int index = indexOf(array, element);
  5806.         return index == INDEX_NOT_FOUND ? clone(array) : remove(array, index);
  5807.     }

  5809.     /**
  5810.      * Removes the first occurrence of the specified element from the
  5811.      * specified array. All subsequent elements are shifted to the left
  5812.      * (subtracts one from their indices). If the array doesn't contain
  5813.      * such an element, no elements are removed from the array.
  5814.      * <p>
  5815.      * This method returns a new array with the same elements of the input
  5816.      * array except the first occurrence of the specified element. The component
  5817.      * type of the returned array is always the same as that of the input
  5818.      * array.
  5819.      * </p>
  5820.      * <pre>
  5821.      * ArrayUtils.removeElement(null, 1.1)            = null
  5822.      * ArrayUtils.removeElement([], 1.1)              = []
  5823.      * ArrayUtils.removeElement([1.1], 1.2)           = [1.1]
  5824.      * ArrayUtils.removeElement([1.1, 2.3], 1.1)      = [2.3]
  5825.      * ArrayUtils.removeElement([1.1, 2.3, 1.1], 1.1) = [2.3, 1.1]
  5826.      * </pre>
  5827.      *
  5828.      * @param array  the array to remove the element from, may be {@code null}
  5829.      * @param element  the element to be removed
  5830.      * @return A new array containing the existing elements except the first
  5831.      *         occurrence of the specified element.
  5832.      * @since 2.1
  5833.      */
  5834.     public static double[] removeElement(final double[] array, final double element) {
  5835.         final int index = indexOf(array, element);
  5836.         return index == INDEX_NOT_FOUND ? clone(array) : remove(array, index);
  5837.     }

  5839.     /**
  5840.      * Removes the first occurrence of the specified element from the
  5841.      * specified array. All subsequent elements are shifted to the left
  5842.      * (subtracts one from their indices). If the array doesn't contain
  5843.      * such an element, no elements are removed from the array.
  5844.      * <p>
  5845.      * This method returns a new array with the same elements of the input
  5846.      * array except the first occurrence of the specified element. The component
  5847.      * type of the returned array is always the same as that of the input
  5848.      * array.
  5849.      * </p>
  5850.      * <pre>
  5851.      * ArrayUtils.removeElement(null, 1.1)            = null
  5852.      * ArrayUtils.removeElement([], 1.1)              = []
  5853.      * ArrayUtils.removeElement([1.1], 1.2)           = [1.1]
  5854.      * ArrayUtils.removeElement([1.1, 2.3], 1.1)      = [2.3]
  5855.      * ArrayUtils.removeElement([1.1, 2.3, 1.1], 1.1) = [2.3, 1.1]
  5856.      * </pre>
  5857.      *
  5858.      * @param array  the array to remove the element from, may be {@code null}
  5859.      * @param element  the element to be removed
  5860.      * @return A new array containing the existing elements except the first
  5861.      *         occurrence of the specified element.
  5862.      * @since 2.1
  5863.      */
  5864.     public static float[] removeElement(final float[] array, final float element) {
  5865.         final int index = indexOf(array, element);
  5866.         return index == INDEX_NOT_FOUND ? clone(array) : remove(array, index);
  5867.     }

  5869.     /**
  5870.      * Removes the first occurrence of the specified element from the
  5871.      * specified array. All subsequent elements are shifted to the left
  5872.      * (subtracts one from their indices). If the array doesn't contain
  5873.      * such an element, no elements are removed from the array.
  5874.      * <p>
  5875.      * This method returns a new array with the same elements of the input
  5876.      * array except the first occurrence of the specified element. The component
  5877.      * type of the returned array is always the same as that of the input
  5878.      * array.
  5879.      * </p>
  5880.      * <pre>
  5881.      * ArrayUtils.removeElement(null, 1)      = null
  5882.      * ArrayUtils.removeElement([], 1)        = []
  5883.      * ArrayUtils.removeElement([1], 2)       = [1]
  5884.      * ArrayUtils.removeElement([1, 3], 1)    = [3]
  5885.      * ArrayUtils.removeElement([1, 3, 1], 1) = [3, 1]
  5886.      * </pre>
  5887.      *
  5888.      * @param array  the array to remove the element from, may be {@code null}
  5889.      * @param element  the element to be removed
  5890.      * @return A new array containing the existing elements except the first
  5891.      *         occurrence of the specified element.
  5892.      * @since 2.1
  5893.      */
  5894.     public static int[] removeElement(final int[] array, final int element) {
  5895.         final int index = indexOf(array, element);
  5896.         return index == INDEX_NOT_FOUND ? clone(array) : remove(array, index);
  5897.     }

  5899.     /**
  5900.      * Removes the first occurrence of the specified element from the
  5901.      * specified array. All subsequent elements are shifted to the left
  5902.      * (subtracts one from their indices). If the array doesn't contain
  5903.      * such an element, no elements are removed from the array.
  5904.      * <p>
  5905.      * This method returns a new array with the same elements of the input
  5906.      * array except the first occurrence of the specified element. The component
  5907.      * type of the returned array is always the same as that of the input
  5908.      * array.
  5909.      * </p>
  5910.      * <pre>
  5911.      * ArrayUtils.removeElement(null, 1)      = null
  5912.      * ArrayUtils.removeElement([], 1)        = []
  5913.      * ArrayUtils.removeElement([1], 2)       = [1]
  5914.      * ArrayUtils.removeElement([1, 3], 1)    = [3]
  5915.      * ArrayUtils.removeElement([1, 3, 1], 1) = [3, 1]
  5916.      * </pre>
  5917.      *
  5918.      * @param array  the array to remove the element from, may be {@code null}
  5919.      * @param element  the element to be removed
  5920.      * @return A new array containing the existing elements except the first
  5921.      *         occurrence of the specified element.
  5922.      * @since 2.1
  5923.      */
  5924.     public static long[] removeElement(final long[] array, final long element) {
  5925.         final int index = indexOf(array, element);
  5926.         return index == INDEX_NOT_FOUND ? clone(array) : remove(array, index);
  5927.     }

  5929.     /**
  5930.      * Removes the first occurrence of the specified element from the
  5931.      * specified array. All subsequent elements are shifted to the left
  5932.      * (subtracts one from their indices). If the array doesn't contain
  5933.      * such an element, no elements are removed from the array.
  5934.      * <p>
  5935.      * This method returns a new array with the same elements of the input
  5936.      * array except the first occurrence of the specified element. The component
  5937.      * type of the returned array is always the same as that of the input
  5938.      * array.
  5939.      * </p>
  5940.      * <pre>
  5941.      * ArrayUtils.removeElement(null, 1)      = null
  5942.      * ArrayUtils.removeElement([], 1)        = []
  5943.      * ArrayUtils.removeElement([1], 2)       = [1]
  5944.      * ArrayUtils.removeElement([1, 3], 1)    = [3]
  5945.      * ArrayUtils.removeElement([1, 3, 1], 1) = [3, 1]
  5946.      * </pre>
  5947.      *
  5948.      * @param array  the array to remove the element from, may be {@code null}
  5949.      * @param element  the element to be removed
  5950.      * @return A new array containing the existing elements except the first
  5951.      *         occurrence of the specified element.
  5952.      * @since 2.1
  5953.      */
  5954.     public static short[] removeElement(final short[] array, final short element) {
  5955.         final int index = indexOf(array, element);
  5956.         return index == INDEX_NOT_FOUND ? clone(array) : remove(array, index);
  5957.     }

  5959.     /**
  5960.      * Removes the first occurrence of the specified element from the
  5961.      * specified array. All subsequent elements are shifted to the left
  5962.      * (subtracts one from their indices). If the array doesn't contain
  5963.      * such an element, no elements are removed from the array.
  5964.      * <p>
  5965.      * This method returns a new array with the same elements of the input
  5966.      * array except the first occurrence of the specified element. The component
  5967.      * type of the returned array is always the same as that of the input
  5968.      * array.
  5969.      * </p>
  5970.      * <pre>
  5971.      * ArrayUtils.removeElement(null, "a")            = null
  5972.      * ArrayUtils.removeElement([], "a")              = []
  5973.      * ArrayUtils.removeElement(["a"], "b")           = ["a"]
  5974.      * ArrayUtils.removeElement(["a", "b"], "a")      = ["b"]
  5975.      * ArrayUtils.removeElement(["a", "b", "a"], "a") = ["b", "a"]
  5976.      * </pre>
  5977.      *
  5978.      * @param <T> the component type of the array
  5979.      * @param array  the array to remove the element from, may be {@code null}
  5980.      * @param element  the element to be removed
  5981.      * @return A new array containing the existing elements except the first
  5982.      *         occurrence of the specified element.
  5983.      * @since 2.1
  5984.      */
  5985.     public static <T> T[] removeElement(final T[] array, final Object element) {
  5986.         final int index = indexOf(array, element);
  5987.         return index == INDEX_NOT_FOUND ? clone(array) : remove(array, index);
  5988.     }

  5990.     /**
  5991.      * Removes occurrences of specified elements, in specified quantities,
  5992.      * from the specified array. All subsequent elements are shifted left.
  5993.      * For any element-to-be-removed specified in greater quantities than
  5994.      * contained in the original array, no change occurs beyond the
  5995.      * removal of the existing matching items.
  5996.      * <p>
  5997.      * This method returns a new array with the same elements of the input
  5998.      * array except for the earliest-encountered occurrences of the specified
  5999.      * elements. The component type of the returned array is always the same
  6000.      * as that of the input array.
  6001.      * </p>
  6002.      * <pre>
  6003.      * ArrayUtils.removeElements(null, true, false)               = null
  6004.      * ArrayUtils.removeElements([], true, false)                 = []
  6005.      * ArrayUtils.removeElements([true], false, false)            = [true]
  6006.      * ArrayUtils.removeElements([true, false], true, true)       = [false]
  6007.      * ArrayUtils.removeElements([true, false, true], true)       = [false, true]
  6008.      * ArrayUtils.removeElements([true, false, true], true, true) = [false]
  6009.      * </pre>
  6010.      *
  6011.      * @param array  the array to remove the element from, may be {@code null}
  6012.      * @param values the elements to be removed
  6013.      * @return A new array containing the existing elements except the
  6014.      *         earliest-encountered occurrences of the specified elements.
  6015.      * @since 3.0.1
  6016.      */
  6017.     public static boolean[] removeElements(final boolean[] array, final boolean... values) {
  6018.         if (isEmpty(array) || isEmpty(values)) {
  6019.             return clone(array);
  6020.         }
  6021.         final HashMap<Boolean, MutableInt> occurrences = new HashMap<>(2); // only two possible values here
  6022.         for (final boolean v : values) {
  6023.             final Boolean boxed = Boolean.valueOf(v);
  6024.             final MutableInt count = occurrences.get(boxed);
  6025.             if (count == null) {
  6026.                 occurrences.put(boxed, new MutableInt(1));
  6027.             } else {
  6028.                 count.increment();
  6029.             }
  6030.         }
  6031.         final BitSet toRemove = new BitSet();
  6032.         for (int i = 0; i < array.length; i++) {
  6033.             final boolean key = array[i];
  6034.             final MutableInt count = occurrences.get(key);
  6035.             if (count != null) {
  6036.                 if (count.decrementAndGet() == 0) {
  6037.                     occurrences.remove(key);
  6038.                 }
  6039.                 toRemove.set(i);
  6040.             }
  6041.         }
  6042.         return (boolean[]) removeAll(array, toRemove);
  6043.     }

  6045.     /**
  6046.      * Removes occurrences of specified elements, in specified quantities,
  6047.      * from the specified array. All subsequent elements are shifted left.
  6048.      * For any element-to-be-removed specified in greater quantities than
  6049.      * contained in the original array, no change occurs beyond the
  6050.      * removal of the existing matching items.
  6051.      * <p>
  6052.      * This method returns a new array with the same elements of the input
  6053.      * array except for the earliest-encountered occurrences of the specified
  6054.      * elements. The component type of the returned array is always the same
  6055.      * as that of the input array.
  6056.      * </p>
  6057.      * <pre>
  6058.      * ArrayUtils.removeElements(null, 1, 2)      = null
  6059.      * ArrayUtils.removeElements([], 1, 2)        = []
  6060.      * ArrayUtils.removeElements([1], 2, 3)       = [1]
  6061.      * ArrayUtils.removeElements([1, 3], 1, 2)    = [3]
  6062.      * ArrayUtils.removeElements([1, 3, 1], 1)    = [3, 1]
  6063.      * ArrayUtils.removeElements([1, 3, 1], 1, 1) = [3]
  6064.      * </pre>
  6065.      *
  6066.      * @param array  the array to remove the element from, may be {@code null}
  6067.      * @param values the elements to be removed
  6068.      * @return A new array containing the existing elements except the
  6069.      *         earliest-encountered occurrences of the specified elements.
  6070.      * @since 3.0.1
  6071.      */
  6072.     public static byte[] removeElements(final byte[] array, final byte... values) {
  6073.         if (isEmpty(array) || isEmpty(values)) {
  6074.             return clone(array);
  6075.         }
  6076.         final Map<Byte, MutableInt> occurrences = new HashMap<>(values.length);
  6077.         for (final byte v : values) {
  6078.             final Byte boxed = Byte.valueOf(v);
  6079.             final MutableInt count = occurrences.get(boxed);
  6080.             if (count == null) {
  6081.                 occurrences.put(boxed, new MutableInt(1));
  6082.             } else {
  6083.                 count.increment();
  6084.             }
  6085.         }
  6086.         final BitSet toRemove = new BitSet();
  6087.         for (int i = 0; i < array.length; i++) {
  6088.             final byte key = array[i];
  6089.             final MutableInt count = occurrences.get(key);
  6090.             if (count != null) {
  6091.                 if (count.decrementAndGet() == 0) {
  6092.                     occurrences.remove(key);
  6093.                 }
  6094.                 toRemove.set(i);
  6095.             }
  6096.         }
  6097.         return (byte[]) removeAll(array, toRemove);
  6098.     }

  6100.     /**
  6101.      * Removes occurrences of specified elements, in specified quantities,
  6102.      * from the specified array. All subsequent elements are shifted left.
  6103.      * For any element-to-be-removed specified in greater quantities than
  6104.      * contained in the original array, no change occurs beyond the
  6105.      * removal of the existing matching items.
  6106.      * <p>
  6107.      * This method returns a new array with the same elements of the input
  6108.      * array except for the earliest-encountered occurrences of the specified
  6109.      * elements. The component type of the returned array is always the same
  6110.      * as that of the input array.
  6111.      * </p>
  6112.      * <pre>
  6113.      * ArrayUtils.removeElements(null, 1, 2)      = null
  6114.      * ArrayUtils.removeElements([], 1, 2)        = []
  6115.      * ArrayUtils.removeElements([1], 2, 3)       = [1]
  6116.      * ArrayUtils.removeElements([1, 3], 1, 2)    = [3]
  6117.      * ArrayUtils.removeElements([1, 3, 1], 1)    = [3, 1]
  6118.      * ArrayUtils.removeElements([1, 3, 1], 1, 1) = [3]
  6119.      * </pre>
  6120.      *
  6121.      * @param array  the array to remove the element from, may be {@code null}
  6122.      * @param values the elements to be removed
  6123.      * @return A new array containing the existing elements except the
  6124.      *         earliest-encountered occurrences of the specified elements.
  6125.      * @since 3.0.1
  6126.      */
  6127.     public static char[] removeElements(final char[] array, final char... values) {
  6128.         if (isEmpty(array) || isEmpty(values)) {
  6129.             return clone(array);
  6130.         }
  6131.         final HashMap<Character, MutableInt> occurrences = new HashMap<>(values.length);
  6132.         for (final char v : values) {
  6133.             final Character boxed = Character.valueOf(v);
  6134.             final MutableInt count = occurrences.get(boxed);
  6135.             if (count == null) {
  6136.                 occurrences.put(boxed, new MutableInt(1));
  6137.             } else {
  6138.                 count.increment();
  6139.             }
  6140.         }
  6141.         final BitSet toRemove = new BitSet();
  6142.         for (int i = 0; i < array.length; i++) {
  6143.             final char key = array[i];
  6144.             final MutableInt count = occurrences.get(key);
  6145.             if (count != null) {
  6146.                 if (count.decrementAndGet() == 0) {
  6147.                     occurrences.remove(key);
  6148.                 }
  6149.                 toRemove.set(i);
  6150.             }
  6151.         }
  6152.         return (char[]) removeAll(array, toRemove);
  6153.     }

  6155.     /**
  6156.      * Removes occurrences of specified elements, in specified quantities,
  6157.      * from the specified array. All subsequent elements are shifted left.
  6158.      * For any element-to-be-removed specified in greater quantities than
  6159.      * contained in the original array, no change occurs beyond the
  6160.      * removal of the existing matching items.
  6161.      * <p>
  6162.      * This method returns a new array with the same elements of the input
  6163.      * array except for the earliest-encountered occurrences of the specified
  6164.      * elements. The component type of the returned array is always the same
  6165.      * as that of the input array.
  6166.      * </p>
  6167.      * <pre>
  6168.      * ArrayUtils.removeElements(null, 1, 2)      = null
  6169.      * ArrayUtils.removeElements([], 1, 2)        = []
  6170.      * ArrayUtils.removeElements([1], 2, 3)       = [1]
  6171.      * ArrayUtils.removeElements([1, 3], 1, 2)    = [3]
  6172.      * ArrayUtils.removeElements([1, 3, 1], 1)    = [3, 1]
  6173.      * ArrayUtils.removeElements([1, 3, 1], 1, 1) = [3]
  6174.      * </pre>
  6175.      *
  6176.      * @param array  the array to remove the element from, may be {@code null}
  6177.      * @param values the elements to be removed
  6178.      * @return A new array containing the existing elements except the
  6179.      *         earliest-encountered occurrences of the specified elements.
  6180.      * @since 3.0.1
  6181.      */
  6182.     public static double[] removeElements(final double[] array, final double... values) {
  6183.         if (isEmpty(array) || isEmpty(values)) {
  6184.             return clone(array);
  6185.         }
  6186.         final HashMap<Double, MutableInt> occurrences = new HashMap<>(values.length);
  6187.         for (final double v : values) {
  6188.             final Double boxed = Double.valueOf(v);
  6189.             final MutableInt count = occurrences.get(boxed);
  6190.             if (count == null) {
  6191.                 occurrences.put(boxed, new MutableInt(1));
  6192.             } else {
  6193.                 count.increment();
  6194.             }
  6195.         }
  6196.         final BitSet toRemove = new BitSet();
  6197.         for (int i = 0; i < array.length; i++) {
  6198.             final double key = array[i];
  6199.             final MutableInt count = occurrences.get(key);
  6200.             if (count != null) {
  6201.                 if (count.decrementAndGet() == 0) {
  6202.                     occurrences.remove(key);
  6203.                 }
  6204.                 toRemove.set(i);
  6205.             }
  6206.         }
  6207.         return (double[]) removeAll(array, toRemove);
  6208.     }

  6210.     /**
  6211.      * Removes occurrences of specified elements, in specified quantities,
  6212.      * from the specified array. All subsequent elements are shifted left.
  6213.      * For any element-to-be-removed specified in greater quantities than
  6214.      * contained in the original array, no change occurs beyond the
  6215.      * removal of the existing matching items.
  6216.      * <p>
  6217.      * This method returns a new array with the same elements of the input
  6218.      * array except for the earliest-encountered occurrences of the specified
  6219.      * elements. The component type of the returned array is always the same
  6220.      * as that of the input array.
  6221.      * </p>
  6222.      * <pre>
  6223.      * ArrayUtils.removeElements(null, 1, 2)      = null
  6224.      * ArrayUtils.removeElements([], 1, 2)        = []
  6225.      * ArrayUtils.removeElements([1], 2, 3)       = [1]
  6226.      * ArrayUtils.removeElements([1, 3], 1, 2)    = [3]
  6227.      * ArrayUtils.removeElements([1, 3, 1], 1)    = [3, 1]
  6228.      * ArrayUtils.removeElements([1, 3, 1], 1, 1) = [3]
  6229.      * </pre>
  6230.      *
  6231.      * @param array  the array to remove the element from, may be {@code null}
  6232.      * @param values the elements to be removed
  6233.      * @return A new array containing the existing elements except the
  6234.      *         earliest-encountered occurrences of the specified elements.
  6235.      * @since 3.0.1
  6236.      */
  6237.     public static float[] removeElements(final float[] array, final float... values) {
  6238.         if (isEmpty(array) || isEmpty(values)) {
  6239.             return clone(array);
  6240.         }
  6241.         final HashMap<Float, MutableInt> occurrences = new HashMap<>(values.length);
  6242.         for (final float v : values) {
  6243.             final Float boxed = Float.valueOf(v);
  6244.             final MutableInt count = occurrences.get(boxed);
  6245.             if (count == null) {
  6246.                 occurrences.put(boxed, new MutableInt(1));
  6247.             } else {
  6248.                 count.increment();
  6249.             }
  6250.         }
  6251.         final BitSet toRemove = new BitSet();
  6252.         for (int i = 0; i < array.length; i++) {
  6253.             final float key = array[i];
  6254.             final MutableInt count = occurrences.get(key);
  6255.             if (count != null) {
  6256.                 if (count.decrementAndGet() == 0) {
  6257.                     occurrences.remove(key);
  6258.                 }
  6259.                 toRemove.set(i);
  6260.             }
  6261.         }
  6262.         return (float[]) removeAll(array, toRemove);
  6263.     }

  6265.     /**
  6266.      * Removes occurrences of specified elements, in specified quantities,
  6267.      * from the specified array. All subsequent elements are shifted left.
  6268.      * For any element-to-be-removed specified in greater quantities than
  6269.      * contained in the original array, no change occurs beyond the
  6270.      * removal of the existing matching items.
  6271.      * <p>
  6272.      * This method returns a new array with the same elements of the input
  6273.      * array except for the earliest-encountered occurrences of the specified
  6274.      * elements. The component type of the returned array is always the same
  6275.      * as that of the input array.
  6276.      * </p>
  6277.      * <pre>
  6278.      * ArrayUtils.removeElements(null, 1, 2)      = null
  6279.      * ArrayUtils.removeElements([], 1, 2)        = []
  6280.      * ArrayUtils.removeElements([1], 2, 3)       = [1]
  6281.      * ArrayUtils.removeElements([1, 3], 1, 2)    = [3]
  6282.      * ArrayUtils.removeElements([1, 3, 1], 1)    = [3, 1]
  6283.      * ArrayUtils.removeElements([1, 3, 1], 1, 1) = [3]
  6284.      * </pre>
  6285.      *
  6286.      * @param array  the array to remove the element from, may be {@code null}
  6287.      * @param values the elements to be removed
  6288.      * @return A new array containing the existing elements except the
  6289.      *         earliest-encountered occurrences of the specified elements.
  6290.      * @since 3.0.1
  6291.      */
  6292.     public static int[] removeElements(final int[] array, final int... values) {
  6293.         if (isEmpty(array) || isEmpty(values)) {
  6294.             return clone(array);
  6295.         }
  6296.         final HashMap<Integer, MutableInt> occurrences = new HashMap<>(values.length);
  6297.         for (final int v : values) {
  6298.             final Integer boxed = Integer.valueOf(v);
  6299.             final MutableInt count = occurrences.get(boxed);
  6300.             if (count == null) {
  6301.                 occurrences.put(boxed, new MutableInt(1));
  6302.             } else {
  6303.                 count.increment();
  6304.             }
  6305.         }
  6306.         final BitSet toRemove = new BitSet();
  6307.         for (int i = 0; i < array.length; i++) {
  6308.             final int key = array[i];
  6309.             final MutableInt count = occurrences.get(key);
  6310.             if (count != null) {
  6311.                 if (count.decrementAndGet() == 0) {
  6312.                     occurrences.remove(key);
  6313.                 }
  6314.                 toRemove.set(i);
  6315.             }
  6316.         }
  6317.         return (int[]) removeAll(array, toRemove);
  6318.     }

  6320.     /**
  6321.      * Removes occurrences of specified elements, in specified quantities,
  6322.      * from the specified array. All subsequent elements are shifted left.
  6323.      * For any element-to-be-removed specified in greater quantities than
  6324.      * contained in the original array, no change occurs beyond the
  6325.      * removal of the existing matching items.
  6326.      * <p>
  6327.      * This method returns a new array with the same elements of the input
  6328.      * array except for the earliest-encountered occurrences of the specified
  6329.      * elements. The component type of the returned array is always the same
  6330.      * as that of the input array.
  6331.      * </p>
  6332.      * <pre>
  6333.      * ArrayUtils.removeElements(null, 1, 2)      = null
  6334.      * ArrayUtils.removeElements([], 1, 2)        = []
  6335.      * ArrayUtils.removeElements([1], 2, 3)       = [1]
  6336.      * ArrayUtils.removeElements([1, 3], 1, 2)    = [3]
  6337.      * ArrayUtils.removeElements([1, 3, 1], 1)    = [3, 1]
  6338.      * ArrayUtils.removeElements([1, 3, 1], 1, 1) = [3]
  6339.      * </pre>
  6340.      *
  6341.      * @param array  the array to remove the element from, may be {@code null}
  6342.      * @param values the elements to be removed
  6343.      * @return A new array containing the existing elements except the
  6344.      *         earliest-encountered occurrences of the specified elements.
  6345.      * @since 3.0.1
  6346.      */
  6347.     public static long[] removeElements(final long[] array, final long... values) {
  6348.         if (isEmpty(array) || isEmpty(values)) {
  6349.             return clone(array);
  6350.         }
  6351.         final HashMap<Long, MutableInt> occurrences = new HashMap<>(values.length);
  6352.         for (final long v : values) {
  6353.             final Long boxed = Long.valueOf(v);
  6354.             final MutableInt count = occurrences.get(boxed);
  6355.             if (count == null) {
  6356.                 occurrences.put(boxed, new MutableInt(1));
  6357.             } else {
  6358.                 count.increment();
  6359.             }
  6360.         }
  6361.         final BitSet toRemove = new BitSet();
  6362.         for (int i = 0; i < array.length; i++) {
  6363.             final long key = array[i];
  6364.             final MutableInt count = occurrences.get(key);
  6365.             if (count != null) {
  6366.                 if (count.decrementAndGet() == 0) {
  6367.                     occurrences.remove(key);
  6368.                 }
  6369.                 toRemove.set(i);
  6370.             }
  6371.         }
  6372.         return (long[]) removeAll(array, toRemove);
  6373.     }

  6375.     /**
  6376.      * Removes occurrences of specified elements, in specified quantities,
  6377.      * from the specified array. All subsequent elements are shifted left.
  6378.      * For any element-to-be-removed specified in greater quantities than
  6379.      * contained in the original array, no change occurs beyond the
  6380.      * removal of the existing matching items.
  6381.      * <p>
  6382.      * This method returns a new array with the same elements of the input
  6383.      * array except for the earliest-encountered occurrences of the specified
  6384.      * elements. The component type of the returned array is always the same
  6385.      * as that of the input array.
  6386.      * </p>
  6387.      * <pre>
  6388.      * ArrayUtils.removeElements(null, 1, 2)      = null
  6389.      * ArrayUtils.removeElements([], 1, 2)        = []
  6390.      * ArrayUtils.removeElements([1], 2, 3)       = [1]
  6391.      * ArrayUtils.removeElements([1, 3], 1, 2)    = [3]
  6392.      * ArrayUtils.removeElements([1, 3, 1], 1)    = [3, 1]
  6393.      * ArrayUtils.removeElements([1, 3, 1], 1, 1) = [3]
  6394.      * </pre>
  6395.      *
  6396.      * @param array  the array to remove the element from, may be {@code null}
  6397.      * @param values the elements to be removed
  6398.      * @return A new array containing the existing elements except the
  6399.      *         earliest-encountered occurrences of the specified elements.
  6400.      * @since 3.0.1
  6401.      */
  6402.     public static short[] removeElements(final short[] array, final short... values) {
  6403.         if (isEmpty(array) || isEmpty(values)) {
  6404.             return clone(array);
  6405.         }
  6406.         final HashMap<Short, MutableInt> occurrences = new HashMap<>(values.length);
  6407.         for (final short v : values) {
  6408.             final Short boxed = Short.valueOf(v);
  6409.             final MutableInt count = occurrences.get(boxed);
  6410.             if (count == null) {
  6411.                 occurrences.put(boxed, new MutableInt(1));
  6412.             } else {
  6413.                 count.increment();
  6414.             }
  6415.         }
  6416.         final BitSet toRemove = new BitSet();
  6417.         for (int i = 0; i < array.length; i++) {
  6418.             final short key = array[i];
  6419.             final MutableInt count = occurrences.get(key);
  6420.             if (count != null) {
  6421.                 if (count.decrementAndGet() == 0) {
  6422.                     occurrences.remove(key);
  6423.                 }
  6424.                 toRemove.set(i);
  6425.             }
  6426.         }
  6427.         return (short[]) removeAll(array, toRemove);
  6428.     }

  6430.     /**
  6431.      * Removes occurrences of specified elements, in specified quantities,
  6432.      * from the specified array. All subsequent elements are shifted left.
  6433.      * For any element-to-be-removed specified in greater quantities than
  6434.      * contained in the original array, no change occurs beyond the
  6435.      * removal of the existing matching items.
  6436.      * <p>
  6437.      * This method returns a new array with the same elements of the input
  6438.      * array except for the earliest-encountered occurrences of the specified
  6439.      * elements. The component type of the returned array is always the same
  6440.      * as that of the input array.
  6441.      * </p>
  6442.      * <pre>
  6443.      * ArrayUtils.removeElements(null, "a", "b")            = null
  6444.      * ArrayUtils.removeElements([], "a", "b")              = []
  6445.      * ArrayUtils.removeElements(["a"], "b", "c")           = ["a"]
  6446.      * ArrayUtils.removeElements(["a", "b"], "a", "c")      = ["b"]
  6447.      * ArrayUtils.removeElements(["a", "b", "a"], "a")      = ["b", "a"]
  6448.      * ArrayUtils.removeElements(["a", "b", "a"], "a", "a") = ["b"]
  6449.      * </pre>
  6450.      *
  6451.      * @param <T> the component type of the array
  6452.      * @param array  the array to remove the element from, may be {@code null}
  6453.      * @param values the elements to be removed
  6454.      * @return A new array containing the existing elements except the
  6455.      *         earliest-encountered occurrences of the specified elements.
  6456.      * @since 3.0.1
  6457.      */
  6458.     @SafeVarargs
  6459.     public static <T> T[] removeElements(final T[] array, final T... values) {
  6460.         if (isEmpty(array) || isEmpty(values)) {
  6461.             return clone(array);
  6462.         }
  6463.         final HashMap<T, MutableInt> occurrences = new HashMap<>(values.length);
  6464.         for (final T v : values) {
  6465.             final MutableInt count = occurrences.get(v);
  6466.             if (count == null) {
  6467.                 occurrences.put(v, new MutableInt(1));
  6468.             } else {
  6469.                 count.increment();
  6470.             }
  6471.         }
  6472.         final BitSet toRemove = new BitSet();
  6473.         for (int i = 0; i < array.length; i++) {
  6474.             final T key = array[i];
  6475.             final MutableInt count = occurrences.get(key);
  6476.             if (count != null) {
  6477.                 if (count.decrementAndGet() == 0) {
  6478.                     occurrences.remove(key);
  6479.                 }
  6480.                 toRemove.set(i);
  6481.             }
  6482.         }
  6483.         @SuppressWarnings("unchecked") // removeAll() always creates an array of the same type as its input
  6484.         final T[] result = (T[]) removeAll(array, toRemove);
  6485.         return result;
  6486.     }

  6488.     /**
  6489.      * Reverses the order of the given array.
  6490.      * <p>
  6491.      * This method does nothing for a {@code null} input array.
  6492.      * </p>
  6493.      *
  6494.      * @param array  the array to reverse, may be {@code null}
  6495.      */
  6496.     public static void reverse(final boolean[] array) {
  6497.         if (array == null) {
  6498.             return;
  6499.         }
  6500.         reverse(array, 0, array.length);
  6501.     }

  6503.     /**
  6504.      * Reverses the order of the given array in the given range.
  6505.      * <p>
  6506.      * This method does nothing for a {@code null} input array.
  6507.      * </p>
  6508.      *
  6509.      * @param array
  6510.      *            the array to reverse, may be {@code null}
  6511.      * @param startIndexInclusive
  6512.      *            the starting index. Undervalue (&lt;0) is promoted to 0, overvalue (&gt;array.length) results in no
  6513.      *            change.
  6514.      * @param endIndexExclusive
  6515.      *            elements up to endIndex-1 are reversed in the array. Undervalue (&lt; start index) results in no
  6516.      *            change. Overvalue (&gt;array.length) is demoted to array length.
  6517.      * @since 3.2
  6518.      */
  6519.     public static void reverse(final boolean[] array, final int startIndexInclusive, final int endIndexExclusive) {
  6520.         if (array == null) {
  6521.             return;
  6522.         }
  6523.         int i = Math.max(startIndexInclusive, 0);
  6524.         int j = Math.min(array.length, endIndexExclusive) - 1;
  6525.         boolean tmp;
  6526.         while (j > i) {
  6527.             tmp = array[j];
  6528.             array[j] = array[i];
  6529.             array[i] = tmp;
  6530.             j--;
  6531.             i++;
  6532.         }
  6533.     }

  6535.     /**
  6536.      * Reverses the order of the given array.
  6537.      * <p>
  6538.      * This method does nothing for a {@code null} input array.
  6539.      * </p>
  6540.      *
  6541.      * @param array  the array to reverse, may be {@code null}
  6542.      */
  6543.     public static void reverse(final byte[] array) {
  6544.         if (array != null) {
  6545.             reverse(array, 0, array.length);
  6546.         }
  6547.     }

  6549.     /**
  6550.      * Reverses the order of the given array in the given range.
  6551.      * <p>
  6552.      * This method does nothing for a {@code null} input array.
  6553.      * </p>
  6554.      *
  6555.      * @param array
  6556.      *            the array to reverse, may be {@code null}
  6557.      * @param startIndexInclusive
  6558.      *            the starting index. Undervalue (&lt;0) is promoted to 0, overvalue (&gt;array.length) results in no
  6559.      *            change.
  6560.      * @param endIndexExclusive
  6561.      *            elements up to endIndex-1 are reversed in the array. Undervalue (&lt; start index) results in no
  6562.      *            change. Overvalue (&gt;array.length) is demoted to array length.
  6563.      * @since 3.2
  6564.      */
  6565.     public static void reverse(final byte[] array, final int startIndexInclusive, final int endIndexExclusive) {
  6566.         if (array == null) {
  6567.             return;
  6568.         }
  6569.         int i = Math.max(startIndexInclusive, 0);
  6570.         int j = Math.min(array.length, endIndexExclusive) - 1;
  6571.         byte tmp;
  6572.         while (j > i) {
  6573.             tmp = array[j];
  6574.             array[j] = array[i];
  6575.             array[i] = tmp;
  6576.             j--;
  6577.             i++;
  6578.         }
  6579.     }

  6581.     /**
  6582.      * Reverses the order of the given array.
  6583.      * <p>
  6584.      * This method does nothing for a {@code null} input array.
  6585.      * </p>
  6586.      *
  6587.      * @param array  the array to reverse, may be {@code null}
  6588.      */
  6589.     public static void reverse(final char[] array) {
  6590.         if (array != null) {
  6591.             reverse(array, 0, array.length);
  6592.         }
  6593.     }

  6595.     /**
  6596.      * Reverses the order of the given array in the given range.
  6597.      * <p>
  6598.      * This method does nothing for a {@code null} input array.
  6599.      * </p>
  6600.      *
  6601.      * @param array
  6602.      *            the array to reverse, may be {@code null}
  6603.      * @param startIndexInclusive
  6604.      *            the starting index. Undervalue (&lt;0) is promoted to 0, overvalue (&gt;array.length) results in no
  6605.      *            change.
  6606.      * @param endIndexExclusive
  6607.      *            elements up to endIndex-1 are reversed in the array. Undervalue (&lt; start index) results in no
  6608.      *            change. Overvalue (&gt;array.length) is demoted to array length.
  6609.      * @since 3.2
  6610.      */
  6611.     public static void reverse(final char[] array, final int startIndexInclusive, final int endIndexExclusive) {
  6612.         if (array == null) {
  6613.             return;
  6614.         }
  6615.         int i = Math.max(startIndexInclusive, 0);
  6616.         int j = Math.min(array.length, endIndexExclusive) - 1;
  6617.         char tmp;
  6618.         while (j > i) {
  6619.             tmp = array[j];
  6620.             array[j] = array[i];
  6621.             array[i] = tmp;
  6622.             j--;
  6623.             i++;
  6624.         }
  6625.     }

  6627.     /**
  6628.      * Reverses the order of the given array.
  6629.      * <p>
  6630.      * This method does nothing for a {@code null} input array.
  6631.      * </p>
  6632.      *
  6633.      * @param array  the array to reverse, may be {@code null}
  6634.      */
  6635.     public static void reverse(final double[] array) {
  6636.         if (array != null) {
  6637.             reverse(array, 0, array.length);
  6638.         }
  6639.     }

  6641.     /**
  6642.      * Reverses the order of the given array in the given range.
  6643.      * <p>
  6644.      * This method does nothing for a {@code null} input array.
  6645.      * </p>
  6646.      *
  6647.      * @param array
  6648.      *            the array to reverse, may be {@code null}
  6649.      * @param startIndexInclusive
  6650.      *            the starting index. Undervalue (&lt;0) is promoted to 0, overvalue (&gt;array.length) results in no
  6651.      *            change.
  6652.      * @param endIndexExclusive
  6653.      *            elements up to endIndex-1 are reversed in the array. Undervalue (&lt; start index) results in no
  6654.      *            change. Overvalue (&gt;array.length) is demoted to array length.
  6655.      * @since 3.2
  6656.      */
  6657.     public static void reverse(final double[] array, final int startIndexInclusive, final int endIndexExclusive) {
  6658.         if (array == null) {
  6659.             return;
  6660.         }
  6661.         int i = Math.max(startIndexInclusive, 0);
  6662.         int j = Math.min(array.length, endIndexExclusive) - 1;
  6663.         double tmp;
  6664.         while (j > i) {
  6665.             tmp = array[j];
  6666.             array[j] = array[i];
  6667.             array[i] = tmp;
  6668.             j--;
  6669.             i++;
  6670.         }
  6671.     }

  6673.     /**
  6674.      * Reverses the order of the given array.
  6675.      * <p>
  6676.      * This method does nothing for a {@code null} input array.
  6677.      * </p>
  6678.      *
  6679.      * @param array  the array to reverse, may be {@code null}
  6680.      */
  6681.     public static void reverse(final float[] array) {
  6682.         if (array != null) {
  6683.             reverse(array, 0, array.length);
  6684.         }
  6685.     }

  6687.     /**
  6688.      * Reverses the order of the given array in the given range.
  6689.      * <p>
  6690.      * This method does nothing for a {@code null} input array.
  6691.      * </p>
  6692.      *
  6693.      * @param array
  6694.      *            the array to reverse, may be {@code null}
  6695.      * @param startIndexInclusive
  6696.      *            the starting index. Undervalue (&lt;0) is promoted to 0, overvalue (&gt;array.length) results in no
  6697.      *            change.
  6698.      * @param endIndexExclusive
  6699.      *            elements up to endIndex-1 are reversed in the array. Undervalue (&lt; start index) results in no
  6700.      *            change. Overvalue (&gt;array.length) is demoted to array length.
  6701.      * @since 3.2
  6702.      */
  6703.     public static void reverse(final float[] array, final int startIndexInclusive, final int endIndexExclusive) {
  6704.         if (array == null) {
  6705.             return;
  6706.         }
  6707.         int i = Math.max(startIndexInclusive, 0);
  6708.         int j = Math.min(array.length, endIndexExclusive) - 1;
  6709.         float tmp;
  6710.         while (j > i) {
  6711.             tmp = array[j];
  6712.             array[j] = array[i];
  6713.             array[i] = tmp;
  6714.             j--;
  6715.             i++;
  6716.         }
  6717.     }

  6719.     /**
  6720.      * Reverses the order of the given array.
  6721.      * <p>
  6722.      * This method does nothing for a {@code null} input array.
  6723.      * </p>
  6724.      *
  6725.      * @param array  the array to reverse, may be {@code null}
  6726.      */
  6727.     public static void reverse(final int[] array) {
  6728.         if (array != null) {
  6729.             reverse(array, 0, array.length);
  6730.         }
  6731.     }

  6733.     /**
  6734.      * Reverses the order of the given array in the given range.
  6735.      * <p>
  6736.      * This method does nothing for a {@code null} input array.
  6737.      * </p>
  6738.      *
  6739.      * @param array
  6740.      *            the array to reverse, may be {@code null}
  6741.      * @param startIndexInclusive
  6742.      *            the starting index. Undervalue (&lt;0) is promoted to 0, overvalue (&gt;array.length) results in no
  6743.      *            change.
  6744.      * @param endIndexExclusive
  6745.      *            elements up to endIndex-1 are reversed in the array. Undervalue (&lt; start index) results in no
  6746.      *            change. Overvalue (&gt;array.length) is demoted to array length.
  6747.      * @since 3.2
  6748.      */
  6749.     public static void reverse(final int[] array, final int startIndexInclusive, final int endIndexExclusive) {
  6750.         if (array == null) {
  6751.             return;
  6752.         }
  6753.         int i = Math.max(startIndexInclusive, 0);
  6754.         int j = Math.min(array.length, endIndexExclusive) - 1;
  6755.         int tmp;
  6756.         while (j > i) {
  6757.             tmp = array[j];
  6758.             array[j] = array[i];
  6759.             array[i] = tmp;
  6760.             j--;
  6761.             i++;
  6762.         }
  6763.     }

  6765.     /**
  6766.      * Reverses the order of the given array.
  6767.      * <p>
  6768.      * This method does nothing for a {@code null} input array.
  6769.      * </p>
  6770.      *
  6771.      * @param array  the array to reverse, may be {@code null}
  6772.      */
  6773.     public static void reverse(final long[] array) {
  6774.         if (array != null) {
  6775.             reverse(array, 0, array.length);
  6776.         }
  6777.     }

  6779.     /**
  6780.      * Reverses the order of the given array in the given range.
  6781.      * <p>
  6782.      * This method does nothing for a {@code null} input array.
  6783.      * </p>
  6784.      *
  6785.      * @param array
  6786.      *            the array to reverse, may be {@code null}
  6787.      * @param startIndexInclusive
  6788.      *            the starting index. Undervalue (&lt;0) is promoted to 0, overvalue (&gt;array.length) results in no
  6789.      *            change.
  6790.      * @param endIndexExclusive
  6791.      *            elements up to endIndex-1 are reversed in the array. Undervalue (&lt; start index) results in no
  6792.      *            change. Overvalue (&gt;array.length) is demoted to array length.
  6793.      * @since 3.2
  6794.      */
  6795.     public static void reverse(final long[] array, final int startIndexInclusive, final int endIndexExclusive) {
  6796.         if (array == null) {
  6797.             return;
  6798.         }
  6799.         int i = Math.max(startIndexInclusive, 0);
  6800.         int j = Math.min(array.length, endIndexExclusive) - 1;
  6801.         long tmp;
  6802.         while (j > i) {
  6803.             tmp = array[j];
  6804.             array[j] = array[i];
  6805.             array[i] = tmp;
  6806.             j--;
  6807.             i++;
  6808.         }
  6809.     }

  6811.     /**
  6812.      * Reverses the order of the given array.
  6813.      * <p>
  6814.      * There is no special handling for multi-dimensional arrays.
  6815.      * </p>
  6816.      * <p>
  6817.      * This method does nothing for a {@code null} input array.
  6818.      * </p>
  6819.      *
  6820.      * @param array  the array to reverse, may be {@code null}
  6821.      */
  6822.     public static void reverse(final Object[] array) {
  6823.         if (array != null) {
  6824.             reverse(array, 0, array.length);
  6825.         }
  6826.     }

  6828.     /**
  6829.      * Reverses the order of the given array in the given range.
  6830.      * <p>
  6831.      * This method does nothing for a {@code null} input array.
  6832.      * </p>
  6833.      *
  6834.      * @param array
  6835.      *            the array to reverse, may be {@code null}
  6836.      * @param startIndexInclusive
  6837.      *            the starting index. Under value (&lt;0) is promoted to 0, over value (&gt;array.length) results in no
  6838.      *            change.
  6839.      * @param endIndexExclusive
  6840.      *            elements up to endIndex-1 are reversed in the array. Under value (&lt; start index) results in no
  6841.      *            change. Over value (&gt;array.length) is demoted to array length.
  6842.      * @since 3.2
  6843.      */
  6844.     public static void reverse(final Object[] array, final int startIndexInclusive, final int endIndexExclusive) {
  6845.         if (array == null) {
  6846.             return;
  6847.         }
  6848.         int i = Math.max(startIndexInclusive, 0);
  6849.         int j = Math.min(array.length, endIndexExclusive) - 1;
  6850.         Object tmp;
  6851.         while (j > i) {
  6852.             tmp = array[j];
  6853.             array[j] = array[i];
  6854.             array[i] = tmp;
  6855.             j--;
  6856.             i++;
  6857.         }
  6858.     }

  6860.     /**
  6861.      * Reverses the order of the given array.
  6862.      * <p>
  6863.      * This method does nothing for a {@code null} input array.
  6864.      * </p>
  6865.      *
  6866.      * @param array  the array to reverse, may be {@code null}
  6867.      */
  6868.     public static void reverse(final short[] array) {
  6869.         if (array != null) {
  6870.             reverse(array, 0, array.length);
  6871.         }
  6872.     }

  6874.     /**
  6875.      * Reverses the order of the given array in the given range.
  6876.      * <p>
  6877.      * This method does nothing for a {@code null} input array.
  6878.      * </p>
  6879.      *
  6880.      * @param array
  6881.      *            the array to reverse, may be {@code null}
  6882.      * @param startIndexInclusive
  6883.      *            the starting index. Undervalue (&lt;0) is promoted to 0, overvalue (&gt;array.length) results in no
  6884.      *            change.
  6885.      * @param endIndexExclusive
  6886.      *            elements up to endIndex-1 are reversed in the array. Undervalue (&lt; start index) results in no
  6887.      *            change. Overvalue (&gt;array.length) is demoted to array length.
  6888.      * @since 3.2
  6889.      */
  6890.     public static void reverse(final short[] array, final int startIndexInclusive, final int endIndexExclusive) {
  6891.         if (array == null) {
  6892.             return;
  6893.         }
  6894.         int i = Math.max(startIndexInclusive, 0);
  6895.         int j = Math.min(array.length, endIndexExclusive) - 1;
  6896.         short tmp;
  6897.         while (j > i) {
  6898.             tmp = array[j];
  6899.             array[j] = array[i];
  6900.             array[i] = tmp;
  6901.             j--;
  6902.             i++;
  6903.         }
  6904.     }

  6906.     /**
  6907.      * Sets all elements of the specified array, using the provided generator supplier to compute each element.
  6908.      * <p>
  6909.      * If the generator supplier throws an exception, it is relayed to the caller and the array is left in an indeterminate
  6910.      * state.
  6911.      * </p>
  6912.      *
  6913.      * @param <T> type of elements of the array.
  6914.      * @param array array to be initialized.
  6915.      * @param generator a function accepting an index and producing the desired value for that position.
  6916.      * @return the input array
  6917.      * @since 3.13.0
  6918.      */
  6919.     public static <T> T[] setAll(final T[] array, final IntFunction<? extends T> generator) {
  6920.         if (array != null && generator != null) {
  6921.             Arrays.setAll(array, generator);
  6922.         }
  6923.         return array;
  6924.     }

  6926.     /**
  6927.      * Sets all elements of the specified array, using the provided generator supplier to compute each element.
  6928.      * <p>
  6929.      * If the generator supplier throws an exception, it is relayed to the caller and the array is left in an indeterminate
  6930.      * state.
  6931.      * </p>
  6932.      *
  6933.      * @param <T> type of elements of the array.
  6934.      * @param array array to be initialized.
  6935.      * @param generator a function accepting an index and producing the desired value for that position.
  6936.      * @return the input array
  6937.      * @since 3.13.0
  6938.      */
  6939.     public static <T> T[] setAll(final T[] array, final Supplier<? extends T> generator) {
  6940.         if (array != null && generator != null) {
  6941.             for (int i = 0; i < array.length; i++) {
  6942.                 array[i] = generator.get();
  6943.             }
  6944.         }
  6945.         return array;
  6946.     }

  6948.     /**
  6949.      * Shifts the order of the given boolean array.
  6950.      *
  6951.      * <p>There is no special handling for multi-dimensional arrays. This method
  6952.      * does nothing for {@code null} or empty input arrays.</p>
  6953.      *
  6954.      * @param array  the array to shift, may be {@code null}
  6955.      * @param offset
  6956.      *          The number of positions to rotate the elements.  If the offset is larger than the number of elements to
  6957.      *          rotate, than the effective offset is modulo the number of elements to rotate.
  6958.      * @since 3.5
  6959.      */
  6960.     public static void shift(final boolean[] array, final int offset) {
  6961.         if (array != null) {
  6962.             shift(array, 0, array.length, offset);
  6963.         }
  6964.     }

  6966.     /**
  6967.      * Shifts the order of a series of elements in the given boolean array.
  6968.      *
  6969.      * <p>There is no special handling for multi-dimensional arrays. This method
  6970.      * does nothing for {@code null} or empty input arrays.</p>
  6971.      *
  6972.      * @param array
  6973.      *            the array to shift, may be {@code null}
  6974.      * @param startIndexInclusive
  6975.      *            the starting index. Undervalue (&lt;0) is promoted to 0, overvalue (&gt;array.length) results in no
  6976.      *            change.
  6977.      * @param endIndexExclusive
  6978.      *            elements up to endIndex-1 are shifted in the array. Undervalue (&lt; start index) results in no
  6979.      *            change. Overvalue (&gt;array.length) is demoted to array length.
  6980.      * @param offset
  6981.      *          The number of positions to rotate the elements.  If the offset is larger than the number of elements to
  6982.      *          rotate, than the effective offset is modulo the number of elements to rotate.
  6983.      * @since 3.5
  6984.      */
  6985.     public static void shift(final boolean[] array, int startIndexInclusive, int endIndexExclusive, int offset) {
  6986.         if (array == null || startIndexInclusive >= array.length - 1 || endIndexExclusive <= 0) {
  6987.             return;
  6988.         }
  6989.         startIndexInclusive = max0(startIndexInclusive);
  6990.         endIndexExclusive = Math.min(endIndexExclusive, array.length);
  6991.         int n = endIndexExclusive - startIndexInclusive;
  6992.         if (n <= 1) {
  6993.             return;
  6994.         }
  6995.         offset %= n;
  6996.         if (offset < 0) {
  6997.             offset += n;
  6998.         }
  6999.         // For algorithm explanations and proof of O(n) time complexity and O(1) space complexity
  7000.         // see https://beradrian.wordpress.com/2015/04/07/shift-an-array-in-on-in-place/
  7001.         while (n > 1 && offset > 0) {
  7002.             final int nOffset = n - offset;
  7003.             if (offset > nOffset) {
  7004.                 swap(array, startIndexInclusive, startIndexInclusive + n - nOffset,  nOffset);
  7005.                 n = offset;
  7006.                 offset -= nOffset;
  7007.             } else if (offset < nOffset) {
  7008.                 swap(array, startIndexInclusive, startIndexInclusive + nOffset,  offset);
  7009.                 startIndexInclusive += offset;
  7010.                 n = nOffset;
  7011.             } else {
  7012.                 swap(array, startIndexInclusive, startIndexInclusive + nOffset, offset);
  7013.                 break;
  7014.             }
  7015.         }
  7016.     }

  7018.     /**
  7019.      * Shifts the order of the given byte array.
  7020.      *
  7021.      * <p>There is no special handling for multi-dimensional arrays. This method
  7022.      * does nothing for {@code null} or empty input arrays.</p>
  7023.      *
  7024.      * @param array  the array to shift, may be {@code null}
  7025.      * @param offset
  7026.      *          The number of positions to rotate the elements.  If the offset is larger than the number of elements to
  7027.      *          rotate, than the effective offset is modulo the number of elements to rotate.
  7028.      * @since 3.5
  7029.      */
  7030.     public static void shift(final byte[] array, final int offset) {
  7031.         if (array != null) {
  7032.             shift(array, 0, array.length, offset);
  7033.         }
  7034.     }

  7036.     /**
  7037.      * Shifts the order of a series of elements in the given byte array.
  7038.      *
  7039.      * <p>There is no special handling for multi-dimensional arrays. This method
  7040.      * does nothing for {@code null} or empty input arrays.</p>
  7041.      *
  7042.      * @param array
  7043.      *            the array to shift, may be {@code null}
  7044.      * @param startIndexInclusive
  7045.      *            the starting index. Undervalue (&lt;0) is promoted to 0, overvalue (&gt;array.length) results in no
  7046.      *            change.
  7047.      * @param endIndexExclusive
  7048.      *            elements up to endIndex-1 are shifted in the array. Undervalue (&lt; start index) results in no
  7049.      *            change. Overvalue (&gt;array.length) is demoted to array length.
  7050.      * @param offset
  7051.      *          The number of positions to rotate the elements.  If the offset is larger than the number of elements to
  7052.      *          rotate, than the effective offset is modulo the number of elements to rotate.
  7053.      * @since 3.5
  7054.      */
  7055.     public static void shift(final byte[] array, int startIndexInclusive, int endIndexExclusive, int offset) {
  7056.         if (array == null || startIndexInclusive >= array.length - 1 || endIndexExclusive <= 0) {
  7057.             return;
  7058.         }
  7059.         startIndexInclusive = max0(startIndexInclusive);
  7060.         endIndexExclusive = Math.min(endIndexExclusive, array.length);
  7061.         int n = endIndexExclusive - startIndexInclusive;
  7062.         if (n <= 1) {
  7063.             return;
  7064.         }
  7065.         offset %= n;
  7066.         if (offset < 0) {
  7067.             offset += n;
  7068.         }
  7069.         // For algorithm explanations and proof of O(n) time complexity and O(1) space complexity
  7070.         // see https://beradrian.wordpress.com/2015/04/07/shift-an-array-in-on-in-place/
  7071.         while (n > 1 && offset > 0) {
  7072.             final int nOffset = n - offset;
  7073.             if (offset > nOffset) {
  7074.                 swap(array, startIndexInclusive, startIndexInclusive + n - nOffset,  nOffset);
  7075.                 n = offset;
  7076.                 offset -= nOffset;
  7077.             } else if (offset < nOffset) {
  7078.                 swap(array, startIndexInclusive, startIndexInclusive + nOffset,  offset);
  7079.                 startIndexInclusive += offset;
  7080.                 n = nOffset;
  7081.             } else {
  7082.                 swap(array, startIndexInclusive, startIndexInclusive + nOffset, offset);
  7083.                 break;
  7084.             }
  7085.         }
  7086.     }

  7088.     /**
  7089.      * Shifts the order of the given char array.
  7090.      *
  7091.      * <p>There is no special handling for multi-dimensional arrays. This method
  7092.      * does nothing for {@code null} or empty input arrays.</p>
  7093.      *
  7094.      * @param array  the array to shift, may be {@code null}
  7095.      * @param offset
  7096.      *          The number of positions to rotate the elements.  If the offset is larger than the number of elements to
  7097.      *          rotate, than the effective offset is modulo the number of elements to rotate.
  7098.      * @since 3.5
  7099.      */
  7100.     public static void shift(final char[] array, final int offset) {
  7101.         if (array != null) {
  7102.             shift(array, 0, array.length, offset);
  7103.         }
  7104.     }

  7106.     /**
  7107.      * Shifts the order of a series of elements in the given char array.
  7108.      *
  7109.      * <p>There is no special handling for multi-dimensional arrays. This method
  7110.      * does nothing for {@code null} or empty input arrays.</p>
  7111.      *
  7112.      * @param array
  7113.      *            the array to shift, may be {@code null}
  7114.      * @param startIndexInclusive
  7115.      *            the starting index. Undervalue (&lt;0) is promoted to 0, overvalue (&gt;array.length) results in no
  7116.      *            change.
  7117.      * @param endIndexExclusive
  7118.      *            elements up to endIndex-1 are shifted in the array. Undervalue (&lt; start index) results in no
  7119.      *            change. Overvalue (&gt;array.length) is demoted to array length.
  7120.      * @param offset
  7121.      *          The number of positions to rotate the elements.  If the offset is larger than the number of elements to
  7122.      *          rotate, than the effective offset is modulo the number of elements to rotate.
  7123.      * @since 3.5
  7124.      */
  7125.     public static void shift(final char[] array, int startIndexInclusive, int endIndexExclusive, int offset) {
  7126.         if (array == null || startIndexInclusive >= array.length - 1 || endIndexExclusive <= 0) {
  7127.             return;
  7128.         }
  7129.         startIndexInclusive = max0(startIndexInclusive);
  7130.         endIndexExclusive = Math.min(endIndexExclusive, array.length);
  7131.         int n = endIndexExclusive - startIndexInclusive;
  7132.         if (n <= 1) {
  7133.             return;
  7134.         }
  7135.         offset %= n;
  7136.         if (offset < 0) {
  7137.             offset += n;
  7138.         }
  7139.         // For algorithm explanations and proof of O(n) time complexity and O(1) space complexity
  7140.         // see https://beradrian.wordpress.com/2015/04/07/shift-an-array-in-on-in-place/
  7141.         while (n > 1 && offset > 0) {
  7142.             final int nOffset = n - offset;
  7143.             if (offset > nOffset) {
  7144.                 swap(array, startIndexInclusive, startIndexInclusive + n - nOffset,  nOffset);
  7145.                 n = offset;
  7146.                 offset -= nOffset;
  7147.             } else if (offset < nOffset) {
  7148.                 swap(array, startIndexInclusive, startIndexInclusive + nOffset,  offset);
  7149.                 startIndexInclusive += offset;
  7150.                 n = nOffset;
  7151.             } else {
  7152.                 swap(array, startIndexInclusive, startIndexInclusive + nOffset, offset);
  7153.                 break;
  7154.             }
  7155.         }
  7156.     }

  7158.     /**
  7159.      * Shifts the order of the given double array.
  7160.      *
  7161.      * <p>There is no special handling for multi-dimensional arrays. This method
  7162.      * does nothing for {@code null} or empty input arrays.</p>
  7163.      *
  7164.      * @param array  the array to shift, may be {@code null}
  7165.      * @param offset
  7166.      *          The number of positions to rotate the elements.  If the offset is larger than the number of elements to
  7167.      *          rotate, than the effective offset is modulo the number of elements to rotate.
  7168.      * @since 3.5
  7169.      */
  7170.     public static void shift(final double[] array, final int offset) {
  7171.         if (array != null) {
  7172.             shift(array, 0, array.length, offset);
  7173.         }
  7174.     }

  7176.     /**
  7177.      * Shifts the order of a series of elements in the given double array.
  7178.      *
  7179.      * <p>There is no special handling for multi-dimensional arrays. This method
  7180.      * does nothing for {@code null} or empty input arrays.</p>
  7181.      *
  7182.      * @param array
  7183.      *            the array to shift, may be {@code null}
  7184.      * @param startIndexInclusive
  7185.      *            the starting index. Undervalue (&lt;0) is promoted to 0, overvalue (&gt;array.length) results in no
  7186.      *            change.
  7187.      * @param endIndexExclusive
  7188.      *            elements up to endIndex-1 are shifted in the array. Undervalue (&lt; start index) results in no
  7189.      *            change. Overvalue (&gt;array.length) is demoted to array length.
  7190.      * @param offset
  7191.      *          The number of positions to rotate the elements.  If the offset is larger than the number of elements to
  7192.      *          rotate, than the effective offset is modulo the number of elements to rotate.
  7193.      * @since 3.5
  7194.      */
  7195.     public static void shift(final double[] array, int startIndexInclusive, int endIndexExclusive, int offset) {
  7196.         if (array == null || startIndexInclusive >= array.length - 1 || endIndexExclusive <= 0) {
  7197.             return;
  7198.         }
  7199.         startIndexInclusive = max0(startIndexInclusive);
  7200.         endIndexExclusive = Math.min(endIndexExclusive, array.length);
  7201.         int n = endIndexExclusive - startIndexInclusive;
  7202.         if (n <= 1) {
  7203.             return;
  7204.         }
  7205.         offset %= n;
  7206.         if (offset < 0) {
  7207.             offset += n;
  7208.         }
  7209.         // For algorithm explanations and proof of O(n) time complexity and O(1) space complexity
  7210.         // see https://beradrian.wordpress.com/2015/04/07/shift-an-array-in-on-in-place/
  7211.         while (n > 1 && offset > 0) {
  7212.             final int nOffset = n - offset;
  7213.             if (offset > nOffset) {
  7214.                 swap(array, startIndexInclusive, startIndexInclusive + n - nOffset,  nOffset);
  7215.                 n = offset;
  7216.                 offset -= nOffset;
  7217.             } else if (offset < nOffset) {
  7218.                 swap(array, startIndexInclusive, startIndexInclusive + nOffset,  offset);
  7219.                 startIndexInclusive += offset;
  7220.                 n = nOffset;
  7221.             } else {
  7222.                 swap(array, startIndexInclusive, startIndexInclusive + nOffset, offset);
  7223.                 break;
  7224.             }
  7225.         }
  7226.     }

  7228.     /**
  7229.      * Shifts the order of the given float array.
  7230.      *
  7231.      * <p>There is no special handling for multi-dimensional arrays. This method
  7232.      * does nothing for {@code null} or empty input arrays.</p>
  7233.      *
  7234.      * @param array  the array to shift, may be {@code null}
  7235.      * @param offset
  7236.      *          The number of positions to rotate the elements.  If the offset is larger than the number of elements to
  7237.      *          rotate, than the effective offset is modulo the number of elements to rotate.
  7238.      * @since 3.5
  7239.      */
  7240.     public static void shift(final float[] array, final int offset) {
  7241.         if (array != null) {
  7242.             shift(array, 0, array.length, offset);
  7243.         }
  7244.     }

  7246.     /**
  7247.      * Shifts the order of a series of elements in the given float array.
  7248.      *
  7249.      * <p>There is no special handling for multi-dimensional arrays. This method
  7250.      * does nothing for {@code null} or empty input arrays.</p>
  7251.      *
  7252.      * @param array
  7253.      *            the array to shift, may be {@code null}
  7254.      * @param startIndexInclusive
  7255.      *            the starting index. Undervalue (&lt;0) is promoted to 0, overvalue (&gt;array.length) results in no
  7256.      *            change.
  7257.      * @param endIndexExclusive
  7258.      *            elements up to endIndex-1 are shifted in the array. Undervalue (&lt; start index) results in no
  7259.      *            change. Overvalue (&gt;array.length) is demoted to array length.
  7260.      * @param offset
  7261.      *          The number of positions to rotate the elements.  If the offset is larger than the number of elements to
  7262.      *          rotate, than the effective offset is modulo the number of elements to rotate.
  7263.      * @since 3.5
  7264.      */
  7265.     public static void shift(final float[] array, int startIndexInclusive, int endIndexExclusive, int offset) {
  7266.         if (array == null || startIndexInclusive >= array.length - 1 || endIndexExclusive <= 0) {
  7267.             return;
  7268.         }
  7269.         startIndexInclusive = max0(startIndexInclusive);
  7270.         endIndexExclusive = Math.min(endIndexExclusive, array.length);
  7271.         int n = endIndexExclusive - startIndexInclusive;
  7272.         if (n <= 1) {
  7273.             return;
  7274.         }
  7275.         offset %= n;
  7276.         if (offset < 0) {
  7277.             offset += n;
  7278.         }
  7279.         // For algorithm explanations and proof of O(n) time complexity and O(1) space complexity
  7280.         // see https://beradrian.wordpress.com/2015/04/07/shift-an-array-in-on-in-place/
  7281.         while (n > 1 && offset > 0) {
  7282.             final int nOffset = n - offset;
  7283.             if (offset > nOffset) {
  7284.                 swap(array, startIndexInclusive, startIndexInclusive + n - nOffset,  nOffset);
  7285.                 n = offset;
  7286.                 offset -= nOffset;
  7287.             } else if (offset < nOffset) {
  7288.                 swap(array, startIndexInclusive, startIndexInclusive + nOffset,  offset);
  7289.                 startIndexInclusive += offset;
  7290.                 n = nOffset;
  7291.             } else {
  7292.                 swap(array, startIndexInclusive, startIndexInclusive + nOffset, offset);
  7293.                 break;
  7294.             }
  7295.         }
  7296.     }

  7298.     /**
  7299.      * Shifts the order of the given int array.
  7300.      *
  7301.      * <p>There is no special handling for multi-dimensional arrays. This method
  7302.      * does nothing for {@code null} or empty input arrays.</p>
  7303.      *
  7304.      * @param array  the array to shift, may be {@code null}
  7305.      * @param offset
  7306.      *          The number of positions to rotate the elements.  If the offset is larger than the number of elements to
  7307.      *          rotate, than the effective offset is modulo the number of elements to rotate.
  7308.      * @since 3.5
  7309.      */
  7310.     public static void shift(final int[] array, final int offset) {
  7311.         if (array != null) {
  7312.             shift(array, 0, array.length, offset);
  7313.         }
  7314.     }

  7316.     /**
  7317.      * Shifts the order of a series of elements in the given int array.
  7318.      *
  7319.      * <p>There is no special handling for multi-dimensional arrays. This method
  7320.      * does nothing for {@code null} or empty input arrays.</p>
  7321.      *
  7322.      * @param array
  7323.      *            the array to shift, may be {@code null}
  7324.      * @param startIndexInclusive
  7325.      *            the starting index. Undervalue (&lt;0) is promoted to 0, overvalue (&gt;array.length) results in no
  7326.      *            change.
  7327.      * @param endIndexExclusive
  7328.      *            elements up to endIndex-1 are shifted in the array. Undervalue (&lt; start index) results in no
  7329.      *            change. Overvalue (&gt;array.length) is demoted to array length.
  7330.      * @param offset
  7331.      *          The number of positions to rotate the elements.  If the offset is larger than the number of elements to
  7332.      *          rotate, than the effective offset is modulo the number of elements to rotate.
  7333.      * @since 3.5
  7334.      */
  7335.     public static void shift(final int[] array, int startIndexInclusive, int endIndexExclusive, int offset) {
  7336.         if (array == null || startIndexInclusive >= array.length - 1 || endIndexExclusive <= 0) {
  7337.             return;
  7338.         }
  7339.         startIndexInclusive = max0(startIndexInclusive);
  7340.         endIndexExclusive = Math.min(endIndexExclusive, array.length);
  7341.         int n = endIndexExclusive - startIndexInclusive;
  7342.         if (n <= 1) {
  7343.             return;
  7344.         }
  7345.         offset %= n;
  7346.         if (offset < 0) {
  7347.             offset += n;
  7348.         }
  7349.         // For algorithm explanations and proof of O(n) time complexity and O(1) space complexity
  7350.         // see https://beradrian.wordpress.com/2015/04/07/shift-an-array-in-on-in-place/
  7351.         while (n > 1 && offset > 0) {
  7352.             final int nOffset = n - offset;
  7353.             if (offset > nOffset) {
  7354.                 swap(array, startIndexInclusive, startIndexInclusive + n - nOffset,  nOffset);
  7355.                 n = offset;
  7356.                 offset -= nOffset;
  7357.             } else if (offset < nOffset) {
  7358.                 swap(array, startIndexInclusive, startIndexInclusive + nOffset,  offset);
  7359.                 startIndexInclusive += offset;
  7360.                 n = nOffset;
  7361.             } else {
  7362.                 swap(array, startIndexInclusive, startIndexInclusive + nOffset, offset);
  7363.                 break;
  7364.             }
  7365.         }
  7366.     }

  7368.     /**
  7369.      * Shifts the order of the given long array.
  7370.      *
  7371.      * <p>There is no special handling for multi-dimensional arrays. This method
  7372.      * does nothing for {@code null} or empty input arrays.</p>
  7373.      *
  7374.      * @param array  the array to shift, may be {@code null}
  7375.      * @param offset
  7376.      *          The number of positions to rotate the elements.  If the offset is larger than the number of elements to
  7377.      *          rotate, than the effective offset is modulo the number of elements to rotate.
  7378.      * @since 3.5
  7379.      */
  7380.     public static void shift(final long[] array, final int offset) {
  7381.         if (array != null) {
  7382.             shift(array, 0, array.length, offset);
  7383.         }
  7384.     }

  7386.     /**
  7387.      * Shifts the order of a series of elements in the given long array.
  7388.      *
  7389.      * <p>There is no special handling for multi-dimensional arrays. This method
  7390.      * does nothing for {@code null} or empty input arrays.</p>
  7391.      *
  7392.      * @param array
  7393.      *            the array to shift, may be {@code null}
  7394.      * @param startIndexInclusive
  7395.      *            the starting index. Undervalue (&lt;0) is promoted to 0, overvalue (&gt;array.length) results in no
  7396.      *            change.
  7397.      * @param endIndexExclusive
  7398.      *            elements up to endIndex-1 are shifted in the array. Undervalue (&lt; start index) results in no
  7399.      *            change. Overvalue (&gt;array.length) is demoted to array length.
  7400.      * @param offset
  7401.      *          The number of positions to rotate the elements.  If the offset is larger than the number of elements to
  7402.      *          rotate, than the effective offset is modulo the number of elements to rotate.
  7403.      * @since 3.5
  7404.      */
  7405.     public static void shift(final long[] array, int startIndexInclusive, int endIndexExclusive, int offset) {
  7406.         if (array == null || startIndexInclusive >= array.length - 1 || endIndexExclusive <= 0) {
  7407.             return;
  7408.         }
  7409.         startIndexInclusive = max0(startIndexInclusive);
  7410.         endIndexExclusive = Math.min(endIndexExclusive, array.length);
  7411.         int n = endIndexExclusive - startIndexInclusive;
  7412.         if (n <= 1) {
  7413.             return;
  7414.         }
  7415.         offset %= n;
  7416.         if (offset < 0) {
  7417.             offset += n;
  7418.         }
  7419.         // For algorithm explanations and proof of O(n) time complexity and O(1) space complexity
  7420.         // see https://beradrian.wordpress.com/2015/04/07/shift-an-array-in-on-in-place/
  7421.         while (n > 1 && offset > 0) {
  7422.             final int nOffset = n - offset;
  7423.             if (offset > nOffset) {
  7424.                 swap(array, startIndexInclusive, startIndexInclusive + n - nOffset,  nOffset);
  7425.                 n = offset;
  7426.                 offset -= nOffset;
  7427.             } else if (offset < nOffset) {
  7428.                 swap(array, startIndexInclusive, startIndexInclusive + nOffset,  offset);
  7429.                 startIndexInclusive += offset;
  7430.                 n = nOffset;
  7431.             } else {
  7432.                 swap(array, startIndexInclusive, startIndexInclusive + nOffset, offset);
  7433.                 break;
  7434.             }
  7435.         }
  7436.     }

  7438.     /**
  7439.      * Shifts the order of the given array.
  7440.      *
  7441.      * <p>There is no special handling for multi-dimensional arrays. This method
  7442.      * does nothing for {@code null} or empty input arrays.</p>
  7443.      *
  7444.      * @param array  the array to shift, may be {@code null}
  7445.      * @param offset
  7446.      *          The number of positions to rotate the elements.  If the offset is larger than the number of elements to
  7447.      *          rotate, than the effective offset is modulo the number of elements to rotate.
  7448.      * @since 3.5
  7449.      */
  7450.     public static void shift(final Object[] array, final int offset) {
  7451.         if (array != null) {
  7452.             shift(array, 0, array.length, offset);
  7453.         }
  7454.     }

  7456.     /**
  7457.      * Shifts the order of a series of elements in the given array.
  7458.      *
  7459.      * <p>There is no special handling for multi-dimensional arrays. This method
  7460.      * does nothing for {@code null} or empty input arrays.</p>
  7461.      *
  7462.      * @param array
  7463.      *            the array to shift, may be {@code null}
  7464.      * @param startIndexInclusive
  7465.      *            the starting index. Undervalue (&lt;0) is promoted to 0, overvalue (&gt;array.length) results in no
  7466.      *            change.
  7467.      * @param endIndexExclusive
  7468.      *            elements up to endIndex-1 are shifted in the array. Undervalue (&lt; start index) results in no
  7469.      *            change. Overvalue (&gt;array.length) is demoted to array length.
  7470.      * @param offset
  7471.      *          The number of positions to rotate the elements.  If the offset is larger than the number of elements to
  7472.      *          rotate, than the effective offset is modulo the number of elements to rotate.
  7473.      * @since 3.5
  7474.      */
  7475.     public static void shift(final Object[] array, int startIndexInclusive, int endIndexExclusive, int offset) {
  7476.         if (array == null || startIndexInclusive >= array.length - 1 || endIndexExclusive <= 0) {
  7477.             return;
  7478.         }
  7479.         startIndexInclusive = max0(startIndexInclusive);
  7480.         endIndexExclusive = Math.min(endIndexExclusive, array.length);
  7481.         int n = endIndexExclusive - startIndexInclusive;
  7482.         if (n <= 1) {
  7483.             return;
  7484.         }
  7485.         offset %= n;
  7486.         if (offset < 0) {
  7487.             offset += n;
  7488.         }
  7489.         // For algorithm explanations and proof of O(n) time complexity and O(1) space complexity
  7490.         // see https://beradrian.wordpress.com/2015/04/07/shift-an-array-in-on-in-place/
  7491.         while (n > 1 && offset > 0) {
  7492.             final int nOffset = n - offset;
  7493.             if (offset > nOffset) {
  7494.                 swap(array, startIndexInclusive, startIndexInclusive + n - nOffset,  nOffset);
  7495.                 n = offset;
  7496.                 offset -= nOffset;
  7497.             } else if (offset < nOffset) {
  7498.                 swap(array, startIndexInclusive, startIndexInclusive + nOffset,  offset);
  7499.                 startIndexInclusive += offset;
  7500.                 n = nOffset;
  7501.             } else {
  7502.                 swap(array, startIndexInclusive, startIndexInclusive + nOffset, offset);
  7503.                 break;
  7504.             }
  7505.         }
  7506.     }

  7508.     /**
  7509.      * Shifts the order of the given short array.
  7510.      *
  7511.      * <p>There is no special handling for multi-dimensional arrays. This method
  7512.      * does nothing for {@code null} or empty input arrays.</p>
  7513.      *
  7514.      * @param array  the array to shift, may be {@code null}
  7515.      * @param offset
  7516.      *          The number of positions to rotate the elements.  If the offset is larger than the number of elements to
  7517.      *          rotate, than the effective offset is modulo the number of elements to rotate.
  7518.      * @since 3.5
  7519.      */
  7520.     public static void shift(final short[] array, final int offset) {
  7521.         if (array != null) {
  7522.             shift(array, 0, array.length, offset);
  7523.         }
  7524.     }

  7526.     /**
  7527.      * Shifts the order of a series of elements in the given short array.
  7528.      *
  7529.      * <p>There is no special handling for multi-dimensional arrays. This method
  7530.      * does nothing for {@code null} or empty input arrays.</p>
  7531.      *
  7532.      * @param array
  7533.      *            the array to shift, may be {@code null}
  7534.      * @param startIndexInclusive
  7535.      *            the starting index. Undervalue (&lt;0) is promoted to 0, overvalue (&gt;array.length) results in no
  7536.      *            change.
  7537.      * @param endIndexExclusive
  7538.      *            elements up to endIndex-1 are shifted in the array. Undervalue (&lt; start index) results in no
  7539.      *            change. Overvalue (&gt;array.length) is demoted to array length.
  7540.      * @param offset
  7541.      *          The number of positions to rotate the elements.  If the offset is larger than the number of elements to
  7542.      *          rotate, than the effective offset is modulo the number of elements to rotate.
  7543.      * @since 3.5
  7544.      */
  7545.     public static void shift(final short[] array, int startIndexInclusive, int endIndexExclusive, int offset) {
  7546.         if (array == null || startIndexInclusive >= array.length - 1 || endIndexExclusive <= 0) {
  7547.             return;
  7548.         }
  7549.         startIndexInclusive = max0(startIndexInclusive);
  7550.         endIndexExclusive = Math.min(endIndexExclusive, array.length);
  7551.         int n = endIndexExclusive - startIndexInclusive;
  7552.         if (n <= 1) {
  7553.             return;
  7554.         }
  7555.         offset %= n;
  7556.         if (offset < 0) {
  7557.             offset += n;
  7558.         }
  7559.         // For algorithm explanations and proof of O(n) time complexity and O(1) space complexity
  7560.         // see https://beradrian.wordpress.com/2015/04/07/shift-an-array-in-on-in-place/
  7561.         while (n > 1 && offset > 0) {
  7562.             final int nOffset = n - offset;
  7563.             if (offset > nOffset) {
  7564.                 swap(array, startIndexInclusive, startIndexInclusive + n - nOffset,  nOffset);
  7565.                 n = offset;
  7566.                 offset -= nOffset;
  7567.             } else if (offset < nOffset) {
  7568.                 swap(array, startIndexInclusive, startIndexInclusive + nOffset,  offset);
  7569.                 startIndexInclusive += offset;
  7570.                 n = nOffset;
  7571.             } else {
  7572.                 swap(array, startIndexInclusive, startIndexInclusive + nOffset, offset);
  7573.                 break;
  7574.             }
  7575.         }
  7576.     }

  7578.     /**
  7579.      * Randomly permutes the elements of the specified array using the Fisher-Yates algorithm.
  7580.      *
  7581.      * @param array   the array to shuffle
  7582.      * @see <a href="https://en.wikipedia.org/wiki/Fisher%E2%80%93Yates_shuffle">Fisher-Yates shuffle algorithm</a>
  7583.      * @since 3.6
  7584.      */
  7585.     public static void shuffle(final boolean[] array) {
  7586.         shuffle(array, random());
  7587.     }

  7589.     /**
  7590.      * Randomly permutes the elements of the specified array using the Fisher-Yates algorithm.
  7591.      *
  7592.      * @param array   the array to shuffle
  7593.      * @param random  the source of randomness used to permute the elements
  7594.      * @see <a href="https://en.wikipedia.org/wiki/Fisher%E2%80%93Yates_shuffle">Fisher-Yates shuffle algorithm</a>
  7595.      * @since 3.6
  7596.      */
  7597.     public static void shuffle(final boolean[] array, final Random random) {
  7598.         for (int i = array.length; i > 1; i--) {
  7599.             swap(array, i - 1, random.nextInt(i), 1);
  7600.         }
  7601.     }

  7603.     /**
  7604.      * Randomly permutes the elements of the specified array using the Fisher-Yates algorithm.
  7605.      *
  7606.      * @param array   the array to shuffle
  7607.      * @see <a href="https://en.wikipedia.org/wiki/Fisher%E2%80%93Yates_shuffle">Fisher-Yates shuffle algorithm</a>
  7608.      * @since 3.6
  7609.      */
  7610.     public static void shuffle(final byte[] array) {
  7611.         shuffle(array, random());
  7612.     }

  7614.     /**
  7615.      * Randomly permutes the elements of the specified array using the Fisher-Yates algorithm.
  7616.      *
  7617.      * @param array   the array to shuffle
  7618.      * @param random  the source of randomness used to permute the elements
  7619.      * @see <a href="https://en.wikipedia.org/wiki/Fisher%E2%80%93Yates_shuffle">Fisher-Yates shuffle algorithm</a>
  7620.      * @since 3.6
  7621.      */
  7622.     public static void shuffle(final byte[] array, final Random random) {
  7623.         for (int i = array.length; i > 1; i--) {
  7624.             swap(array, i - 1, random.nextInt(i), 1);
  7625.         }
  7626.     }

  7628.     /**
  7629.      * Randomly permutes the elements of the specified array using the Fisher-Yates algorithm.
  7630.      *
  7631.      * @param array   the array to shuffle
  7632.      * @see <a href="https://en.wikipedia.org/wiki/Fisher%E2%80%93Yates_shuffle">Fisher-Yates shuffle algorithm</a>
  7633.      * @since 3.6
  7634.      */
  7635.     public static void shuffle(final char[] array) {
  7636.         shuffle(array, random());
  7637.     }

  7639.     /**
  7640.      * Randomly permutes the elements of the specified array using the Fisher-Yates algorithm.
  7641.      *
  7642.      * @param array   the array to shuffle
  7643.      * @param random  the source of randomness used to permute the elements
  7644.      * @see <a href="https://en.wikipedia.org/wiki/Fisher%E2%80%93Yates_shuffle">Fisher-Yates shuffle algorithm</a>
  7645.      * @since 3.6
  7646.      */
  7647.     public static void shuffle(final char[] array, final Random random) {
  7648.         for (int i = array.length; i > 1; i--) {
  7649.             swap(array, i - 1, random.nextInt(i), 1);
  7650.         }
  7651.     }

  7653.     /**
  7654.      * Randomly permutes the elements of the specified array using the Fisher-Yates algorithm.
  7655.      *
  7656.      * @param array   the array to shuffle
  7657.      * @see <a href="https://en.wikipedia.org/wiki/Fisher%E2%80%93Yates_shuffle">Fisher-Yates shuffle algorithm</a>
  7658.      * @since 3.6
  7659.      */
  7660.     public static void shuffle(final double[] array) {
  7661.         shuffle(array, random());
  7662.     }

  7664.     /**
  7665.      * Randomly permutes the elements of the specified array using the Fisher-Yates algorithm.
  7666.      *
  7667.      * @param array   the array to shuffle
  7668.      * @param random  the source of randomness used to permute the elements
  7669.      * @see <a href="https://en.wikipedia.org/wiki/Fisher%E2%80%93Yates_shuffle">Fisher-Yates shuffle algorithm</a>
  7670.      * @since 3.6
  7671.      */
  7672.     public static void shuffle(final double[] array, final Random random) {
  7673.         for (int i = array.length; i > 1; i--) {
  7674.             swap(array, i - 1, random.nextInt(i), 1);
  7675.         }
  7676.     }

  7678.     /**
  7679.      * Randomly permutes the elements of the specified array using the Fisher-Yates algorithm.
  7680.      *
  7681.      * @param array   the array to shuffle
  7682.      * @see <a href="https://en.wikipedia.org/wiki/Fisher%E2%80%93Yates_shuffle">Fisher-Yates shuffle algorithm</a>
  7683.      * @since 3.6
  7684.      */
  7685.     public static void shuffle(final float[] array) {
  7686.         shuffle(array, random());
  7687.     }

  7689.     /**
  7690.      * Randomly permutes the elements of the specified array using the Fisher-Yates algorithm.
  7691.      *
  7692.      * @param array   the array to shuffle
  7693.      * @param random  the source of randomness used to permute the elements
  7694.      * @see <a href="https://en.wikipedia.org/wiki/Fisher%E2%80%93Yates_shuffle">Fisher-Yates shuffle algorithm</a>
  7695.      * @since 3.6
  7696.      */
  7697.     public static void shuffle(final float[] array, final Random random) {
  7698.         for (int i = array.length; i > 1; i--) {
  7699.             swap(array, i - 1, random.nextInt(i), 1);
  7700.         }
  7701.     }

  7703.     /**
  7704.      * Randomly permutes the elements of the specified array using the Fisher-Yates algorithm.
  7705.      *
  7706.      * @param array   the array to shuffle
  7707.      * @see <a href="https://en.wikipedia.org/wiki/Fisher%E2%80%93Yates_shuffle">Fisher-Yates shuffle algorithm</a>
  7708.      * @since 3.6
  7709.      */
  7710.     public static void shuffle(final int[] array) {
  7711.         shuffle(array, random());
  7712.     }

  7714.     /**
  7715.      * Randomly permutes the elements of the specified array using the Fisher-Yates algorithm.
  7716.      *
  7717.      * @param array   the array to shuffle
  7718.      * @param random  the source of randomness used to permute the elements
  7719.      * @see <a href="https://en.wikipedia.org/wiki/Fisher%E2%80%93Yates_shuffle">Fisher-Yates shuffle algorithm</a>
  7720.      * @since 3.6
  7721.      */
  7722.     public static void shuffle(final int[] array, final Random random) {
  7723.         for (int i = array.length; i > 1; i--) {
  7724.             swap(array, i - 1, random.nextInt(i), 1);
  7725.         }
  7726.     }

  7728.     /**
  7729.      * Randomly permutes the elements of the specified array using the Fisher-Yates algorithm.
  7730.      *
  7731.      * @param array   the array to shuffle
  7732.      * @see <a href="https://en.wikipedia.org/wiki/Fisher%E2%80%93Yates_shuffle">Fisher-Yates shuffle algorithm</a>
  7733.      * @since 3.6
  7734.      */
  7735.     public static void shuffle(final long[] array) {
  7736.         shuffle(array, random());
  7737.     }

  7739.     /**
  7740.      * Randomly permutes the elements of the specified array using the Fisher-Yates algorithm.
  7741.      *
  7742.      * @param array   the array to shuffle
  7743.      * @param random  the source of randomness used to permute the elements
  7744.      * @see <a href="https://en.wikipedia.org/wiki/Fisher%E2%80%93Yates_shuffle">Fisher-Yates shuffle algorithm</a>
  7745.      * @since 3.6
  7746.      */
  7747.     public static void shuffle(final long[] array, final Random random) {
  7748.         for (int i = array.length; i > 1; i--) {
  7749.             swap(array, i - 1, random.nextInt(i), 1);
  7750.         }
  7751.     }

  7753.     /**
  7754.      * Randomly permutes the elements of the specified array using the Fisher-Yates algorithm.
  7755.      *
  7756.      * @param array   the array to shuffle
  7757.      * @see <a href="https://en.wikipedia.org/wiki/Fisher%E2%80%93Yates_shuffle">Fisher-Yates shuffle algorithm</a>
  7758.      * @since 3.6
  7759.      */
  7760.     public static void shuffle(final Object[] array) {
  7761.         shuffle(array, random());
  7762.     }

  7764.     /**
  7765.      * Randomly permutes the elements of the specified array using the Fisher-Yates algorithm.
  7766.      *
  7767.      * @param array   the array to shuffle
  7768.      * @param random  the source of randomness used to permute the elements
  7769.      * @see <a href="https://en.wikipedia.org/wiki/Fisher%E2%80%93Yates_shuffle">Fisher-Yates shuffle algorithm</a>
  7770.      * @since 3.6
  7771.      */
  7772.     public static void shuffle(final Object[] array, final Random random) {
  7773.         for (int i = array.length; i > 1; i--) {
  7774.             swap(array, i - 1, random.nextInt(i), 1);
  7775.         }
  7776.     }

  7778.     /**
  7779.      * Randomly permutes the elements of the specified array using the Fisher-Yates algorithm.
  7780.      *
  7781.      * @param array   the array to shuffle
  7782.      * @see <a href="https://en.wikipedia.org/wiki/Fisher%E2%80%93Yates_shuffle">Fisher-Yates shuffle algorithm</a>
  7783.      * @since 3.6
  7784.      */
  7785.     public static void shuffle(final short[] array) {
  7786.         shuffle(array, random());
  7787.     }

  7789.     /**
  7790.      * Randomly permutes the elements of the specified array using the Fisher-Yates algorithm.
  7791.      *
  7792.      * @param array   the array to shuffle
  7793.      * @param random  the source of randomness used to permute the elements
  7794.      * @see <a href="https://en.wikipedia.org/wiki/Fisher%E2%80%93Yates_shuffle">Fisher-Yates shuffle algorithm</a>
  7795.      * @since 3.6
  7796.      */
  7797.     public static void shuffle(final short[] array, final Random random) {
  7798.         for (int i = array.length; i > 1; i--) {
  7799.             swap(array, i - 1, random.nextInt(i), 1);
  7800.         }
  7801.     }

  7803.     /**
  7804.      * Produces a new {@code boolean} array containing the elements
  7805.      * between the start and end indices.
  7806.      * <p>
  7807.      * The start index is inclusive, the end index exclusive.
  7808.      * Null array input produces null output.
  7809.      * </p>
  7810.      *
  7811.      * @param array  the array
  7812.      * @param startIndexInclusive  the starting index. Undervalue (&lt;0)
  7813.      *      is promoted to 0, overvalue (&gt;array.length) results
  7814.      *      in an empty array.
  7815.      * @param endIndexExclusive  elements up to endIndex-1 are present in the
  7816.      *      returned subarray. Undervalue (&lt; startIndex) produces
  7817.      *      empty array, overvalue (&gt;array.length) is demoted to
  7818.      *      array length.
  7819.      * @return a new array containing the elements between
  7820.      *      the start and end indices.
  7821.      * @since 2.1
  7822.      * @see Arrays#copyOfRange(boolean[], int, int)
  7823.      */
  7824.     public static boolean[] subarray(final boolean[] array, int startIndexInclusive, int endIndexExclusive) {
  7825.         if (array == null) {
  7826.             return null;
  7827.         }
  7828.         startIndexInclusive = max0(startIndexInclusive);
  7829.         endIndexExclusive = Math.min(endIndexExclusive, array.length);
  7830.         final int newSize = endIndexExclusive - startIndexInclusive;
  7831.         if (newSize <= 0) {
  7832.             return EMPTY_BOOLEAN_ARRAY;
  7833.         }
  7834.         return arraycopy(array, startIndexInclusive, 0, newSize, boolean[]::new);
  7835.     }

  7837.     /**
  7838.      * Produces a new {@code byte} array containing the elements
  7839.      * between the start and end indices.
  7840.      * <p>
  7841.      * The start index is inclusive, the end index exclusive.
  7842.      * Null array input produces null output.
  7843.      * </p>
  7844.      *
  7845.      * @param array  the array
  7846.      * @param startIndexInclusive  the starting index. Undervalue (&lt;0)
  7847.      *      is promoted to 0, overvalue (&gt;array.length) results
  7848.      *      in an empty array.
  7849.      * @param endIndexExclusive  elements up to endIndex-1 are present in the
  7850.      *      returned subarray. Undervalue (&lt; startIndex) produces
  7851.      *      empty array, overvalue (&gt;array.length) is demoted to
  7852.      *      array length.
  7853.      * @return a new array containing the elements between
  7854.      *      the start and end indices.
  7855.      * @since 2.1
  7856.      * @see Arrays#copyOfRange(byte[], int, int)
  7857.      */
  7858.     public static byte[] subarray(final byte[] array, int startIndexInclusive, int endIndexExclusive) {
  7859.         if (array == null) {
  7860.             return null;
  7861.         }
  7862.         startIndexInclusive = max0(startIndexInclusive);
  7863.         endIndexExclusive = Math.min(endIndexExclusive, array.length);
  7864.         final int newSize = endIndexExclusive - startIndexInclusive;
  7865.         if (newSize <= 0) {
  7866.             return EMPTY_BYTE_ARRAY;
  7867.         }
  7868.         return arraycopy(array, startIndexInclusive, 0, newSize, byte[]::new);
  7869.     }

  7871.     /**
  7872.      * Produces a new {@code char} array containing the elements
  7873.      * between the start and end indices.
  7874.      * <p>
  7875.      * The start index is inclusive, the end index exclusive.
  7876.      * Null array input produces null output.
  7877.      * </p>
  7878.      *
  7879.      * @param array  the array
  7880.      * @param startIndexInclusive  the starting index. Undervalue (&lt;0)
  7881.      *      is promoted to 0, overvalue (&gt;array.length) results
  7882.      *      in an empty array.
  7883.      * @param endIndexExclusive  elements up to endIndex-1 are present in the
  7884.      *      returned subarray. Undervalue (&lt; startIndex) produces
  7885.      *      empty array, overvalue (&gt;array.length) is demoted to
  7886.      *      array length.
  7887.      * @return a new array containing the elements between
  7888.      *      the start and end indices.
  7889.      * @since 2.1
  7890.      * @see Arrays#copyOfRange(char[], int, int)
  7891.      */
  7892.     public static char[] subarray(final char[] array, int startIndexInclusive, int endIndexExclusive) {
  7893.         if (array == null) {
  7894.             return null;
  7895.         }
  7896.         startIndexInclusive = max0(startIndexInclusive);
  7897.         endIndexExclusive = Math.min(endIndexExclusive, array.length);
  7898.         final int newSize = endIndexExclusive - startIndexInclusive;
  7899.         if (newSize <= 0) {
  7900.             return EMPTY_CHAR_ARRAY;
  7901.         }
  7902.         return arraycopy(array, startIndexInclusive, 0, newSize, char[]::new);
  7903.     }

  7905.     /**
  7906.      * Produces a new {@code double} array containing the elements
  7907.      * between the start and end indices.
  7908.      * <p>
  7909.      * The start index is inclusive, the end index exclusive.
  7910.      * Null array input produces null output.
  7911.      * </p>
  7912.      *
  7913.      * @param array  the array
  7914.      * @param startIndexInclusive  the starting index. Undervalue (&lt;0)
  7915.      *      is promoted to 0, overvalue (&gt;array.length) results
  7916.      *      in an empty array.
  7917.      * @param endIndexExclusive  elements up to endIndex-1 are present in the
  7918.      *      returned subarray. Undervalue (&lt; startIndex) produces
  7919.      *      empty array, overvalue (&gt;array.length) is demoted to
  7920.      *      array length.
  7921.      * @return a new array containing the elements between
  7922.      *      the start and end indices.
  7923.      * @since 2.1
  7924.      * @see Arrays#copyOfRange(double[], int, int)
  7925.      */
  7926.     public static double[] subarray(final double[] array, int startIndexInclusive, int endIndexExclusive) {
  7927.         if (array == null) {
  7928.             return null;
  7929.         }
  7930.         startIndexInclusive = max0(startIndexInclusive);
  7931.         endIndexExclusive = Math.min(endIndexExclusive, array.length);
  7932.         final int newSize = endIndexExclusive - startIndexInclusive;
  7933.         if (newSize <= 0) {
  7934.             return EMPTY_DOUBLE_ARRAY;
  7935.         }
  7936.         return arraycopy(array, startIndexInclusive, 0, newSize, double[]::new);
  7937.     }

  7939.     /**
  7940.      * Produces a new {@code float} array containing the elements
  7941.      * between the start and end indices.
  7942.      * <p>
  7943.      * The start index is inclusive, the end index exclusive.
  7944.      * Null array input produces null output.
  7945.      * </p>
  7946.      *
  7947.      * @param array  the array
  7948.      * @param startIndexInclusive  the starting index. Undervalue (&lt;0)
  7949.      *      is promoted to 0, overvalue (&gt;array.length) results
  7950.      *      in an empty array.
  7951.      * @param endIndexExclusive  elements up to endIndex-1 are present in the
  7952.      *      returned subarray. Undervalue (&lt; startIndex) produces
  7953.      *      empty array, overvalue (&gt;array.length) is demoted to
  7954.      *      array length.
  7955.      * @return a new array containing the elements between
  7956.      *      the start and end indices.
  7957.      * @since 2.1
  7958.      * @see Arrays#copyOfRange(float[], int, int)
  7959.      */
  7960.     public static float[] subarray(final float[] array, int startIndexInclusive, int endIndexExclusive) {
  7961.         if (array == null) {
  7962.             return null;
  7963.         }
  7964.         startIndexInclusive = max0(startIndexInclusive);
  7965.         endIndexExclusive = Math.min(endIndexExclusive, array.length);
  7966.         final int newSize = endIndexExclusive - startIndexInclusive;
  7967.         if (newSize <= 0) {
  7968.             return EMPTY_FLOAT_ARRAY;
  7969.         }
  7970.         return arraycopy(array, startIndexInclusive, 0, newSize, float[]::new);
  7971.     }

  7973.     /**
  7974.      * Produces a new {@code int} array containing the elements
  7975.      * between the start and end indices.
  7976.      * <p>
  7977.      * The start index is inclusive, the end index exclusive.
  7978.      * Null array input produces null output.
  7979.      * </p>
  7980.      *
  7981.      * @param array  the array
  7982.      * @param startIndexInclusive  the starting index. Undervalue (&lt;0)
  7983.      *      is promoted to 0, overvalue (&gt;array.length) results
  7984.      *      in an empty array.
  7985.      * @param endIndexExclusive  elements up to endIndex-1 are present in the
  7986.      *      returned subarray. Undervalue (&lt; startIndex) produces
  7987.      *      empty array, overvalue (&gt;array.length) is demoted to
  7988.      *      array length.
  7989.      * @return a new array containing the elements between
  7990.      *      the start and end indices.
  7991.      * @since 2.1
  7992.      * @see Arrays#copyOfRange(int[], int, int)
  7993.      */
  7994.     public static int[] subarray(final int[] array, int startIndexInclusive, int endIndexExclusive) {
  7995.         if (array == null) {
  7996.             return null;
  7997.         }
  7998.         startIndexInclusive = max0(startIndexInclusive);
  7999.         endIndexExclusive = Math.min(endIndexExclusive, array.length);
  8000.         final int newSize = endIndexExclusive - startIndexInclusive;
  8001.         if (newSize <= 0) {
  8002.             return EMPTY_INT_ARRAY;
  8003.         }
  8004.         return arraycopy(array, startIndexInclusive, 0, newSize, int[]::new);
  8005.     }

  8007.     /**
  8008.      * Produces a new {@code long} array containing the elements
  8009.      * between the start and end indices.
  8010.      * <p>
  8011.      * The start index is inclusive, the end index exclusive.
  8012.      * Null array input produces null output.
  8013.      * </p>
  8014.      *
  8015.      * @param array  the array
  8016.      * @param startIndexInclusive  the starting index. Undervalue (&lt;0)
  8017.      *      is promoted to 0, overvalue (&gt;array.length) results
  8018.      *      in an empty array.
  8019.      * @param endIndexExclusive  elements up to endIndex-1 are present in the
  8020.      *      returned subarray. Undervalue (&lt; startIndex) produces
  8021.      *      empty array, overvalue (&gt;array.length) is demoted to
  8022.      *      array length.
  8023.      * @return a new array containing the elements between
  8024.      *      the start and end indices.
  8025.      * @since 2.1
  8026.      * @see Arrays#copyOfRange(long[], int, int)
  8027.      */
  8028.     public static long[] subarray(final long[] array, int startIndexInclusive, int endIndexExclusive) {
  8029.         if (array == null) {
  8030.             return null;
  8031.         }
  8032.         startIndexInclusive = max0(startIndexInclusive);
  8033.         endIndexExclusive = Math.min(endIndexExclusive, array.length);
  8034.         final int newSize = endIndexExclusive - startIndexInclusive;
  8035.         if (newSize <= 0) {
  8036.             return EMPTY_LONG_ARRAY;
  8037.         }
  8038.         return arraycopy(array, startIndexInclusive, 0, newSize, long[]::new);
  8039.     }

  8041.     /**
  8042.      * Produces a new {@code short} array containing the elements
  8043.      * between the start and end indices.
  8044.      * <p>
  8045.      * The start index is inclusive, the end index exclusive.
  8046.      * Null array input produces null output.
  8047.      * </p>
  8048.      *
  8049.      * @param array  the array
  8050.      * @param startIndexInclusive  the starting index. Undervalue (&lt;0)
  8051.      *      is promoted to 0, overvalue (&gt;array.length) results
  8052.      *      in an empty array.
  8053.      * @param endIndexExclusive  elements up to endIndex-1 are present in the
  8054.      *      returned subarray. Undervalue (&lt; startIndex) produces
  8055.      *      empty array, overvalue (&gt;array.length) is demoted to
  8056.      *      array length.
  8057.      * @return a new array containing the elements between
  8058.      *      the start and end indices.
  8059.      * @since 2.1
  8060.      * @see Arrays#copyOfRange(short[], int, int)
  8061.      */
  8062.     public static short[] subarray(final short[] array, int startIndexInclusive, int endIndexExclusive) {
  8063.         if (array == null) {
  8064.             return null;
  8065.         }
  8066.         startIndexInclusive = max0(startIndexInclusive);
  8067.         endIndexExclusive = Math.min(endIndexExclusive, array.length);
  8068.         final int newSize = endIndexExclusive - startIndexInclusive;
  8069.         if (newSize <= 0) {
  8070.             return EMPTY_SHORT_ARRAY;
  8071.         }
  8072.         return arraycopy(array, startIndexInclusive, 0, newSize, short[]::new);
  8073.     }

  8075.     /**
  8076.      * Produces a new array containing the elements between
  8077.      * the start and end indices.
  8078.      * <p>
  8079.      * The start index is inclusive, the end index exclusive.
  8080.      * Null array input produces null output.
  8081.      * </p>
  8082.      * <p>
  8083.      * The component type of the subarray is always the same as
  8084.      * that of the input array. Thus, if the input is an array of type
  8085.      * {@link Date}, the following usage is envisaged:
  8086.      * </p>
  8087.      * <pre>
  8088.      * Date[] someDates = (Date[]) ArrayUtils.subarray(allDates, 2, 5);
  8089.      * </pre>
  8090.      *
  8091.      * @param <T> the component type of the array
  8092.      * @param array  the array
  8093.      * @param startIndexInclusive  the starting index. Undervalue (&lt;0)
  8094.      *      is promoted to 0, overvalue (&gt;array.length) results
  8095.      *      in an empty array.
  8096.      * @param endIndexExclusive  elements up to endIndex-1 are present in the
  8097.      *      returned subarray. Undervalue (&lt; startIndex) produces
  8098.      *      empty array, overvalue (&gt;array.length) is demoted to
  8099.      *      array length.
  8100.      * @return a new array containing the elements between
  8101.      *      the start and end indices.
  8102.      * @since 2.1
  8103.      * @see Arrays#copyOfRange(Object[], int, int)
  8104.      */
  8105.     public static <T> T[] subarray(final T[] array, int startIndexInclusive, int endIndexExclusive) {
  8106.         if (array == null) {
  8107.             return null;
  8108.         }
  8109.         startIndexInclusive = max0(startIndexInclusive);
  8110.         endIndexExclusive = Math.min(endIndexExclusive, array.length);
  8111.         final int newSize = endIndexExclusive - startIndexInclusive;
  8112.         final Class<T> type = getComponentType(array);
  8113.         if (newSize <= 0) {
  8114.             return newInstance(type, 0);
  8115.         }
  8116.         return arraycopy(array, startIndexInclusive, 0, newSize, () -> newInstance(type, newSize));
  8117.     }

  8119.     /**
  8120.      * Swaps two elements in the given boolean array.
  8121.      *
  8122.      * <p>There is no special handling for multi-dimensional arrays. This method
  8123.      * does nothing for a {@code null} or empty input array or for overflow indices.
  8124.      * Negative indices are promoted to 0(zero).</p>
  8125.      *
  8126.      * Examples:
  8127.      * <ul>
  8128.      *     <li>ArrayUtils.swap([1, 2, 3], 0, 2) -&gt; [3, 2, 1]</li>
  8129.      *     <li>ArrayUtils.swap([1, 2, 3], 0, 0) -&gt; [1, 2, 3]</li>
  8130.      *     <li>ArrayUtils.swap([1, 2, 3], 1, 0) -&gt; [2, 1, 3]</li>
  8131.      *     <li>ArrayUtils.swap([1, 2, 3], 0, 5) -&gt; [1, 2, 3]</li>
  8132.      *     <li>ArrayUtils.swap([1, 2, 3], -1, 1) -&gt; [2, 1, 3]</li>
  8133.      * </ul>
  8134.      *
  8135.      * @param array  the array to swap, may be {@code null}
  8136.      * @param offset1 the index of the first element to swap
  8137.      * @param offset2 the index of the second element to swap
  8138.      * @since 3.5
  8139.      */
  8140.     public static void swap(final boolean[] array, final int offset1, final int offset2) {
  8141.         swap(array, offset1, offset2, 1);
  8142.     }

  8144.     /**
  8145.      * Swaps a series of elements in the given boolean array.
  8146.      *
  8147.      * <p>This method does nothing for a {@code null} or empty input array or
  8148.      * for overflow indices. Negative indices are promoted to 0(zero). If any
  8149.      * of the sub-arrays to swap falls outside of the given array, then the
  8150.      * swap is stopped at the end of the array and as many as possible elements
  8151.      * are swapped.</p>
  8152.      *
  8153.      * Examples:
  8154.      * <ul>
  8155.      *     <li>ArrayUtils.swap([true, false, true, false], 0, 2, 1) -&gt; [true, false, true, false]</li>
  8156.      *     <li>ArrayUtils.swap([true, false, true, false], 0, 0, 1) -&gt; [true, false, true, false]</li>
  8157.      *     <li>ArrayUtils.swap([true, false, true, false], 0, 2, 2) -&gt; [true, false, true, false]</li>
  8158.      *     <li>ArrayUtils.swap([true, false, true, false], -3, 2, 2) -&gt; [true, false, true, false]</li>
  8159.      *     <li>ArrayUtils.swap([true, false, true, false], 0, 3, 3) -&gt; [false, false, true, true]</li>
  8160.      * </ul>
  8161.      *
  8162.      * @param array the array to swap, may be {@code null}
  8163.      * @param offset1 the index of the first element in the series to swap
  8164.      * @param offset2 the index of the second element in the series to swap
  8165.      * @param len the number of elements to swap starting with the given indices
  8166.      * @since 3.5
  8167.      */
  8168.     public static void swap(final boolean[] array, int offset1, int offset2, int len) {
  8169.         if (isEmpty(array) || offset1 >= array.length || offset2 >= array.length) {
  8170.             return;
  8171.         }
  8172.         offset1 = max0(offset1);
  8173.         offset2 = max0(offset2);
  8174.         len = Math.min(Math.min(len, array.length - offset1), array.length - offset2);
  8175.         for (int i = 0; i < len; i++, offset1++, offset2++) {
  8176.             final boolean aux = array[offset1];
  8177.             array[offset1] = array[offset2];
  8178.             array[offset2] = aux;
  8179.         }
  8180.     }

  8182.     /**
  8183.      * Swaps two elements in the given byte array.
  8184.      *
  8185.      * <p>There is no special handling for multi-dimensional arrays. This method
  8186.      * does nothing for a {@code null} or empty input array or for overflow indices.
  8187.      * Negative indices are promoted to 0(zero).</p>
  8188.      *
  8189.      * Examples:
  8190.      * <ul>
  8191.      *     <li>ArrayUtils.swap([1, 2, 3], 0, 2) -&gt; [3, 2, 1]</li>
  8192.      *     <li>ArrayUtils.swap([1, 2, 3], 0, 0) -&gt; [1, 2, 3]</li>
  8193.      *     <li>ArrayUtils.swap([1, 2, 3], 1, 0) -&gt; [2, 1, 3]</li>
  8194.      *     <li>ArrayUtils.swap([1, 2, 3], 0, 5) -&gt; [1, 2, 3]</li>
  8195.      *     <li>ArrayUtils.swap([1, 2, 3], -1, 1) -&gt; [2, 1, 3]</li>
  8196.      * </ul>
  8197.      *
  8198.      * @param array  the array to swap, may be {@code null}
  8199.      * @param offset1 the index of the first element to swap
  8200.      * @param offset2 the index of the second element to swap
  8201.      * @since 3.5
  8202.      */
  8203.     public static void swap(final byte[] array, final int offset1, final int offset2) {
  8204.         swap(array, offset1, offset2, 1);
  8205.     }

  8207.     /**
  8208.      * Swaps a series of elements in the given byte array.
  8209.      *
  8210.      * <p>This method does nothing for a {@code null} or empty input array or
  8211.      * for overflow indices. Negative indices are promoted to 0(zero). If any
  8212.      * of the sub-arrays to swap falls outside of the given array, then the
  8213.      * swap is stopped at the end of the array and as many as possible elements
  8214.      * are swapped.</p>
  8215.      *
  8216.      * Examples:
  8217.      * <ul>
  8218.      *     <li>ArrayUtils.swap([1, 2, 3, 4], 0, 2, 1) -&gt; [3, 2, 1, 4]</li>
  8219.      *     <li>ArrayUtils.swap([1, 2, 3, 4], 0, 0, 1) -&gt; [1, 2, 3, 4]</li>
  8220.      *     <li>ArrayUtils.swap([1, 2, 3, 4], 2, 0, 2) -&gt; [3, 4, 1, 2]</li>
  8221.      *     <li>ArrayUtils.swap([1, 2, 3, 4], -3, 2, 2) -&gt; [3, 4, 1, 2]</li>
  8222.      *     <li>ArrayUtils.swap([1, 2, 3, 4], 0, 3, 3) -&gt; [4, 2, 3, 1]</li>
  8223.      * </ul>
  8224.      *
  8225.      * @param array the array to swap, may be {@code null}
  8226.      * @param offset1 the index of the first element in the series to swap
  8227.      * @param offset2 the index of the second element in the series to swap
  8228.      * @param len the number of elements to swap starting with the given indices
  8229.      * @since 3.5
  8230.      */
  8231.     public static void swap(final byte[] array, int offset1, int offset2, int len) {
  8232.         if (isEmpty(array) || offset1 >= array.length || offset2 >= array.length) {
  8233.             return;
  8234.         }
  8235.         offset1 = max0(offset1);
  8236.         offset2 = max0(offset2);
  8237.         len = Math.min(Math.min(len, array.length - offset1), array.length - offset2);
  8238.         for (int i = 0; i < len; i++, offset1++, offset2++) {
  8239.             final byte aux = array[offset1];
  8240.             array[offset1] = array[offset2];
  8241.             array[offset2] = aux;
  8242.         }
  8243.     }

  8245.     /**
  8246.      * Swaps two elements in the given char array.
  8247.      *
  8248.      * <p>There is no special handling for multi-dimensional arrays. This method
  8249.      * does nothing for a {@code null} or empty input array or for overflow indices.
  8250.      * Negative indices are promoted to 0(zero).</p>
  8251.      *
  8252.      * Examples:
  8253.      * <ul>
  8254.      *     <li>ArrayUtils.swap([1, 2, 3], 0, 2) -&gt; [3, 2, 1]</li>
  8255.      *     <li>ArrayUtils.swap([1, 2, 3], 0, 0) -&gt; [1, 2, 3]</li>
  8256.      *     <li>ArrayUtils.swap([1, 2, 3], 1, 0) -&gt; [2, 1, 3]</li>
  8257.      *     <li>ArrayUtils.swap([1, 2, 3], 0, 5) -&gt; [1, 2, 3]</li>
  8258.      *     <li>ArrayUtils.swap([1, 2, 3], -1, 1) -&gt; [2, 1, 3]</li>
  8259.      * </ul>
  8260.      *
  8261.      * @param array  the array to swap, may be {@code null}
  8262.      * @param offset1 the index of the first element to swap
  8263.      * @param offset2 the index of the second element to swap
  8264.      * @since 3.5
  8265.      */
  8266.     public static void swap(final char[] array, final int offset1, final int offset2) {
  8267.         swap(array, offset1, offset2, 1);
  8268.     }

  8270.     /**
  8271.      * Swaps a series of elements in the given char array.
  8272.      *
  8273.      * <p>This method does nothing for a {@code null} or empty input array or
  8274.      * for overflow indices. Negative indices are promoted to 0(zero). If any
  8275.      * of the sub-arrays to swap falls outside of the given array, then the
  8276.      * swap is stopped at the end of the array and as many as possible elements
  8277.      * are swapped.</p>
  8278.      *
  8279.      * Examples:
  8280.      * <ul>
  8281.      *     <li>ArrayUtils.swap([1, 2, 3, 4], 0, 2, 1) -&gt; [3, 2, 1, 4]</li>
  8282.      *     <li>ArrayUtils.swap([1, 2, 3, 4], 0, 0, 1) -&gt; [1, 2, 3, 4]</li>
  8283.      *     <li>ArrayUtils.swap([1, 2, 3, 4], 2, 0, 2) -&gt; [3, 4, 1, 2]</li>
  8284.      *     <li>ArrayUtils.swap([1, 2, 3, 4], -3, 2, 2) -&gt; [3, 4, 1, 2]</li>
  8285.      *     <li>ArrayUtils.swap([1, 2, 3, 4], 0, 3, 3) -&gt; [4, 2, 3, 1]</li>
  8286.      * </ul>
  8287.      *
  8288.      * @param array the array to swap, may be {@code null}
  8289.      * @param offset1 the index of the first element in the series to swap
  8290.      * @param offset2 the index of the second element in the series to swap
  8291.      * @param len the number of elements to swap starting with the given indices
  8292.      * @since 3.5
  8293.      */
  8294.     public static void swap(final char[] array, int offset1, int offset2, int len) {
  8295.         if (isEmpty(array) || offset1 >= array.length || offset2 >= array.length) {
  8296.             return;
  8297.         }
  8298.         offset1 = max0(offset1);
  8299.         offset2 = max0(offset2);
  8300.         len = Math.min(Math.min(len, array.length - offset1), array.length - offset2);
  8301.         for (int i = 0; i < len; i++, offset1++, offset2++) {
  8302.             final char aux = array[offset1];
  8303.             array[offset1] = array[offset2];
  8304.             array[offset2] = aux;
  8305.         }
  8306.     }

  8308.     /**
  8309.      * Swaps two elements in the given double array.
  8310.      *
  8311.      * <p>There is no special handling for multi-dimensional arrays. This method
  8312.      * does nothing for a {@code null} or empty input array or for overflow indices.
  8313.      * Negative indices are promoted to 0(zero).</p>
  8314.      *
  8315.      * Examples:
  8316.      * <ul>
  8317.      *     <li>ArrayUtils.swap([1, 2, 3], 0, 2) -&gt; [3, 2, 1]</li>
  8318.      *     <li>ArrayUtils.swap([1, 2, 3], 0, 0) -&gt; [1, 2, 3]</li>
  8319.      *     <li>ArrayUtils.swap([1, 2, 3], 1, 0) -&gt; [2, 1, 3]</li>
  8320.      *     <li>ArrayUtils.swap([1, 2, 3], 0, 5) -&gt; [1, 2, 3]</li>
  8321.      *     <li>ArrayUtils.swap([1, 2, 3], -1, 1) -&gt; [2, 1, 3]</li>
  8322.      * </ul>
  8323.      *
  8324.      * @param array  the array to swap, may be {@code null}
  8325.      * @param offset1 the index of the first element to swap
  8326.      * @param offset2 the index of the second element to swap
  8327.      * @since 3.5
  8328.      */
  8329.     public static void swap(final double[] array, final int offset1, final int offset2) {
  8330.         swap(array, offset1, offset2, 1);
  8331.     }

  8333.     /**
  8334.      * Swaps a series of elements in the given double array.
  8335.      *
  8336.      * <p>This method does nothing for a {@code null} or empty input array or
  8337.      * for overflow indices. Negative indices are promoted to 0(zero). If any
  8338.      * of the sub-arrays to swap falls outside of the given array, then the
  8339.      * swap is stopped at the end of the array and as many as possible elements
  8340.      * are swapped.</p>
  8341.      *
  8342.      * Examples:
  8343.      * <ul>
  8344.      *     <li>ArrayUtils.swap([1, 2, 3, 4], 0, 2, 1) -&gt; [3, 2, 1, 4]</li>
  8345.      *     <li>ArrayUtils.swap([1, 2, 3, 4], 0, 0, 1) -&gt; [1, 2, 3, 4]</li>
  8346.      *     <li>ArrayUtils.swap([1, 2, 3, 4], 2, 0, 2) -&gt; [3, 4, 1, 2]</li>
  8347.      *     <li>ArrayUtils.swap([1, 2, 3, 4], -3, 2, 2) -&gt; [3, 4, 1, 2]</li>
  8348.      *     <li>ArrayUtils.swap([1, 2, 3, 4], 0, 3, 3) -&gt; [4, 2, 3, 1]</li>
  8349.      * </ul>
  8350.      *
  8351.      * @param array the array to swap, may be {@code null}
  8352.      * @param offset1 the index of the first element in the series to swap
  8353.      * @param offset2 the index of the second element in the series to swap
  8354.      * @param len the number of elements to swap starting with the given indices
  8355.      * @since 3.5
  8356.      */
  8357.     public static void swap(final double[] array,  int offset1, int offset2, int len) {
  8358.         if (isEmpty(array) || offset1 >= array.length || offset2 >= array.length) {
  8359.             return;
  8360.         }
  8361.         offset1 = max0(offset1);
  8362.         offset2 = max0(offset2);
  8363.         len = Math.min(Math.min(len, array.length - offset1), array.length - offset2);
  8364.         for (int i = 0; i < len; i++, offset1++, offset2++) {
  8365.             final double aux = array[offset1];
  8366.             array[offset1] = array[offset2];
  8367.             array[offset2] = aux;
  8368.         }
  8369.     }

  8371.     /**
  8372.      * Swaps two elements in the given float array.
  8373.      *
  8374.      * <p>There is no special handling for multi-dimensional arrays. This method
  8375.      * does nothing for a {@code null} or empty input array or for overflow indices.
  8376.      * Negative indices are promoted to 0(zero).</p>
  8377.      *
  8378.      * Examples:
  8379.      * <ul>
  8380.      *     <li>ArrayUtils.swap([1, 2, 3], 0, 2) -&gt; [3, 2, 1]</li>
  8381.      *     <li>ArrayUtils.swap([1, 2, 3], 0, 0) -&gt; [1, 2, 3]</li>
  8382.      *     <li>ArrayUtils.swap([1, 2, 3], 1, 0) -&gt; [2, 1, 3]</li>
  8383.      *     <li>ArrayUtils.swap([1, 2, 3], 0, 5) -&gt; [1, 2, 3]</li>
  8384.      *     <li>ArrayUtils.swap([1, 2, 3], -1, 1) -&gt; [2, 1, 3]</li>
  8385.      * </ul>
  8386.      *
  8387.      * @param array  the array to swap, may be {@code null}
  8388.      * @param offset1 the index of the first element to swap
  8389.      * @param offset2 the index of the second element to swap
  8390.      * @since 3.5
  8391.      */
  8392.     public static void swap(final float[] array, final int offset1, final int offset2) {
  8393.         swap(array, offset1, offset2, 1);
  8394.     }

  8396.     /**
  8397.      * Swaps a series of elements in the given float array.
  8398.      *
  8399.      * <p>This method does nothing for a {@code null} or empty input array or
  8400.      * for overflow indices. Negative indices are promoted to 0(zero). If any
  8401.      * of the sub-arrays to swap falls outside of the given array, then the
  8402.      * swap is stopped at the end of the array and as many as possible elements
  8403.      * are swapped.</p>
  8404.      *
  8405.      * Examples:
  8406.      * <ul>
  8407.      *     <li>ArrayUtils.swap([1, 2, 3, 4], 0, 2, 1) -&gt; [3, 2, 1, 4]</li>
  8408.      *     <li>ArrayUtils.swap([1, 2, 3, 4], 0, 0, 1) -&gt; [1, 2, 3, 4]</li>
  8409.      *     <li>ArrayUtils.swap([1, 2, 3, 4], 2, 0, 2) -&gt; [3, 4, 1, 2]</li>
  8410.      *     <li>ArrayUtils.swap([1, 2, 3, 4], -3, 2, 2) -&gt; [3, 4, 1, 2]</li>
  8411.      *     <li>ArrayUtils.swap([1, 2, 3, 4], 0, 3, 3) -&gt; [4, 2, 3, 1]</li>
  8412.      * </ul>
  8413.      *
  8414.      * @param array the array to swap, may be {@code null}
  8415.      * @param offset1 the index of the first element in the series to swap
  8416.      * @param offset2 the index of the second element in the series to swap
  8417.      * @param len the number of elements to swap starting with the given indices
  8418.      * @since 3.5
  8419.      */
  8420.     public static void swap(final float[] array, int offset1, int offset2, int len) {
  8421.         if (isEmpty(array) || offset1 >= array.length || offset2 >= array.length) {
  8422.             return;
  8423.         }
  8424.         offset1 = max0(offset1);
  8425.         offset2 = max0(offset2);
  8426.         len = Math.min(Math.min(len, array.length - offset1), array.length - offset2);
  8427.         for (int i = 0; i < len; i++, offset1++, offset2++) {
  8428.             final float aux = array[offset1];
  8429.             array[offset1] = array[offset2];
  8430.             array[offset2] = aux;
  8431.         }

  8433.     }

  8435.     /**
  8436.      * Swaps two elements in the given int array.
  8437.      *
  8438.      * <p>There is no special handling for multi-dimensional arrays. This method
  8439.      * does nothing for a {@code null} or empty input array or for overflow indices.
  8440.      * Negative indices are promoted to 0(zero).</p>
  8441.      *
  8442.      * Examples:
  8443.      * <ul>
  8444.      *     <li>ArrayUtils.swap([1, 2, 3], 0, 2) -&gt; [3, 2, 1]</li>
  8445.      *     <li>ArrayUtils.swap([1, 2, 3], 0, 0) -&gt; [1, 2, 3]</li>
  8446.      *     <li>ArrayUtils.swap([1, 2, 3], 1, 0) -&gt; [2, 1, 3]</li>
  8447.      *     <li>ArrayUtils.swap([1, 2, 3], 0, 5) -&gt; [1, 2, 3]</li>
  8448.      *     <li>ArrayUtils.swap([1, 2, 3], -1, 1) -&gt; [2, 1, 3]</li>
  8449.      * </ul>
  8450.      *
  8451.      * @param array  the array to swap, may be {@code null}
  8452.      * @param offset1 the index of the first element to swap
  8453.      * @param offset2 the index of the second element to swap
  8454.      * @since 3.5
  8455.      */
  8456.     public static void swap(final int[] array, final int offset1, final int offset2) {
  8457.         swap(array, offset1, offset2, 1);
  8458.     }

  8460.     /**
  8461.      * Swaps a series of elements in the given int array.
  8462.      *
  8463.      * <p>This method does nothing for a {@code null} or empty input array or
  8464.      * for overflow indices. Negative indices are promoted to 0(zero). If any
  8465.      * of the sub-arrays to swap falls outside of the given array, then the
  8466.      * swap is stopped at the end of the array and as many as possible elements
  8467.      * are swapped.</p>
  8468.      *
  8469.      * Examples:
  8470.      * <ul>
  8471.      *     <li>ArrayUtils.swap([1, 2, 3, 4], 0, 2, 1) -&gt; [3, 2, 1, 4]</li>
  8472.      *     <li>ArrayUtils.swap([1, 2, 3, 4], 0, 0, 1) -&gt; [1, 2, 3, 4]</li>
  8473.      *     <li>ArrayUtils.swap([1, 2, 3, 4], 2, 0, 2) -&gt; [3, 4, 1, 2]</li>
  8474.      *     <li>ArrayUtils.swap([1, 2, 3, 4], -3, 2, 2) -&gt; [3, 4, 1, 2]</li>
  8475.      *     <li>ArrayUtils.swap([1, 2, 3, 4], 0, 3, 3) -&gt; [4, 2, 3, 1]</li>
  8476.      * </ul>
  8477.      *
  8478.      * @param array the array to swap, may be {@code null}
  8479.      * @param offset1 the index of the first element in the series to swap
  8480.      * @param offset2 the index of the second element in the series to swap
  8481.      * @param len the number of elements to swap starting with the given indices
  8482.      * @since 3.5
  8483.      */
  8484.     public static void swap(final int[] array,  int offset1, int offset2, int len) {
  8485.         if (isEmpty(array) || offset1 >= array.length || offset2 >= array.length) {
  8486.             return;
  8487.         }
  8488.         offset1 = max0(offset1);
  8489.         offset2 = max0(offset2);
  8490.         len = Math.min(Math.min(len, array.length - offset1), array.length - offset2);
  8491.         for (int i = 0; i < len; i++, offset1++, offset2++) {
  8492.             final int aux = array[offset1];
  8493.             array[offset1] = array[offset2];
  8494.             array[offset2] = aux;
  8495.         }
  8496.     }

  8498.     /**
  8499.      * Swaps two elements in the given long array.
  8500.      *
  8501.      * <p>There is no special handling for multi-dimensional arrays. This method
  8502.      * does nothing for a {@code null} or empty input array or for overflow indices.
  8503.      * Negative indices are promoted to 0(zero).</p>
  8504.      *
  8505.      * Examples:
  8506.      * <ul>
  8507.      *     <li>ArrayUtils.swap([true, false, true], 0, 2) -&gt; [true, false, true]</li>
  8508.      *     <li>ArrayUtils.swap([true, false, true], 0, 0) -&gt; [true, false, true]</li>
  8509.      *     <li>ArrayUtils.swap([true, false, true], 1, 0) -&gt; [false, true, true]</li>
  8510.      *     <li>ArrayUtils.swap([true, false, true], 0, 5) -&gt; [true, false, true]</li>
  8511.      *     <li>ArrayUtils.swap([true, false, true], -1, 1) -&gt; [false, true, true]</li>
  8512.      * </ul>
  8513.      *
  8514.      * @param array  the array to swap, may be {@code null}
  8515.      * @param offset1 the index of the first element to swap
  8516.      * @param offset2 the index of the second element to swap
  8517.      * @since 3.5
  8518.      */
  8519.     public static void swap(final long[] array, final int offset1, final int offset2) {
  8520.         swap(array, offset1, offset2, 1);
  8521.     }

  8523.     /**
  8524.      * Swaps a series of elements in the given long array.
  8525.      *
  8526.      * <p>This method does nothing for a {@code null} or empty input array or
  8527.      * for overflow indices. Negative indices are promoted to 0(zero). If any
  8528.      * of the sub-arrays to swap falls outside of the given array, then the
  8529.      * swap is stopped at the end of the array and as many as possible elements
  8530.      * are swapped.</p>
  8531.      *
  8532.      * Examples:
  8533.      * <ul>
  8534.      *     <li>ArrayUtils.swap([1, 2, 3, 4], 0, 2, 1) -&gt; [3, 2, 1, 4]</li>
  8535.      *     <li>ArrayUtils.swap([1, 2, 3, 4], 0, 0, 1) -&gt; [1, 2, 3, 4]</li>
  8536.      *     <li>ArrayUtils.swap([1, 2, 3, 4], 2, 0, 2) -&gt; [3, 4, 1, 2]</li>
  8537.      *     <li>ArrayUtils.swap([1, 2, 3, 4], -3, 2, 2) -&gt; [3, 4, 1, 2]</li>
  8538.      *     <li>ArrayUtils.swap([1, 2, 3, 4], 0, 3, 3) -&gt; [4, 2, 3, 1]</li>
  8539.      * </ul>
  8540.      *
  8541.      * @param array the array to swap, may be {@code null}
  8542.      * @param offset1 the index of the first element in the series to swap
  8543.      * @param offset2 the index of the second element in the series to swap
  8544.      * @param len the number of elements to swap starting with the given indices
  8545.      * @since 3.5
  8546.      */
  8547.     public static void swap(final long[] array,  int offset1, int offset2, int len) {
  8548.         if (isEmpty(array) || offset1 >= array.length || offset2 >= array.length) {
  8549.             return;
  8550.         }
  8551.         offset1 = max0(offset1);
  8552.         offset2 = max0(offset2);
  8553.         len = Math.min(Math.min(len, array.length - offset1), array.length - offset2);
  8554.         for (int i = 0; i < len; i++, offset1++, offset2++) {
  8555.             final long aux = array[offset1];
  8556.             array[offset1] = array[offset2];
  8557.             array[offset2] = aux;
  8558.         }
  8559.     }

  8561.     /**
  8562.      * Swaps two elements in the given array.
  8563.      *
  8564.      * <p>There is no special handling for multi-dimensional arrays. This method
  8565.      * does nothing for a {@code null} or empty input array or for overflow indices.
  8566.      * Negative indices are promoted to 0(zero).</p>
  8567.      *
  8568.      * Examples:
  8569.      * <ul>
  8570.      *     <li>ArrayUtils.swap(["1", "2", "3"], 0, 2) -&gt; ["3", "2", "1"]</li>
  8571.      *     <li>ArrayUtils.swap(["1", "2", "3"], 0, 0) -&gt; ["1", "2", "3"]</li>
  8572.      *     <li>ArrayUtils.swap(["1", "2", "3"], 1, 0) -&gt; ["2", "1", "3"]</li>
  8573.      *     <li>ArrayUtils.swap(["1", "2", "3"], 0, 5) -&gt; ["1", "2", "3"]</li>
  8574.      *     <li>ArrayUtils.swap(["1", "2", "3"], -1, 1) -&gt; ["2", "1", "3"]</li>
  8575.      * </ul>
  8576.      *
  8577.      * @param array the array to swap, may be {@code null}
  8578.      * @param offset1 the index of the first element to swap
  8579.      * @param offset2 the index of the second element to swap
  8580.      * @since 3.5
  8581.      */
  8582.     public static void swap(final Object[] array, final int offset1, final int offset2) {
  8583.         swap(array, offset1, offset2, 1);
  8584.     }

  8586.     /**
  8587.      * Swaps a series of elements in the given array.
  8588.      *
  8589.      * <p>This method does nothing for a {@code null} or empty input array or
  8590.      * for overflow indices. Negative indices are promoted to 0(zero). If any
  8591.      * of the sub-arrays to swap falls outside of the given array, then the
  8592.      * swap is stopped at the end of the array and as many as possible elements
  8593.      * are swapped.</p>
  8594.      *
  8595.      * Examples:
  8596.      * <ul>
  8597.      *     <li>ArrayUtils.swap(["1", "2", "3", "4"], 0, 2, 1) -&gt; ["3", "2", "1", "4"]</li>
  8598.      *     <li>ArrayUtils.swap(["1", "2", "3", "4"], 0, 0, 1) -&gt; ["1", "2", "3", "4"]</li>
  8599.      *     <li>ArrayUtils.swap(["1", "2", "3", "4"], 2, 0, 2) -&gt; ["3", "4", "1", "2"]</li>
  8600.      *     <li>ArrayUtils.swap(["1", "2", "3", "4"], -3, 2, 2) -&gt; ["3", "4", "1", "2"]</li>
  8601.      *     <li>ArrayUtils.swap(["1", "2", "3", "4"], 0, 3, 3) -&gt; ["4", "2", "3", "1"]</li>
  8602.      * </ul>
  8603.      *
  8604.      * @param array the array to swap, may be {@code null}
  8605.      * @param offset1 the index of the first element in the series to swap
  8606.      * @param offset2 the index of the second element in the series to swap
  8607.      * @param len the number of elements to swap starting with the given indices
  8608.      * @since 3.5
  8609.      */
  8610.     public static void swap(final Object[] array,  int offset1, int offset2, int len) {
  8611.         if (isEmpty(array) || offset1 >= array.length || offset2 >= array.length) {
  8612.             return;
  8613.         }
  8614.         offset1 = max0(offset1);
  8615.         offset2 = max0(offset2);
  8616.         len = Math.min(Math.min(len, array.length - offset1), array.length - offset2);
  8617.         for (int i = 0; i < len; i++, offset1++, offset2++) {
  8618.             final Object aux = array[offset1];
  8619.             array[offset1] = array[offset2];
  8620.             array[offset2] = aux;
  8621.         }
  8622.     }

  8624.     /**
  8625.      * Swaps two elements in the given short array.
  8626.      *
  8627.      * <p>There is no special handling for multi-dimensional arrays. This method
  8628.      * does nothing for a {@code null} or empty input array or for overflow indices.
  8629.      * Negative indices are promoted to 0(zero).</p>
  8630.      *
  8631.      * Examples:
  8632.      * <ul>
  8633.      *     <li>ArrayUtils.swap([1, 2, 3], 0, 2) -&gt; [3, 2, 1]</li>
  8634.      *     <li>ArrayUtils.swap([1, 2, 3], 0, 0) -&gt; [1, 2, 3]</li>
  8635.      *     <li>ArrayUtils.swap([1, 2, 3], 1, 0) -&gt; [2, 1, 3]</li>
  8636.      *     <li>ArrayUtils.swap([1, 2, 3], 0, 5) -&gt; [1, 2, 3]</li>
  8637.      *     <li>ArrayUtils.swap([1, 2, 3], -1, 1) -&gt; [2, 1, 3]</li>
  8638.      * </ul>
  8639.      *
  8640.      * @param array  the array to swap, may be {@code null}
  8641.      * @param offset1 the index of the first element to swap
  8642.      * @param offset2 the index of the second element to swap
  8643.      * @since 3.5
  8644.      */
  8645.     public static void swap(final short[] array, final int offset1, final int offset2) {
  8646.         swap(array, offset1, offset2, 1);
  8647.     }

  8649.     /**
  8650.      * Swaps a series of elements in the given short array.
  8651.      *
  8652.      * <p>This method does nothing for a {@code null} or empty input array or
  8653.      * for overflow indices. Negative indices are promoted to 0(zero). If any
  8654.      * of the sub-arrays to swap falls outside of the given array, then the
  8655.      * swap is stopped at the end of the array and as many as possible elements
  8656.      * are swapped.</p>
  8657.      *
  8658.      * Examples:
  8659.      * <ul>
  8660.      *     <li>ArrayUtils.swap([1, 2, 3, 4], 0, 2, 1) -&gt; [3, 2, 1, 4]</li>
  8661.      *     <li>ArrayUtils.swap([1, 2, 3, 4], 0, 0, 1) -&gt; [1, 2, 3, 4]</li>
  8662.      *     <li>ArrayUtils.swap([1, 2, 3, 4], 2, 0, 2) -&gt; [3, 4, 1, 2]</li>
  8663.      *     <li>ArrayUtils.swap([1, 2, 3, 4], -3, 2, 2) -&gt; [3, 4, 1, 2]</li>
  8664.      *     <li>ArrayUtils.swap([1, 2, 3, 4], 0, 3, 3) -&gt; [4, 2, 3, 1]</li>
  8665.      * </ul>
  8666.      *
  8667.      * @param array the array to swap, may be {@code null}
  8668.      * @param offset1 the index of the first element in the series to swap
  8669.      * @param offset2 the index of the second element in the series to swap
  8670.      * @param len the number of elements to swap starting with the given indices
  8671.      * @since 3.5
  8672.      */
  8673.     public static void swap(final short[] array, int offset1, int offset2, int len) {
  8674.         if (isEmpty(array) || offset1 >= array.length || offset2 >= array.length) {
  8675.             return;
  8676.         }
  8677.         offset1 = max0(offset1);
  8678.         offset2 = max0(offset2);
  8679.         if (offset1 == offset2) {
  8680.             return;
  8681.         }
  8682.         len = Math.min(Math.min(len, array.length - offset1), array.length - offset2);
  8683.         for (int i = 0; i < len; i++, offset1++, offset2++) {
  8684.             final short aux = array[offset1];
  8685.             array[offset1] = array[offset2];
  8686.             array[offset2] = aux;
  8687.         }
  8688.     }

  8690.     /**
  8691.      * Create a type-safe generic array.
  8692.      * <p>
  8693.      * The Java language does not allow an array to be created from a generic type:
  8694.      * </p>
  8695.      * <pre>
  8696.     public static &lt;T&gt; T[] createAnArray(int size) {
  8697.         return new T[size]; // compiler error here
  8698.     }
  8699.     public static &lt;T&gt; T[] createAnArray(int size) {
  8700.         return (T[]) new Object[size]; // ClassCastException at runtime
  8701.     }
  8702.      * </pre>
  8703.      * <p>
  8704.      * Therefore new arrays of generic types can be created with this method.
  8705.      * For example, an array of Strings can be created:
  8706.      * </p>
  8707.      * <pre>{@code
  8708.      * String[] array = ArrayUtils.toArray("1", "2");
  8709.      * String[] emptyArray = ArrayUtils.<String>toArray();
  8710.      * }</pre>
  8711.      * <p>
  8712.      * The method is typically used in scenarios, where the caller itself uses generic types
  8713.      * that have to be combined into an array.
  8714.      * </p>
  8715.      * <p>
  8716.      * Note, this method makes only sense to provide arguments of the same type so that the
  8717.      * compiler can deduce the type of the array itself. While it is possible to select the
  8718.      * type explicitly like in
  8719.      * {@code Number[] array = ArrayUtils.<Number>toArray(Integer.valueOf(42), Double.valueOf(Math.PI))},
  8720.      * there is no real advantage when compared to
  8721.      * {@code new Number[] {Integer.valueOf(42), Double.valueOf(Math.PI)}}.
  8722.      * </p>
  8723.      *
  8724.      * @param  <T>   the array's element type
  8725.      * @param  items  the varargs array items, null allowed
  8726.      * @return the array, not null unless a null array is passed in
  8727.      * @since 3.0
  8728.      */
  8729.     public static <T> T[] toArray(@SuppressWarnings("unchecked") final T... items) {
  8730.         return items;
  8731.     }

  8733.     /**
  8734.      * Converts the given array into a {@link java.util.Map}. Each element of the array
  8735.      * must be either a {@link java.util.Map.Entry} or an Array, containing at least two
  8736.      * elements, where the first element is used as key and the second as
  8737.      * value.
  8738.      * <p>
  8739.      * This method can be used to initialize:
  8740.      * </p>
  8741.      * <pre>
  8742.      * // Create a Map mapping colors.
  8743.      * Map colorMap = ArrayUtils.toMap(new String[][] {
  8744.      *     {"RED", "#FF0000"},
  8745.      *     {"GREEN", "#00FF00"},
  8746.      *     {"BLUE", "#0000FF"}});
  8747.      * </pre>
  8748.      * <p>
  8749.      * This method returns {@code null} for a {@code null} input array.
  8750.      * </p>
  8751.      *
  8752.      * @param array  an array whose elements are either a {@link java.util.Map.Entry} or
  8753.      *  an Array containing at least two elements, may be {@code null}
  8754.      * @return a {@link Map} that was created from the array
  8755.      * @throws IllegalArgumentException  if one element of this Array is
  8756.      *  itself an Array containing less than two elements
  8757.      * @throws IllegalArgumentException  if the array contains elements other
  8758.      *  than {@link java.util.Map.Entry} and an Array
  8759.      */
  8760.     public static Map<Object, Object> toMap(final Object[] array) {
  8761.         if (array == null) {
  8762.             return null;
  8763.         }
  8764.         final Map<Object, Object> map = new HashMap<>((int) (array.length * 1.5));
  8765.         for (int i = 0; i < array.length; i++) {
  8766.             final Object object = array[i];
  8767.             if (object instanceof Map.Entry<?, ?>) {
  8768.                 final Map.Entry<?, ?> entry = (Map.Entry<?, ?>) object;
  8769.                 map.put(entry.getKey(), entry.getValue());
  8770.             } else if (object instanceof Object[]) {
  8771.                 final Object[] entry = (Object[]) object;
  8772.                 if (entry.length < 2) {
  8773.                     throw new IllegalArgumentException("Array element " + i + ", '"
  8774.                         + object
  8775.                         + "', has a length less than 2");
  8776.                 }
  8777.                 map.put(entry[0], entry[1]);
  8778.             } else {
  8779.                 throw new IllegalArgumentException("Array element " + i + ", '"
  8780.                         + object
  8781.                         + "', is neither of type Map.Entry nor an Array");
  8782.             }
  8783.         }
  8784.         return map;
  8785.     }

  8787.     /**
  8788.      * Converts an array of primitive booleans to objects.
  8789.      *
  8790.      * <p>This method returns {@code null} for a {@code null} input array.</p>
  8791.      *
  8792.      * @param array  a {@code boolean} array
  8793.      * @return a {@link Boolean} array, {@code null} if null array input
  8794.      */
  8795.     public static Boolean[] toObject(final boolean[] array) {
  8796.         if (array == null) {
  8797.             return null;
  8798.         }
  8799.         if (array.length == 0) {
  8800.             return EMPTY_BOOLEAN_OBJECT_ARRAY;
  8801.         }
  8802.         final Boolean[] result = new Boolean[array.length];
  8803.         return setAll(result, i -> array[i] ? Boolean.TRUE : Boolean.FALSE);
  8804.     }

  8806.     /**
  8807.      * Converts an array of primitive bytes to objects.
  8808.      *
  8809.      * <p>This method returns {@code null} for a {@code null} input array.</p>
  8810.      *
  8811.      * @param array  a {@code byte} array
  8812.      * @return a {@link Byte} array, {@code null} if null array input
  8813.      */
  8814.     public static Byte[] toObject(final byte[] array) {
  8815.         if (array == null) {
  8816.             return null;
  8817.         }
  8818.         if (array.length == 0) {
  8819.             return EMPTY_BYTE_OBJECT_ARRAY;
  8820.         }
  8821.         return setAll(new Byte[array.length], i -> Byte.valueOf(array[i]));
  8822.     }

  8824.     /**
  8825.      * Converts an array of primitive chars to objects.
  8826.      *
  8827.      * <p>This method returns {@code null} for a {@code null} input array.</p>
  8828.      *
  8829.      * @param array a {@code char} array
  8830.      * @return a {@link Character} array, {@code null} if null array input
  8831.      */
  8832.     public static Character[] toObject(final char[] array) {
  8833.         if (array == null) {
  8834.             return null;
  8835.         }
  8836.         if (array.length == 0) {
  8837.             return EMPTY_CHARACTER_OBJECT_ARRAY;
  8838.         }
  8839.         return setAll(new Character[array.length], i -> Character.valueOf(array[i]));
  8840.      }

  8842.     /**
  8843.      * Converts an array of primitive doubles to objects.
  8844.      *
  8845.      * <p>This method returns {@code null} for a {@code null} input array.</p>
  8846.      *
  8847.      * @param array  a {@code double} array
  8848.      * @return a {@link Double} array, {@code null} if null array input
  8849.      */
  8850.     public static Double[] toObject(final double[] array) {
  8851.         if (array == null) {
  8852.             return null;
  8853.         }
  8854.         if (array.length == 0) {
  8855.             return EMPTY_DOUBLE_OBJECT_ARRAY;
  8856.         }
  8857.         return setAll(new Double[array.length], i -> Double.valueOf(array[i]));
  8858.     }

  8860.     /**
  8861.      * Converts an array of primitive floats to objects.
  8862.      *
  8863.      * <p>This method returns {@code null} for a {@code null} input array.</p>
  8864.      *
  8865.      * @param array  a {@code float} array
  8866.      * @return a {@link Float} array, {@code null} if null array input
  8867.      */
  8868.     public static Float[] toObject(final float[] array) {
  8869.         if (array == null) {
  8870.             return null;
  8871.         }
  8872.         if (array.length == 0) {
  8873.             return EMPTY_FLOAT_OBJECT_ARRAY;
  8874.         }
  8875.         return setAll(new Float[array.length], i -> Float.valueOf(array[i]));
  8876.     }

  8878.     /**
  8879.      * Converts an array of primitive ints to objects.
  8880.      *
  8881.      * <p>This method returns {@code null} for a {@code null} input array.</p>
  8882.      *
  8883.      * @param array  an {@code int} array
  8884.      * @return an {@link Integer} array, {@code null} if null array input
  8885.      */
  8886.     public static Integer[] toObject(final int[] array) {
  8887.         if (array == null) {
  8888.             return null;
  8889.         }
  8890.         if (array.length == 0) {
  8891.             return EMPTY_INTEGER_OBJECT_ARRAY;
  8892.         }
  8893.         return setAll(new Integer[array.length], i -> Integer.valueOf(array[i]));
  8894.     }

  8896.     /**
  8897.      * Converts an array of primitive longs to objects.
  8898.      *
  8899.      * <p>This method returns {@code null} for a {@code null} input array.</p>
  8900.      *
  8901.      * @param array  a {@code long} array
  8902.      * @return a {@link Long} array, {@code null} if null array input
  8903.      */
  8904.     public static Long[] toObject(final long[] array) {
  8905.         if (array == null) {
  8906.             return null;
  8907.         }
  8908.         if (array.length == 0) {
  8909.             return EMPTY_LONG_OBJECT_ARRAY;
  8910.         }
  8911.         return setAll(new Long[array.length], i -> Long.valueOf(array[i]));
  8912.     }

  8914.     /**
  8915.      * Converts an array of primitive shorts to objects.
  8916.      *
  8917.      * <p>This method returns {@code null} for a {@code null} input array.</p>
  8918.      *
  8919.      * @param array  a {@code short} array
  8920.      * @return a {@link Short} array, {@code null} if null array input
  8921.      */
  8922.     public static Short[] toObject(final short[] array) {
  8923.         if (array == null) {
  8924.             return null;
  8925.         }
  8926.         if (array.length == 0) {
  8927.             return EMPTY_SHORT_OBJECT_ARRAY;
  8928.         }
  8929.         return setAll(new Short[array.length], i -> Short.valueOf(array[i]));
  8930.     }

  8932.     /**
  8933.      * Converts an array of object Booleans to primitives.
  8934.      * <p>
  8935.      * This method returns {@code null} for a {@code null} input array.
  8936.      * </p>
  8937.      * <p>
  8938.      * Null array elements map to false, like {@code Boolean.parseBoolean(null)} and its callers return false.
  8939.      * </p>
  8940.      *
  8941.      * @param array a {@link Boolean} array, may be {@code null}
  8942.      * @return a {@code boolean} array, {@code null} if null array input
  8943.      */
  8944.     public static boolean[] toPrimitive(final Boolean[] array) {
  8945.         return toPrimitive(array, false);
  8946.     }

  8948.     /**
  8949.      * Converts an array of object Booleans to primitives handling {@code null}.
  8950.      * <p>
  8951.      * This method returns {@code null} for a {@code null} input array.
  8952.      * </p>
  8953.      *
  8954.      * @param array  a {@link Boolean} array, may be {@code null}
  8955.      * @param valueForNull  the value to insert if {@code null} found
  8956.      * @return a {@code boolean} array, {@code null} if null array input
  8957.      */
  8958.     public static boolean[] toPrimitive(final Boolean[] array, final boolean valueForNull) {
  8959.         if (array == null) {
  8960.             return null;
  8961.         }
  8962.         if (array.length == 0) {
  8963.             return EMPTY_BOOLEAN_ARRAY;
  8964.         }
  8965.         final boolean[] result = new boolean[array.length];
  8966.         for (int i = 0; i < array.length; i++) {
  8967.             final Boolean b = array[i];
  8968.             result[i] = b == null ? valueForNull : b.booleanValue();
  8969.         }
  8970.         return result;
  8971.     }

  8973.     /**
  8974.      * Converts an array of object Bytes to primitives.
  8975.      * <p>
  8976.      * This method returns {@code null} for a {@code null} input array.
  8977.      * </p>
  8978.      *
  8979.      * @param array  a {@link Byte} array, may be {@code null}
  8980.      * @return a {@code byte} array, {@code null} if null array input
  8981.      * @throws NullPointerException if an array element is {@code null}
  8982.      */
  8983.     public static byte[] toPrimitive(final Byte[] array) {
  8984.         if (array == null) {
  8985.             return null;
  8986.         }
  8987.         if (array.length == 0) {
  8988.             return EMPTY_BYTE_ARRAY;
  8989.         }
  8990.         final byte[] result = new byte[array.length];
  8991.         for (int i = 0; i < array.length; i++) {
  8992.             result[i] = array[i].byteValue();
  8993.         }
  8994.         return result;
  8995.     }

  8997.     /**
  8998.      * Converts an array of object Bytes to primitives handling {@code null}.
  8999.      * <p>
  9000.      * This method returns {@code null} for a {@code null} input array.
  9001.      * </p>
  9002.      *
  9003.      * @param array  a {@link Byte} array, may be {@code null}
  9004.      * @param valueForNull  the value to insert if {@code null} found
  9005.      * @return a {@code byte} array, {@code null} if null array input
  9006.      */
  9007.     public static byte[] toPrimitive(final Byte[] array, final byte valueForNull) {
  9008.         if (array == null) {
  9009.             return null;
  9010.         }
  9011.         if (array.length == 0) {
  9012.             return EMPTY_BYTE_ARRAY;
  9013.         }
  9014.         final byte[] result = new byte[array.length];
  9015.         for (int i = 0; i < array.length; i++) {
  9016.             final Byte b = array[i];
  9017.             result[i] = b == null ? valueForNull : b.byteValue();
  9018.         }
  9019.         return result;
  9020.     }

  9022.     /**
  9023.      * Converts an array of object Characters to primitives.
  9024.      * <p>
  9025.      * This method returns {@code null} for a {@code null} input array.
  9026.      * </p>
  9027.      *
  9028.      * @param array  a {@link Character} array, may be {@code null}
  9029.      * @return a {@code char} array, {@code null} if null array input
  9030.      * @throws NullPointerException if an array element is {@code null}
  9031.      */
  9032.     public static char[] toPrimitive(final Character[] array) {
  9033.         if (array == null) {
  9034.             return null;
  9035.         }
  9036.         if (array.length == 0) {
  9037.             return EMPTY_CHAR_ARRAY;
  9038.         }
  9039.         final char[] result = new char[array.length];
  9040.         for (int i = 0; i < array.length; i++) {
  9041.             result[i] = array[i].charValue();
  9042.         }
  9043.         return result;
  9044.     }

  9046.     /**
  9047.      * Converts an array of object Character to primitives handling {@code null}.
  9048.      * <p>
  9049.      * This method returns {@code null} for a {@code null} input array.
  9050.      * </p>
  9051.      *
  9052.      * @param array  a {@link Character} array, may be {@code null}
  9053.      * @param valueForNull  the value to insert if {@code null} found
  9054.      * @return a {@code char} array, {@code null} if null array input
  9055.      */
  9056.     public static char[] toPrimitive(final Character[] array, final char valueForNull) {
  9057.         if (array == null) {
  9058.             return null;
  9059.         }
  9060.         if (array.length == 0) {
  9061.             return EMPTY_CHAR_ARRAY;
  9062.         }
  9063.         final char[] result = new char[array.length];
  9064.         for (int i = 0; i < array.length; i++) {
  9065.             final Character b = array[i];
  9066.             result[i] = b == null ? valueForNull : b.charValue();
  9067.         }
  9068.         return result;
  9069.     }

  9071.     /**
  9072.      * Converts an array of object Doubles to primitives.
  9073.      * <p>
  9074.      * This method returns {@code null} for a {@code null} input array.
  9075.      * </p>
  9076.      *
  9077.      * @param array  a {@link Double} array, may be {@code null}
  9078.      * @return a {@code double} array, {@code null} if null array input
  9079.      * @throws NullPointerException if an array element is {@code null}
  9080.      */
  9081.     public static double[] toPrimitive(final Double[] array) {
  9082.         if (array == null) {
  9083.             return null;
  9084.         }
  9085.         if (array.length == 0) {
  9086.             return EMPTY_DOUBLE_ARRAY;
  9087.         }
  9088.         final double[] result = new double[array.length];
  9089.         for (int i = 0; i < array.length; i++) {
  9090.             result[i] = array[i].doubleValue();
  9091.         }
  9092.         return result;
  9093.     }

  9095.     /**
  9096.      * Converts an array of object Doubles to primitives handling {@code null}.
  9097.      * <p>
  9098.      * This method returns {@code null} for a {@code null} input array.
  9099.      * </p>
  9100.      *
  9101.      * @param array  a {@link Double} array, may be {@code null}
  9102.      * @param valueForNull  the value to insert if {@code null} found
  9103.      * @return a {@code double} array, {@code null} if null array input
  9104.      */
  9105.     public static double[] toPrimitive(final Double[] array, final double valueForNull) {
  9106.         if (array == null) {
  9107.             return null;
  9108.         }
  9109.         if (array.length == 0) {
  9110.             return EMPTY_DOUBLE_ARRAY;
  9111.         }
  9112.         final double[] result = new double[array.length];
  9113.         for (int i = 0; i < array.length; i++) {
  9114.             final Double b = array[i];
  9115.             result[i] = b == null ? valueForNull : b.doubleValue();
  9116.         }
  9117.         return result;
  9118.     }

  9120.     /**
  9121.      * Converts an array of object Floats to primitives.
  9122.      * <p>
  9123.      * This method returns {@code null} for a {@code null} input array.
  9124.      * </p>
  9125.      *
  9126.      * @param array  a {@link Float} array, may be {@code null}
  9127.      * @return a {@code float} array, {@code null} if null array input
  9128.      * @throws NullPointerException if an array element is {@code null}
  9129.      */
  9130.     public static float[] toPrimitive(final Float[] array) {
  9131.         if (array == null) {
  9132.             return null;
  9133.         }
  9134.         if (array.length == 0) {
  9135.             return EMPTY_FLOAT_ARRAY;
  9136.         }
  9137.         final float[] result = new float[array.length];
  9138.         for (int i = 0; i < array.length; i++) {
  9139.             result[i] = array[i].floatValue();
  9140.         }
  9141.         return result;
  9142.     }

  9144.     /**
  9145.      * Converts an array of object Floats to primitives handling {@code null}.
  9146.      * <p>
  9147.      * This method returns {@code null} for a {@code null} input array.
  9148.      * </p>
  9149.      *
  9150.      * @param array  a {@link Float} array, may be {@code null}
  9151.      * @param valueForNull  the value to insert if {@code null} found
  9152.      * @return a {@code float} array, {@code null} if null array input
  9153.      */
  9154.     public static float[] toPrimitive(final Float[] array, final float valueForNull) {
  9155.         if (array == null) {
  9156.             return null;
  9157.         }
  9158.         if (array.length == 0) {
  9159.             return EMPTY_FLOAT_ARRAY;
  9160.         }
  9161.         final float[] result = new float[array.length];
  9162.         for (int i = 0; i < array.length; i++) {
  9163.             final Float b = array[i];
  9164.             result[i] = b == null ? valueForNull : b.floatValue();
  9165.         }
  9166.         return result;
  9167.     }

  9169.     /**
  9170.      * Converts an array of object Integers to primitives.
  9171.      * <p>
  9172.      * This method returns {@code null} for a {@code null} input array.
  9173.      * </p>
  9174.      *
  9175.      * @param array  a {@link Integer} array, may be {@code null}
  9176.      * @return an {@code int} array, {@code null} if null array input
  9177.      * @throws NullPointerException if an array element is {@code null}
  9178.      */
  9179.     public static int[] toPrimitive(final Integer[] array) {
  9180.         if (array == null) {
  9181.             return null;
  9182.         }
  9183.         if (array.length == 0) {
  9184.             return EMPTY_INT_ARRAY;
  9185.         }
  9186.         final int[] result = new int[array.length];
  9187.         for (int i = 0; i < array.length; i++) {
  9188.             result[i] = array[i].intValue();
  9189.         }
  9190.         return result;
  9191.     }

  9193.     /**
  9194.      * Converts an array of object Integer to primitives handling {@code null}.
  9195.      * <p>
  9196.      * This method returns {@code null} for a {@code null} input array.
  9197.      * </p>
  9198.      *
  9199.      * @param array  a {@link Integer} array, may be {@code null}
  9200.      * @param valueForNull  the value to insert if {@code null} found
  9201.      * @return an {@code int} array, {@code null} if null array input
  9202.      */
  9203.     public static int[] toPrimitive(final Integer[] array, final int valueForNull) {
  9204.         if (array == null) {
  9205.             return null;
  9206.         }
  9207.         if (array.length == 0) {
  9208.             return EMPTY_INT_ARRAY;
  9209.         }
  9210.         final int[] result = new int[array.length];
  9211.         for (int i = 0; i < array.length; i++) {
  9212.             final Integer b = array[i];
  9213.             result[i] = b == null ? valueForNull : b.intValue();
  9214.         }
  9215.         return result;
  9216.     }

  9218.     /**
  9219.      * Converts an array of object Longs to primitives.
  9220.      * <p>
  9221.      * This method returns {@code null} for a {@code null} input array.
  9222.      * </p>
  9223.      *
  9224.      * @param array  a {@link Long} array, may be {@code null}
  9225.      * @return a {@code long} array, {@code null} if null array input
  9226.      * @throws NullPointerException if an array element is {@code null}
  9227.      */
  9228.     public static long[] toPrimitive(final Long[] array) {
  9229.         if (array == null) {
  9230.             return null;
  9231.         }
  9232.         if (array.length == 0) {
  9233.             return EMPTY_LONG_ARRAY;
  9234.         }
  9235.         final long[] result = new long[array.length];
  9236.         for (int i = 0; i < array.length; i++) {
  9237.             result[i] = array[i].longValue();
  9238.         }
  9239.         return result;
  9240.     }

  9242.     /**
  9243.      * Converts an array of object Long to primitives handling {@code null}.
  9244.      * <p>
  9245.      * This method returns {@code null} for a {@code null} input array.
  9246.      * </p>
  9247.      *
  9248.      * @param array  a {@link Long} array, may be {@code null}
  9249.      * @param valueForNull  the value to insert if {@code null} found
  9250.      * @return a {@code long} array, {@code null} if null array input
  9251.      */
  9252.     public static long[] toPrimitive(final Long[] array, final long valueForNull) {
  9253.         if (array == null) {
  9254.             return null;
  9255.         }
  9256.         if (array.length == 0) {
  9257.             return EMPTY_LONG_ARRAY;
  9258.         }
  9259.         final long[] result = new long[array.length];
  9260.         for (int i = 0; i < array.length; i++) {
  9261.             final Long b = array[i];
  9262.             result[i] = b == null ? valueForNull : b.longValue();
  9263.         }
  9264.         return result;
  9265.     }

  9267.     /**
  9268.      * Create an array of primitive type from an array of wrapper types.
  9269.      * <p>
  9270.      * This method returns {@code null} for a {@code null} input array.
  9271.      * </p>
  9272.      *
  9273.      * @param array  an array of wrapper object
  9274.      * @return an array of the corresponding primitive type, or the original array
  9275.      * @since 3.5
  9276.      */
  9277.     public static Object toPrimitive(final Object array) {
  9278.         if (array == null) {
  9279.             return null;
  9280.         }
  9281.         final Class<?> ct = array.getClass().getComponentType();
  9282.         final Class<?> pt = ClassUtils.wrapperToPrimitive(ct);
  9283.         if (Boolean.TYPE.equals(pt)) {
  9284.             return toPrimitive((Boolean[]) array);
  9285.         }
  9286.         if (Character.TYPE.equals(pt)) {
  9287.             return toPrimitive((Character[]) array);
  9288.         }
  9289.         if (Byte.TYPE.equals(pt)) {
  9290.             return toPrimitive((Byte[]) array);
  9291.         }
  9292.         if (Integer.TYPE.equals(pt)) {
  9293.             return toPrimitive((Integer[]) array);
  9294.         }
  9295.         if (Long.TYPE.equals(pt)) {
  9296.             return toPrimitive((Long[]) array);
  9297.         }
  9298.         if (Short.TYPE.equals(pt)) {
  9299.             return toPrimitive((Short[]) array);
  9300.         }
  9301.         if (Double.TYPE.equals(pt)) {
  9302.             return toPrimitive((Double[]) array);
  9303.         }
  9304.         if (Float.TYPE.equals(pt)) {
  9305.             return toPrimitive((Float[]) array);
  9306.         }
  9307.         return array;
  9308.     }

  9310.     /**
  9311.      * Converts an array of object Shorts to primitives.
  9312.      * <p>
  9313.      * This method returns {@code null} for a {@code null} input array.
  9314.      * </p>
  9315.      *
  9316.      * @param array  a {@link Short} array, may be {@code null}
  9317.      * @return a {@code byte} array, {@code null} if null array input
  9318.      * @throws NullPointerException if an array element is {@code null}
  9319.      */
  9320.     public static short[] toPrimitive(final Short[] array) {
  9321.         if (array == null) {
  9322.             return null;
  9323.         }
  9324.         if (array.length == 0) {
  9325.             return EMPTY_SHORT_ARRAY;
  9326.         }
  9327.         final short[] result = new short[array.length];
  9328.         for (int i = 0; i < array.length; i++) {
  9329.             result[i] = array[i].shortValue();
  9330.         }
  9331.         return result;
  9332.     }

  9334.     /**
  9335.      * Converts an array of object Short to primitives handling {@code null}.
  9336.      * <p>
  9337.      * This method returns {@code null} for a {@code null} input array.
  9338.      * </p>
  9339.      *
  9340.      * @param array  a {@link Short} array, may be {@code null}
  9341.      * @param valueForNull  the value to insert if {@code null} found
  9342.      * @return a {@code byte} array, {@code null} if null array input
  9343.      */
  9344.     public static short[] toPrimitive(final Short[] array, final short valueForNull) {
  9345.         if (array == null) {
  9346.             return null;
  9347.         }
  9348.         if (array.length == 0) {
  9349.             return EMPTY_SHORT_ARRAY;
  9350.         }
  9351.         final short[] result = new short[array.length];
  9352.         for (int i = 0; i < array.length; i++) {
  9353.             final Short b = array[i];
  9354.             result[i] = b == null ? valueForNull : b.shortValue();
  9355.         }
  9356.         return result;
  9357.     }

  9359.     /**
  9360.      * Outputs an array as a String, treating {@code null} as an empty array.
  9361.      * <p>
  9362.      * Multi-dimensional arrays are handled correctly, including
  9363.      * multi-dimensional primitive arrays.
  9364.      * </p>
  9365.      * <p>
  9366.      * The format is that of Java source code, for example {@code {a,b}}.
  9367.      * </p>
  9368.      *
  9369.      * @param array  the array to get a toString for, may be {@code null}
  9370.      * @return a String representation of the array, '{}' if null array input
  9371.      */
  9372.     public static String toString(final Object array) {
  9373.         return toString(array, "{}");
  9374.     }

  9376.     /**
  9377.      * Outputs an array as a String handling {@code null}s.
  9378.      * <p>
  9379.      * Multi-dimensional arrays are handled correctly, including
  9380.      * multi-dimensional primitive arrays.
  9381.      * </p>
  9382.      * <p>
  9383.      * The format is that of Java source code, for example {@code {a,b}}.
  9384.      * </p>
  9385.      *
  9386.      * @param array  the array to get a toString for, may be {@code null}
  9387.      * @param stringIfNull  the String to return if the array is {@code null}
  9388.      * @return a String representation of the array
  9389.      */
  9390.     public static String toString(final Object array, final String stringIfNull) {
  9391.         if (array == null) {
  9392.             return stringIfNull;
  9393.         }
  9394.         return new ToStringBuilder(array, ToStringStyle.SIMPLE_STYLE).append(array).toString();
  9395.     }

  9397.     /**
  9398.      * Returns an array containing the string representation of each element in the argument array.
  9399.      * <p>
  9400.      * This method returns {@code null} for a {@code null} input array.
  9401.      * </p>
  9402.      *
  9403.      * @param array the {@code Object[]} to be processed, may be null
  9404.      * @return {@code String[]} of the same size as the source with its element's string representation,
  9405.      * {@code null} if null array input
  9406.      * @throws NullPointerException if an array element is {@code null}
  9407.      * @since 3.6
  9408.      */
  9409.     public static String[] toStringArray(final Object[] array) {
  9410.         if (array == null) {
  9411.             return null;
  9412.         }
  9413.         if (array.length == 0) {
  9414.             return EMPTY_STRING_ARRAY;
  9415.         }

  9417.         final String[] result = new String[array.length];
  9418.         for (int i = 0; i < array.length; i++) {
  9419.             result[i] = array[i].toString();
  9420.         }

  9422.         return result;
  9423.     }

  9425.     /**
  9426.      * Returns an array containing the string representation of each element in the argument
  9427.      * array handling {@code null} elements.
  9428.      * <p>
  9429.      * This method returns {@code null} for a {@code null} input array.
  9430.      * </p>
  9431.      *
  9432.      * @param array the Object[] to be processed, may be null
  9433.      * @param valueForNullElements the value to insert if {@code null} is found
  9434.      * @return a {@link String} array, {@code null} if null array input
  9435.      * @since 3.6
  9436.      */
  9437.     public static String[] toStringArray(final Object[] array, final String valueForNullElements) {
  9438.         if (null == array) {
  9439.             return null;
  9440.         }
  9441.         if (array.length == 0) {
  9442.             return EMPTY_STRING_ARRAY;
  9443.         }

  9445.         final String[] result = new String[array.length];
  9446.         for (int i = 0; i < array.length; i++) {
  9447.             result[i] = Objects.toString(array[i], valueForNullElements);
  9448.         }

  9450.         return result;
  9451.     }

  9453.     /**
  9454.      * ArrayUtils instances should NOT be constructed in standard programming.
  9455.      * Instead, the class should be used as {@code ArrayUtils.clone(new int[] {2})}.
  9456.      * <p>
  9457.      * This constructor is public to permit tools that require a JavaBean instance
  9458.      * to operate.
  9459.      * </p>
  9460.      *
  9461.      * @deprecated TODO Make private in 4.0.
  9462.      */
  9463.     @Deprecated
  9464.     public ArrayUtils() {
  9465.         // empty
  9466.     }
  9467. }
Created with JaCoCo 0.8.12.202403310830