Source code
Description: source: package: org.apache.commons.lang3, class: ArrayUtils

    001/*
    002 * Licensed to the Apache Software Foundation (ASF) under one or more
    003 * contributor license agreements.  See the NOTICE file distributed with
    004 * this work for additional information regarding copyright ownership.
    005 * The ASF licenses this file to You under the Apache License, Version 2.0
    006 * (the "License"); you may not use this file except in compliance with
    007 * the License.  You may obtain a copy of the License at
    008 *
    009 *      http://www.apache.org/licenses/LICENSE-2.0
    010 *
    011 * Unless required by applicable law or agreed to in writing, software
    012 * distributed under the License is distributed on an "AS IS" BASIS,
    013 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
    014 * See the License for the specific language governing permissions and
    015 * limitations under the License.
    016 */
    017package org.apache.commons.lang3;
    018
    019import java.lang.reflect.Array;
    020import java.lang.reflect.Field;
    021import java.lang.reflect.Method;
    022import java.lang.reflect.Type;
    023import java.util.Arrays;
    024import java.util.BitSet;
    025import java.util.Comparator;
    026import java.util.Date;
    027import java.util.HashMap;
    028import java.util.Map;
    029import java.util.Objects;
    030import java.util.Random;
    031import java.util.concurrent.ThreadLocalRandom;
    032import java.util.function.Function;
    033import java.util.function.IntFunction;
    034import java.util.function.Supplier;
    035
    036import org.apache.commons.lang3.builder.EqualsBuilder;
    037import org.apache.commons.lang3.builder.HashCodeBuilder;
    038import org.apache.commons.lang3.builder.ToStringBuilder;
    039import org.apache.commons.lang3.builder.ToStringStyle;
    040import org.apache.commons.lang3.math.NumberUtils;
    041import org.apache.commons.lang3.mutable.MutableInt;
    042import org.apache.commons.lang3.stream.Streams;
    043
    044/**
    045 * Operations on arrays, primitive arrays (like {@code int[]}) and
    046 * primitive wrapper arrays (like {@code Integer[]}).
    047 * <p>
    048 * This class tries to handle {@code null} input gracefully.
    049 * An exception will not be thrown for a {@code null}
    050 * array input. However, an Object array that contains a {@code null}
    051 * element may throw an exception. Each method documents its behavior.
    052 * </p>
    053 * <p>
    054 * #ThreadSafe#
    055 * </p>
    056 * @since 2.0
    057 */
    058public class ArrayUtils {
    059
    060    /**
    061     * An empty immutable {@code boolean} array.
    062     */
    063    public static final boolean[] EMPTY_BOOLEAN_ARRAY = {};
    064
    065    /**
    066     * An empty immutable {@link Boolean} array.
    067     */
    068    public static final Boolean[] EMPTY_BOOLEAN_OBJECT_ARRAY = {};
    069
    070    /**
    071     * An empty immutable {@code byte} array.
    072     */
    073    public static final byte[] EMPTY_BYTE_ARRAY = {};
    074
    075    /**
    076     * An empty immutable {@link Byte} array.
    077     */
    078    public static final Byte[] EMPTY_BYTE_OBJECT_ARRAY = {};
    079
    080    /**
    081     * An empty immutable {@code char} array.
    082     */
    083    public static final char[] EMPTY_CHAR_ARRAY = {};
    084
    085    /**
    086     * An empty immutable {@link Character} array.
    087     */
    088    public static final Character[] EMPTY_CHARACTER_OBJECT_ARRAY = {};
    089
    090    /**
    091     * An empty immutable {@link Class} array.
    092     */
    093    public static final Class<?>[] EMPTY_CLASS_ARRAY = {};
    094
    095    /**
    096     * An empty immutable {@code double} array.
    097     */
    098    public static final double[] EMPTY_DOUBLE_ARRAY = {};
    099
    100    /**
    101     * An empty immutable {@link Double} array.
    102     */
    103    public static final Double[] EMPTY_DOUBLE_OBJECT_ARRAY = {};
    104
    105    /**
    106     * An empty immutable {@link Field} array.
    107     *
    108     * @since 3.10
    109     */
    110    public static final Field[] EMPTY_FIELD_ARRAY = {};
    111
    112    /**
    113     * An empty immutable {@code float} array.
    114     */
    115    public static final float[] EMPTY_FLOAT_ARRAY = {};
    116
    117    /**
    118     * An empty immutable {@link Float} array.
    119     */
    120    public static final Float[] EMPTY_FLOAT_OBJECT_ARRAY = {};
    121
    122    /**
    123     * An empty immutable {@code int} array.
    124     */
    125    public static final int[] EMPTY_INT_ARRAY = {};
    126
    127    /**
    128     * An empty immutable {@link Integer} array.
    129     */
    130    public static final Integer[] EMPTY_INTEGER_OBJECT_ARRAY = {};
    131
    132    /**
    133     * An empty immutable {@code long} array.
    134     */
    135    public static final long[] EMPTY_LONG_ARRAY = {};
    136
    137    /**
    138     * An empty immutable {@link Long} array.
    139     */
    140    public static final Long[] EMPTY_LONG_OBJECT_ARRAY = {};
    141
    142    /**
    143     * An empty immutable {@link Method} array.
    144     *
    145     * @since 3.10
    146     */
    147    public static final Method[] EMPTY_METHOD_ARRAY = {};
    148
    149    /**
    150     * An empty immutable {@link Object} array.
    151     */
    152    public static final Object[] EMPTY_OBJECT_ARRAY = {};
    153
    154    /**
    155     * An empty immutable {@code short} array.
    156     */
    157    public static final short[] EMPTY_SHORT_ARRAY = {};
    158
    159    /**
    160     * An empty immutable {@link Short} array.
    161     */
    162    public static final Short[] EMPTY_SHORT_OBJECT_ARRAY = {};
    163
    164    /**
    165     * An empty immutable {@link String} array.
    166     */
    167    public static final String[] EMPTY_STRING_ARRAY = {};
    168
    169    /**
    170     * An empty immutable {@link Throwable} array.
    171     *
    172     * @since 3.10
    173     */
    174    public static final Throwable[] EMPTY_THROWABLE_ARRAY = {};
    175
    176    /**
    177     * An empty immutable {@link Type} array.
    178     *
    179     * @since 3.10
    180     */
    181    public static final Type[] EMPTY_TYPE_ARRAY = {};
    182
    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;
    189
    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    }
    217
    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    }
    252
    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    }
    280
    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    }
    316
    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    }
    344
    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    }
    381
    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    }
    410
    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    }
    446
    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    }
    474
    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    }
    510
    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    }
    538
    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    }
    574
    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    }
    610
    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    }
    638
    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    }
    670
    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    }
    706
    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    }
    734
    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    }
    780
    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    }
    826
    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    }
    858
    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    }
    890
    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    }
    922
    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    }
    954
    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    }
    986
    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    }
    1018
    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    }
    1050
    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    }
    1082
    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    }
    1134
    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    }
    1160
    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    }
    1186
    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    }
    1212
    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    }
    1238
    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    }
    1264
    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    }
    1290
    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    }
    1316
    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    }
    1342
    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    }
    1373
    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    }
    1393
    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    }
    1413
    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    }
    1434
    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    }
    1447
    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    }
    1460
    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    }
    1473
    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    }
    1486
    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    }
    1499
    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    }
    1512
    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    }
    1525
    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    }
    1538
    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    }
    1555
    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    }
    1569
    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    }
    1583
    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    }
    1598
    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    }
    1612
    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    }
    1630
    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    }
    1644
    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    }
    1658
    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    }
    1672
    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    }
    1686
    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    }
    1700
    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    }
    1715
    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    }
    1734
    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    }
    1747
    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    }
    1761
    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    }
    1773
    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    }
    1797
    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    }
    1810
    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    }
    1826
    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    }
    1860
    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    }
    1875
    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        }
    1904
    1905        return bitSet;
    1906    }
    1907
    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    }
    1922
    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    }
    1953
    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    }
    1968
    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    }
    1989
    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    }
    2020
    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    }
    2057
    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    }
    2072
    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    }
    2103
    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    }
    2118
    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);
    2141
    2142            if (startIndex == INDEX_NOT_FOUND) {
    2143                break;
    2144            }
    2145            bitSet.set(startIndex);
    2146            ++startIndex;
    2147        }
    2148        return bitSet;
    2149    }
    2150
    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    }
    2165
    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    }
    2196
    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    }
    2211
    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    }
    2242
    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    }
    2257
    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    }
    2288
    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    }
    2303
    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    }
    2332
    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    }
    2347
    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    }
    2375
    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    }
    2391
    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    }
    2420
    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    }
    2435
    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    }
    2453
    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    }
    2483
    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    }
    2516
    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    }
    2531
    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    }
    2561
    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    }
    2576
    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    }
    2604
    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    }
    2619
    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    }
    2647
    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    }
    2662
    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    }
    2699
    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    }
    2714
    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    }
    2742
    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    }
    2782
    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    }
    2822
    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    }
    2862
    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    }
    2902
    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    }
    2942
    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    }
    2982
    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    }
    3022
    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    }
    3062
    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    }
    3113
    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    }
    3123
    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    }
    3142
    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    }
    3153
    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    }
    3164
    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    }
    3175
    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    }
    3186
    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    }
    3197
    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    }
    3208
    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    }
    3219
    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    }
    3230
    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    }
    3241
    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    }
    3259
    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    }
    3270
    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    }
    3281
    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    }
    3292
    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    }
    3303
    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    }
    3314
    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    }
    3325
    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    }
    3336
    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    }
    3347
    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     }
    3359
    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    }
    3372
    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    }
    3385
    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    }
    3398
    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    }
    3411
    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    }
    3424
    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    }
    3437
    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    }
    3450
    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    }
    3467
    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    }
    3483
    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    }
    3496
    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    }
    3512
    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    }
    3536
    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    }
    3559
    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    }
    3582
    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    }
    3605
    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    }
    3628
    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    }
    3651
    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    }
    3674
    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    }
    3697
    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    }
    3710
    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    }
    3737
    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    }
    3753
    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    }
    3784
    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    }
    3799
    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    }
    3830
    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    }
    3846
    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    }
    3878
    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    }
    3893
    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    }
    3911
    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    }
    3942
    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    }
    3978
    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    }
    3993
    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    }
    4024
    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    }
    4039
    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    }
    4070
    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    }
    4085
    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    }
    4116
    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    }
    4131
    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    }
    4170
    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    }
    4185
    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    }
    4216
    4217    private static int max0(int other) {
    4218        return Math.max(0, other);
    4219    }
    4220
    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    }
    4235
    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    }
    4256
    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    }
    4275
    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    }
    4294
    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    }
    4313
    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    }
    4332
    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    }
    4351
    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    }
    4370
    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    }
    4389
    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    }
    4408
    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    }
    4427
    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    }
    4446
    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    }
    4465
    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    }
    4484
    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    }
    4503
    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    }
    4522
    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    }
    4541
    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    }
    4560
    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    }
    4579
    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    }
    4598
    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    }
    4617
    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    }
    4641
    4642    private static ThreadLocalRandom random() {
    4643        return ThreadLocalRandom.current();
    4644    }
    4645
    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    }
    4678
    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    }
    4711
    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    }
    4744
    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    }
    4777
    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    }
    4810
    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    }
    4843
    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    }
    4876
    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    }
    4912
    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    }
    4945
    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    }
    4980
    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    }
    5010
    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    }
    5044
    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    }
    5078
    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    }
    5112
    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    }
    5146
    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    }
    5180
    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    }
    5214
    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    }
    5255
    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    }
    5308
    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    }
    5342
    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    }
    5374
    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    }
    5394
    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    }
    5414
    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    }
    5434
    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    }
    5454
    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    }
    5474
    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    }
    5494
    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    }
    5514
    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    }
    5534
    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    }
    5555
    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    }
    5573
    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    }
    5591
    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    }
    5609
    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    }
    5627
    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    }
    5645
    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    }
    5663
    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    }
    5681
    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    }
    5699
    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    }
    5718
    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    }
    5748
    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    }
    5778
    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    }
    5808
    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    }
    5838
    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    }
    5868
    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    }
    5898
    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    }
    5928
    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    }
    5958
    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    }
    5989
    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    }
    6044
    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    }
    6099
    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    }
    6154
    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    }
    6209
    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    }
    6264
    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    }
    6319
    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    }
    6374
    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    }
    6429
    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    }
    6487
    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    }
    6502
    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    }
    6534
    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    }
    6548
    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    }
    6580
    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    }
    6594
    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    }
    6626
    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    }
    6640
    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    }
    6672
    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    }
    6686
    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    }
    6718
    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    }
    6732
    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    }
    6764
    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    }
    6778
    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    }
    6810
    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    }
    6827
    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    }
    6859
    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    }
    6873
    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    }
    6905
    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    }
    6925
    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    }
    6947
    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    }
    6965
    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    }
    7017
    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    }
    7035
    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    }
    7087
    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    }
    7105
    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    }
    7157
    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    }
    7175
    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    }
    7227
    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    }
    7245
    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    }
    7297
    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    }
    7315
    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    }
    7367
    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    }
    7385
    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    }
    7437
    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    }
    7455
    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    }
    7507
    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    }
    7525
    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    }
    7577
    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    }
    7588
    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    }
    7602
    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    }
    7613
    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    }
    7627
    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    }
    7638
    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    }
    7652
    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    }
    7663
    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    }
    7677
    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    }
    7688
    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    }
    7702
    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    }
    7713
    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    }
    7727
    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    }
    7738
    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    }
    7752
    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    }
    7763
    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    }
    7777
    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    }
    7788
    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    }
    7802
    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    }
    7836
    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    }
    7870
    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    }
    7904
    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    }
    7938
    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    }
    7972
    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    }
    8006
    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    }
    8040
    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    }
    8074
    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    }
    8118
    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    }
    8143
    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    }
    8181
    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    }
    8206
    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    }
    8244
    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    }
    8269
    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    }
    8307
    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    }
    8332
    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    }
    8370
    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    }
    8395
    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        }
    8432
    8433    }
    8434
    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    }
    8459
    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    }
    8497
    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    }
    8522
    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    }
    8560
    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    }
    8585
    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    }
    8623
    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    }
    8648
    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    }
    8689
    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    }
    8732
    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    }
    8786
    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    }
    8805
    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    }
    8823
    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     }
    8841
    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    }
    8859
    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    }
    8877
    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    }
    8895
    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    }
    8913
    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    }
    8931
    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    }
    8947
    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    }
    8972
    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    }
    8996
    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    }
    9021
    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    }
    9045
    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    }
    9070
    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    }
    9094
    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    }
    9119
    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    }
    9143
    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    }
    9168
    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    }
    9192
    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    }
    9217
    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    }
    9241
    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    }
    9266
    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    }
    9309
    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    }
    9333
    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    }
    9358
    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    }
    9375
    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    }
    9396
    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        }
    9416
    9417        final String[] result = new String[array.length];
    9418        for (int i = 0; i < array.length; i++) {
    9419            result[i] = array[i].toString();
    9420        }
    9421
    9422        return result;
    9423    }
    9424
    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        }
    9444
    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        }
    9449
    9450        return result;
    9451    }
    9452
    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}