src/java.base/share/classes/java/util/Arrays.java
changeset 47216 71c04702a3d5
parent 44743 f0bbd698c486
child 48356 29e165bdf669
equal deleted inserted replaced
47215:4ebc2e2fb97c 47216:71c04702a3d5
       
     1 /*
       
     2  * Copyright (c) 1997, 2016, Oracle and/or its affiliates. All rights reserved.
       
     3  * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER.
       
     4  *
       
     5  * This code is free software; you can redistribute it and/or modify it
       
     6  * under the terms of the GNU General Public License version 2 only, as
       
     7  * published by the Free Software Foundation.  Oracle designates this
       
     8  * particular file as subject to the "Classpath" exception as provided
       
     9  * by Oracle in the LICENSE file that accompanied this code.
       
    10  *
       
    11  * This code is distributed in the hope that it will be useful, but WITHOUT
       
    12  * ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or
       
    13  * FITNESS FOR A PARTICULAR PURPOSE.  See the GNU General Public License
       
    14  * version 2 for more details (a copy is included in the LICENSE file that
       
    15  * accompanied this code).
       
    16  *
       
    17  * You should have received a copy of the GNU General Public License version
       
    18  * 2 along with this work; if not, write to the Free Software Foundation,
       
    19  * Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA.
       
    20  *
       
    21  * Please contact Oracle, 500 Oracle Parkway, Redwood Shores, CA 94065 USA
       
    22  * or visit www.oracle.com if you need additional information or have any
       
    23  * questions.
       
    24  */
       
    25 
       
    26 package java.util;
       
    27 
       
    28 import jdk.internal.HotSpotIntrinsicCandidate;
       
    29 
       
    30 import java.lang.reflect.Array;
       
    31 import java.util.concurrent.ForkJoinPool;
       
    32 import java.util.function.BinaryOperator;
       
    33 import java.util.function.Consumer;
       
    34 import java.util.function.DoubleBinaryOperator;
       
    35 import java.util.function.IntBinaryOperator;
       
    36 import java.util.function.IntFunction;
       
    37 import java.util.function.IntToDoubleFunction;
       
    38 import java.util.function.IntToLongFunction;
       
    39 import java.util.function.IntUnaryOperator;
       
    40 import java.util.function.LongBinaryOperator;
       
    41 import java.util.function.UnaryOperator;
       
    42 import java.util.stream.DoubleStream;
       
    43 import java.util.stream.IntStream;
       
    44 import java.util.stream.LongStream;
       
    45 import java.util.stream.Stream;
       
    46 import java.util.stream.StreamSupport;
       
    47 
       
    48 /**
       
    49  * This class contains various methods for manipulating arrays (such as
       
    50  * sorting and searching). This class also contains a static factory
       
    51  * that allows arrays to be viewed as lists.
       
    52  *
       
    53  * <p>The methods in this class all throw a {@code NullPointerException},
       
    54  * if the specified array reference is null, except where noted.
       
    55  *
       
    56  * <p>The documentation for the methods contained in this class includes
       
    57  * brief descriptions of the <i>implementations</i>. Such descriptions should
       
    58  * be regarded as <i>implementation notes</i>, rather than parts of the
       
    59  * <i>specification</i>. Implementors should feel free to substitute other
       
    60  * algorithms, so long as the specification itself is adhered to. (For
       
    61  * example, the algorithm used by {@code sort(Object[])} does not have to be
       
    62  * a MergeSort, but it does have to be <i>stable</i>.)
       
    63  *
       
    64  * <p>This class is a member of the
       
    65  * <a href="{@docRoot}/java/util/package-summary.html#CollectionsFramework">
       
    66  * Java Collections Framework</a>.
       
    67  *
       
    68  * @author Josh Bloch
       
    69  * @author Neal Gafter
       
    70  * @author John Rose
       
    71  * @since  1.2
       
    72  */
       
    73 public class Arrays {
       
    74 
       
    75     /**
       
    76      * The minimum array length below which a parallel sorting
       
    77      * algorithm will not further partition the sorting task. Using
       
    78      * smaller sizes typically results in memory contention across
       
    79      * tasks that makes parallel speedups unlikely.
       
    80      */
       
    81     private static final int MIN_ARRAY_SORT_GRAN = 1 << 13;
       
    82 
       
    83     // Suppresses default constructor, ensuring non-instantiability.
       
    84     private Arrays() {}
       
    85 
       
    86     /**
       
    87      * A comparator that implements the natural ordering of a group of
       
    88      * mutually comparable elements. May be used when a supplied
       
    89      * comparator is null. To simplify code-sharing within underlying
       
    90      * implementations, the compare method only declares type Object
       
    91      * for its second argument.
       
    92      *
       
    93      * Arrays class implementor's note: It is an empirical matter
       
    94      * whether ComparableTimSort offers any performance benefit over
       
    95      * TimSort used with this comparator.  If not, you are better off
       
    96      * deleting or bypassing ComparableTimSort.  There is currently no
       
    97      * empirical case for separating them for parallel sorting, so all
       
    98      * public Object parallelSort methods use the same comparator
       
    99      * based implementation.
       
   100      */
       
   101     static final class NaturalOrder implements Comparator<Object> {
       
   102         @SuppressWarnings("unchecked")
       
   103         public int compare(Object first, Object second) {
       
   104             return ((Comparable<Object>)first).compareTo(second);
       
   105         }
       
   106         static final NaturalOrder INSTANCE = new NaturalOrder();
       
   107     }
       
   108 
       
   109     /**
       
   110      * Checks that {@code fromIndex} and {@code toIndex} are in
       
   111      * the range and throws an exception if they aren't.
       
   112      */
       
   113     static void rangeCheck(int arrayLength, int fromIndex, int toIndex) {
       
   114         if (fromIndex > toIndex) {
       
   115             throw new IllegalArgumentException(
       
   116                     "fromIndex(" + fromIndex + ") > toIndex(" + toIndex + ")");
       
   117         }
       
   118         if (fromIndex < 0) {
       
   119             throw new ArrayIndexOutOfBoundsException(fromIndex);
       
   120         }
       
   121         if (toIndex > arrayLength) {
       
   122             throw new ArrayIndexOutOfBoundsException(toIndex);
       
   123         }
       
   124     }
       
   125 
       
   126     /*
       
   127      * Sorting methods. Note that all public "sort" methods take the
       
   128      * same form: Performing argument checks if necessary, and then
       
   129      * expanding arguments into those required for the internal
       
   130      * implementation methods residing in other package-private
       
   131      * classes (except for legacyMergeSort, included in this class).
       
   132      */
       
   133 
       
   134     /**
       
   135      * Sorts the specified array into ascending numerical order.
       
   136      *
       
   137      * <p>Implementation note: The sorting algorithm is a Dual-Pivot Quicksort
       
   138      * by Vladimir Yaroslavskiy, Jon Bentley, and Joshua Bloch. This algorithm
       
   139      * offers O(n log(n)) performance on many data sets that cause other
       
   140      * quicksorts to degrade to quadratic performance, and is typically
       
   141      * faster than traditional (one-pivot) Quicksort implementations.
       
   142      *
       
   143      * @param a the array to be sorted
       
   144      */
       
   145     public static void sort(int[] a) {
       
   146         DualPivotQuicksort.sort(a, 0, a.length - 1, null, 0, 0);
       
   147     }
       
   148 
       
   149     /**
       
   150      * Sorts the specified range of the array into ascending order. The range
       
   151      * to be sorted extends from the index {@code fromIndex}, inclusive, to
       
   152      * the index {@code toIndex}, exclusive. If {@code fromIndex == toIndex},
       
   153      * the range to be sorted is empty.
       
   154      *
       
   155      * <p>Implementation note: The sorting algorithm is a Dual-Pivot Quicksort
       
   156      * by Vladimir Yaroslavskiy, Jon Bentley, and Joshua Bloch. This algorithm
       
   157      * offers O(n log(n)) performance on many data sets that cause other
       
   158      * quicksorts to degrade to quadratic performance, and is typically
       
   159      * faster than traditional (one-pivot) Quicksort implementations.
       
   160      *
       
   161      * @param a the array to be sorted
       
   162      * @param fromIndex the index of the first element, inclusive, to be sorted
       
   163      * @param toIndex the index of the last element, exclusive, to be sorted
       
   164      *
       
   165      * @throws IllegalArgumentException if {@code fromIndex > toIndex}
       
   166      * @throws ArrayIndexOutOfBoundsException
       
   167      *     if {@code fromIndex < 0} or {@code toIndex > a.length}
       
   168      */
       
   169     public static void sort(int[] a, int fromIndex, int toIndex) {
       
   170         rangeCheck(a.length, fromIndex, toIndex);
       
   171         DualPivotQuicksort.sort(a, fromIndex, toIndex - 1, null, 0, 0);
       
   172     }
       
   173 
       
   174     /**
       
   175      * Sorts the specified array into ascending numerical order.
       
   176      *
       
   177      * <p>Implementation note: The sorting algorithm is a Dual-Pivot Quicksort
       
   178      * by Vladimir Yaroslavskiy, Jon Bentley, and Joshua Bloch. This algorithm
       
   179      * offers O(n log(n)) performance on many data sets that cause other
       
   180      * quicksorts to degrade to quadratic performance, and is typically
       
   181      * faster than traditional (one-pivot) Quicksort implementations.
       
   182      *
       
   183      * @param a the array to be sorted
       
   184      */
       
   185     public static void sort(long[] a) {
       
   186         DualPivotQuicksort.sort(a, 0, a.length - 1, null, 0, 0);
       
   187     }
       
   188 
       
   189     /**
       
   190      * Sorts the specified range of the array into ascending order. The range
       
   191      * to be sorted extends from the index {@code fromIndex}, inclusive, to
       
   192      * the index {@code toIndex}, exclusive. If {@code fromIndex == toIndex},
       
   193      * the range to be sorted is empty.
       
   194      *
       
   195      * <p>Implementation note: The sorting algorithm is a Dual-Pivot Quicksort
       
   196      * by Vladimir Yaroslavskiy, Jon Bentley, and Joshua Bloch. This algorithm
       
   197      * offers O(n log(n)) performance on many data sets that cause other
       
   198      * quicksorts to degrade to quadratic performance, and is typically
       
   199      * faster than traditional (one-pivot) Quicksort implementations.
       
   200      *
       
   201      * @param a the array to be sorted
       
   202      * @param fromIndex the index of the first element, inclusive, to be sorted
       
   203      * @param toIndex the index of the last element, exclusive, to be sorted
       
   204      *
       
   205      * @throws IllegalArgumentException if {@code fromIndex > toIndex}
       
   206      * @throws ArrayIndexOutOfBoundsException
       
   207      *     if {@code fromIndex < 0} or {@code toIndex > a.length}
       
   208      */
       
   209     public static void sort(long[] a, int fromIndex, int toIndex) {
       
   210         rangeCheck(a.length, fromIndex, toIndex);
       
   211         DualPivotQuicksort.sort(a, fromIndex, toIndex - 1, null, 0, 0);
       
   212     }
       
   213 
       
   214     /**
       
   215      * Sorts the specified array into ascending numerical order.
       
   216      *
       
   217      * <p>Implementation note: The sorting algorithm is a Dual-Pivot Quicksort
       
   218      * by Vladimir Yaroslavskiy, Jon Bentley, and Joshua Bloch. This algorithm
       
   219      * offers O(n log(n)) performance on many data sets that cause other
       
   220      * quicksorts to degrade to quadratic performance, and is typically
       
   221      * faster than traditional (one-pivot) Quicksort implementations.
       
   222      *
       
   223      * @param a the array to be sorted
       
   224      */
       
   225     public static void sort(short[] a) {
       
   226         DualPivotQuicksort.sort(a, 0, a.length - 1, null, 0, 0);
       
   227     }
       
   228 
       
   229     /**
       
   230      * Sorts the specified range of the array into ascending order. The range
       
   231      * to be sorted extends from the index {@code fromIndex}, inclusive, to
       
   232      * the index {@code toIndex}, exclusive. If {@code fromIndex == toIndex},
       
   233      * the range to be sorted is empty.
       
   234      *
       
   235      * <p>Implementation note: The sorting algorithm is a Dual-Pivot Quicksort
       
   236      * by Vladimir Yaroslavskiy, Jon Bentley, and Joshua Bloch. This algorithm
       
   237      * offers O(n log(n)) performance on many data sets that cause other
       
   238      * quicksorts to degrade to quadratic performance, and is typically
       
   239      * faster than traditional (one-pivot) Quicksort implementations.
       
   240      *
       
   241      * @param a the array to be sorted
       
   242      * @param fromIndex the index of the first element, inclusive, to be sorted
       
   243      * @param toIndex the index of the last element, exclusive, to be sorted
       
   244      *
       
   245      * @throws IllegalArgumentException if {@code fromIndex > toIndex}
       
   246      * @throws ArrayIndexOutOfBoundsException
       
   247      *     if {@code fromIndex < 0} or {@code toIndex > a.length}
       
   248      */
       
   249     public static void sort(short[] a, int fromIndex, int toIndex) {
       
   250         rangeCheck(a.length, fromIndex, toIndex);
       
   251         DualPivotQuicksort.sort(a, fromIndex, toIndex - 1, null, 0, 0);
       
   252     }
       
   253 
       
   254     /**
       
   255      * Sorts the specified array into ascending numerical order.
       
   256      *
       
   257      * <p>Implementation note: The sorting algorithm is a Dual-Pivot Quicksort
       
   258      * by Vladimir Yaroslavskiy, Jon Bentley, and Joshua Bloch. This algorithm
       
   259      * offers O(n log(n)) performance on many data sets that cause other
       
   260      * quicksorts to degrade to quadratic performance, and is typically
       
   261      * faster than traditional (one-pivot) Quicksort implementations.
       
   262      *
       
   263      * @param a the array to be sorted
       
   264      */
       
   265     public static void sort(char[] a) {
       
   266         DualPivotQuicksort.sort(a, 0, a.length - 1, null, 0, 0);
       
   267     }
       
   268 
       
   269     /**
       
   270      * Sorts the specified range of the array into ascending order. The range
       
   271      * to be sorted extends from the index {@code fromIndex}, inclusive, to
       
   272      * the index {@code toIndex}, exclusive. If {@code fromIndex == toIndex},
       
   273      * the range to be sorted is empty.
       
   274      *
       
   275      * <p>Implementation note: The sorting algorithm is a Dual-Pivot Quicksort
       
   276      * by Vladimir Yaroslavskiy, Jon Bentley, and Joshua Bloch. This algorithm
       
   277      * offers O(n log(n)) performance on many data sets that cause other
       
   278      * quicksorts to degrade to quadratic performance, and is typically
       
   279      * faster than traditional (one-pivot) Quicksort implementations.
       
   280      *
       
   281      * @param a the array to be sorted
       
   282      * @param fromIndex the index of the first element, inclusive, to be sorted
       
   283      * @param toIndex the index of the last element, exclusive, to be sorted
       
   284      *
       
   285      * @throws IllegalArgumentException if {@code fromIndex > toIndex}
       
   286      * @throws ArrayIndexOutOfBoundsException
       
   287      *     if {@code fromIndex < 0} or {@code toIndex > a.length}
       
   288      */
       
   289     public static void sort(char[] a, int fromIndex, int toIndex) {
       
   290         rangeCheck(a.length, fromIndex, toIndex);
       
   291         DualPivotQuicksort.sort(a, fromIndex, toIndex - 1, null, 0, 0);
       
   292     }
       
   293 
       
   294     /**
       
   295      * Sorts the specified array into ascending numerical order.
       
   296      *
       
   297      * <p>Implementation note: The sorting algorithm is a Dual-Pivot Quicksort
       
   298      * by Vladimir Yaroslavskiy, Jon Bentley, and Joshua Bloch. This algorithm
       
   299      * offers O(n log(n)) performance on many data sets that cause other
       
   300      * quicksorts to degrade to quadratic performance, and is typically
       
   301      * faster than traditional (one-pivot) Quicksort implementations.
       
   302      *
       
   303      * @param a the array to be sorted
       
   304      */
       
   305     public static void sort(byte[] a) {
       
   306         DualPivotQuicksort.sort(a, 0, a.length - 1);
       
   307     }
       
   308 
       
   309     /**
       
   310      * Sorts the specified range of the array into ascending order. The range
       
   311      * to be sorted extends from the index {@code fromIndex}, inclusive, to
       
   312      * the index {@code toIndex}, exclusive. If {@code fromIndex == toIndex},
       
   313      * the range to be sorted is empty.
       
   314      *
       
   315      * <p>Implementation note: The sorting algorithm is a Dual-Pivot Quicksort
       
   316      * by Vladimir Yaroslavskiy, Jon Bentley, and Joshua Bloch. This algorithm
       
   317      * offers O(n log(n)) performance on many data sets that cause other
       
   318      * quicksorts to degrade to quadratic performance, and is typically
       
   319      * faster than traditional (one-pivot) Quicksort implementations.
       
   320      *
       
   321      * @param a the array to be sorted
       
   322      * @param fromIndex the index of the first element, inclusive, to be sorted
       
   323      * @param toIndex the index of the last element, exclusive, to be sorted
       
   324      *
       
   325      * @throws IllegalArgumentException if {@code fromIndex > toIndex}
       
   326      * @throws ArrayIndexOutOfBoundsException
       
   327      *     if {@code fromIndex < 0} or {@code toIndex > a.length}
       
   328      */
       
   329     public static void sort(byte[] a, int fromIndex, int toIndex) {
       
   330         rangeCheck(a.length, fromIndex, toIndex);
       
   331         DualPivotQuicksort.sort(a, fromIndex, toIndex - 1);
       
   332     }
       
   333 
       
   334     /**
       
   335      * Sorts the specified array into ascending numerical order.
       
   336      *
       
   337      * <p>The {@code <} relation does not provide a total order on all float
       
   338      * values: {@code -0.0f == 0.0f} is {@code true} and a {@code Float.NaN}
       
   339      * value compares neither less than, greater than, nor equal to any value,
       
   340      * even itself. This method uses the total order imposed by the method
       
   341      * {@link Float#compareTo}: {@code -0.0f} is treated as less than value
       
   342      * {@code 0.0f} and {@code Float.NaN} is considered greater than any
       
   343      * other value and all {@code Float.NaN} values are considered equal.
       
   344      *
       
   345      * <p>Implementation note: The sorting algorithm is a Dual-Pivot Quicksort
       
   346      * by Vladimir Yaroslavskiy, Jon Bentley, and Joshua Bloch. This algorithm
       
   347      * offers O(n log(n)) performance on many data sets that cause other
       
   348      * quicksorts to degrade to quadratic performance, and is typically
       
   349      * faster than traditional (one-pivot) Quicksort implementations.
       
   350      *
       
   351      * @param a the array to be sorted
       
   352      */
       
   353     public static void sort(float[] a) {
       
   354         DualPivotQuicksort.sort(a, 0, a.length - 1, null, 0, 0);
       
   355     }
       
   356 
       
   357     /**
       
   358      * Sorts the specified range of the array into ascending order. The range
       
   359      * to be sorted extends from the index {@code fromIndex}, inclusive, to
       
   360      * the index {@code toIndex}, exclusive. If {@code fromIndex == toIndex},
       
   361      * the range to be sorted is empty.
       
   362      *
       
   363      * <p>The {@code <} relation does not provide a total order on all float
       
   364      * values: {@code -0.0f == 0.0f} is {@code true} and a {@code Float.NaN}
       
   365      * value compares neither less than, greater than, nor equal to any value,
       
   366      * even itself. This method uses the total order imposed by the method
       
   367      * {@link Float#compareTo}: {@code -0.0f} is treated as less than value
       
   368      * {@code 0.0f} and {@code Float.NaN} is considered greater than any
       
   369      * other value and all {@code Float.NaN} values are considered equal.
       
   370      *
       
   371      * <p>Implementation note: The sorting algorithm is a Dual-Pivot Quicksort
       
   372      * by Vladimir Yaroslavskiy, Jon Bentley, and Joshua Bloch. This algorithm
       
   373      * offers O(n log(n)) performance on many data sets that cause other
       
   374      * quicksorts to degrade to quadratic performance, and is typically
       
   375      * faster than traditional (one-pivot) Quicksort implementations.
       
   376      *
       
   377      * @param a the array to be sorted
       
   378      * @param fromIndex the index of the first element, inclusive, to be sorted
       
   379      * @param toIndex the index of the last element, exclusive, to be sorted
       
   380      *
       
   381      * @throws IllegalArgumentException if {@code fromIndex > toIndex}
       
   382      * @throws ArrayIndexOutOfBoundsException
       
   383      *     if {@code fromIndex < 0} or {@code toIndex > a.length}
       
   384      */
       
   385     public static void sort(float[] a, int fromIndex, int toIndex) {
       
   386         rangeCheck(a.length, fromIndex, toIndex);
       
   387         DualPivotQuicksort.sort(a, fromIndex, toIndex - 1, null, 0, 0);
       
   388     }
       
   389 
       
   390     /**
       
   391      * Sorts the specified array into ascending numerical order.
       
   392      *
       
   393      * <p>The {@code <} relation does not provide a total order on all double
       
   394      * values: {@code -0.0d == 0.0d} is {@code true} and a {@code Double.NaN}
       
   395      * value compares neither less than, greater than, nor equal to any value,
       
   396      * even itself. This method uses the total order imposed by the method
       
   397      * {@link Double#compareTo}: {@code -0.0d} is treated as less than value
       
   398      * {@code 0.0d} and {@code Double.NaN} is considered greater than any
       
   399      * other value and all {@code Double.NaN} values are considered equal.
       
   400      *
       
   401      * <p>Implementation note: The sorting algorithm is a Dual-Pivot Quicksort
       
   402      * by Vladimir Yaroslavskiy, Jon Bentley, and Joshua Bloch. This algorithm
       
   403      * offers O(n log(n)) performance on many data sets that cause other
       
   404      * quicksorts to degrade to quadratic performance, and is typically
       
   405      * faster than traditional (one-pivot) Quicksort implementations.
       
   406      *
       
   407      * @param a the array to be sorted
       
   408      */
       
   409     public static void sort(double[] a) {
       
   410         DualPivotQuicksort.sort(a, 0, a.length - 1, null, 0, 0);
       
   411     }
       
   412 
       
   413     /**
       
   414      * Sorts the specified range of the array into ascending order. The range
       
   415      * to be sorted extends from the index {@code fromIndex}, inclusive, to
       
   416      * the index {@code toIndex}, exclusive. If {@code fromIndex == toIndex},
       
   417      * the range to be sorted is empty.
       
   418      *
       
   419      * <p>The {@code <} relation does not provide a total order on all double
       
   420      * values: {@code -0.0d == 0.0d} is {@code true} and a {@code Double.NaN}
       
   421      * value compares neither less than, greater than, nor equal to any value,
       
   422      * even itself. This method uses the total order imposed by the method
       
   423      * {@link Double#compareTo}: {@code -0.0d} is treated as less than value
       
   424      * {@code 0.0d} and {@code Double.NaN} is considered greater than any
       
   425      * other value and all {@code Double.NaN} values are considered equal.
       
   426      *
       
   427      * <p>Implementation note: The sorting algorithm is a Dual-Pivot Quicksort
       
   428      * by Vladimir Yaroslavskiy, Jon Bentley, and Joshua Bloch. This algorithm
       
   429      * offers O(n log(n)) performance on many data sets that cause other
       
   430      * quicksorts to degrade to quadratic performance, and is typically
       
   431      * faster than traditional (one-pivot) Quicksort implementations.
       
   432      *
       
   433      * @param a the array to be sorted
       
   434      * @param fromIndex the index of the first element, inclusive, to be sorted
       
   435      * @param toIndex the index of the last element, exclusive, to be sorted
       
   436      *
       
   437      * @throws IllegalArgumentException if {@code fromIndex > toIndex}
       
   438      * @throws ArrayIndexOutOfBoundsException
       
   439      *     if {@code fromIndex < 0} or {@code toIndex > a.length}
       
   440      */
       
   441     public static void sort(double[] a, int fromIndex, int toIndex) {
       
   442         rangeCheck(a.length, fromIndex, toIndex);
       
   443         DualPivotQuicksort.sort(a, fromIndex, toIndex - 1, null, 0, 0);
       
   444     }
       
   445 
       
   446     /**
       
   447      * Sorts the specified array into ascending numerical order.
       
   448      *
       
   449      * @implNote The sorting algorithm is a parallel sort-merge that breaks the
       
   450      * array into sub-arrays that are themselves sorted and then merged. When
       
   451      * the sub-array length reaches a minimum granularity, the sub-array is
       
   452      * sorted using the appropriate {@link Arrays#sort(byte[]) Arrays.sort}
       
   453      * method. If the length of the specified array is less than the minimum
       
   454      * granularity, then it is sorted using the appropriate {@link
       
   455      * Arrays#sort(byte[]) Arrays.sort} method. The algorithm requires a
       
   456      * working space no greater than the size of the original array. The
       
   457      * {@link ForkJoinPool#commonPool() ForkJoin common pool} is used to
       
   458      * execute any parallel tasks.
       
   459      *
       
   460      * @param a the array to be sorted
       
   461      *
       
   462      * @since 1.8
       
   463      */
       
   464     public static void parallelSort(byte[] a) {
       
   465         int n = a.length, p, g;
       
   466         if (n <= MIN_ARRAY_SORT_GRAN ||
       
   467             (p = ForkJoinPool.getCommonPoolParallelism()) == 1)
       
   468             DualPivotQuicksort.sort(a, 0, n - 1);
       
   469         else
       
   470             new ArraysParallelSortHelpers.FJByte.Sorter
       
   471                 (null, a, new byte[n], 0, n, 0,
       
   472                  ((g = n / (p << 2)) <= MIN_ARRAY_SORT_GRAN) ?
       
   473                  MIN_ARRAY_SORT_GRAN : g).invoke();
       
   474     }
       
   475 
       
   476     /**
       
   477      * Sorts the specified range of the array into ascending numerical order.
       
   478      * The range to be sorted extends from the index {@code fromIndex},
       
   479      * inclusive, to the index {@code toIndex}, exclusive. If
       
   480      * {@code fromIndex == toIndex}, the range to be sorted is empty.
       
   481      *
       
   482      * @implNote The sorting algorithm is a parallel sort-merge that breaks the
       
   483      * array into sub-arrays that are themselves sorted and then merged. When
       
   484      * the sub-array length reaches a minimum granularity, the sub-array is
       
   485      * sorted using the appropriate {@link Arrays#sort(byte[]) Arrays.sort}
       
   486      * method. If the length of the specified array is less than the minimum
       
   487      * granularity, then it is sorted using the appropriate {@link
       
   488      * Arrays#sort(byte[]) Arrays.sort} method. The algorithm requires a working
       
   489      * space no greater than the size of the specified range of the original
       
   490      * array. The {@link ForkJoinPool#commonPool() ForkJoin common pool} is
       
   491      * used to execute any parallel tasks.
       
   492      *
       
   493      * @param a the array to be sorted
       
   494      * @param fromIndex the index of the first element, inclusive, to be sorted
       
   495      * @param toIndex the index of the last element, exclusive, to be sorted
       
   496      *
       
   497      * @throws IllegalArgumentException if {@code fromIndex > toIndex}
       
   498      * @throws ArrayIndexOutOfBoundsException
       
   499      *     if {@code fromIndex < 0} or {@code toIndex > a.length}
       
   500      *
       
   501      * @since 1.8
       
   502      */
       
   503     public static void parallelSort(byte[] a, int fromIndex, int toIndex) {
       
   504         rangeCheck(a.length, fromIndex, toIndex);
       
   505         int n = toIndex - fromIndex, p, g;
       
   506         if (n <= MIN_ARRAY_SORT_GRAN ||
       
   507             (p = ForkJoinPool.getCommonPoolParallelism()) == 1)
       
   508             DualPivotQuicksort.sort(a, fromIndex, toIndex - 1);
       
   509         else
       
   510             new ArraysParallelSortHelpers.FJByte.Sorter
       
   511                 (null, a, new byte[n], fromIndex, n, 0,
       
   512                  ((g = n / (p << 2)) <= MIN_ARRAY_SORT_GRAN) ?
       
   513                  MIN_ARRAY_SORT_GRAN : g).invoke();
       
   514     }
       
   515 
       
   516     /**
       
   517      * Sorts the specified array into ascending numerical order.
       
   518      *
       
   519      * @implNote The sorting algorithm is a parallel sort-merge that breaks the
       
   520      * array into sub-arrays that are themselves sorted and then merged. When
       
   521      * the sub-array length reaches a minimum granularity, the sub-array is
       
   522      * sorted using the appropriate {@link Arrays#sort(char[]) Arrays.sort}
       
   523      * method. If the length of the specified array is less than the minimum
       
   524      * granularity, then it is sorted using the appropriate {@link
       
   525      * Arrays#sort(char[]) Arrays.sort} method. The algorithm requires a
       
   526      * working space no greater than the size of the original array. The
       
   527      * {@link ForkJoinPool#commonPool() ForkJoin common pool} is used to
       
   528      * execute any parallel tasks.
       
   529      *
       
   530      * @param a the array to be sorted
       
   531      *
       
   532      * @since 1.8
       
   533      */
       
   534     public static void parallelSort(char[] a) {
       
   535         int n = a.length, p, g;
       
   536         if (n <= MIN_ARRAY_SORT_GRAN ||
       
   537             (p = ForkJoinPool.getCommonPoolParallelism()) == 1)
       
   538             DualPivotQuicksort.sort(a, 0, n - 1, null, 0, 0);
       
   539         else
       
   540             new ArraysParallelSortHelpers.FJChar.Sorter
       
   541                 (null, a, new char[n], 0, n, 0,
       
   542                  ((g = n / (p << 2)) <= MIN_ARRAY_SORT_GRAN) ?
       
   543                  MIN_ARRAY_SORT_GRAN : g).invoke();
       
   544     }
       
   545 
       
   546     /**
       
   547      * Sorts the specified range of the array into ascending numerical order.
       
   548      * The range to be sorted extends from the index {@code fromIndex},
       
   549      * inclusive, to the index {@code toIndex}, exclusive. If
       
   550      * {@code fromIndex == toIndex}, the range to be sorted is empty.
       
   551      *
       
   552       @implNote The sorting algorithm is a parallel sort-merge that breaks the
       
   553      * array into sub-arrays that are themselves sorted and then merged. When
       
   554      * the sub-array length reaches a minimum granularity, the sub-array is
       
   555      * sorted using the appropriate {@link Arrays#sort(char[]) Arrays.sort}
       
   556      * method. If the length of the specified array is less than the minimum
       
   557      * granularity, then it is sorted using the appropriate {@link
       
   558      * Arrays#sort(char[]) Arrays.sort} method. The algorithm requires a working
       
   559      * space no greater than the size of the specified range of the original
       
   560      * array. The {@link ForkJoinPool#commonPool() ForkJoin common pool} is
       
   561      * used to execute any parallel tasks.
       
   562      *
       
   563      * @param a the array to be sorted
       
   564      * @param fromIndex the index of the first element, inclusive, to be sorted
       
   565      * @param toIndex the index of the last element, exclusive, to be sorted
       
   566      *
       
   567      * @throws IllegalArgumentException if {@code fromIndex > toIndex}
       
   568      * @throws ArrayIndexOutOfBoundsException
       
   569      *     if {@code fromIndex < 0} or {@code toIndex > a.length}
       
   570      *
       
   571      * @since 1.8
       
   572      */
       
   573     public static void parallelSort(char[] a, int fromIndex, int toIndex) {
       
   574         rangeCheck(a.length, fromIndex, toIndex);
       
   575         int n = toIndex - fromIndex, p, g;
       
   576         if (n <= MIN_ARRAY_SORT_GRAN ||
       
   577             (p = ForkJoinPool.getCommonPoolParallelism()) == 1)
       
   578             DualPivotQuicksort.sort(a, fromIndex, toIndex - 1, null, 0, 0);
       
   579         else
       
   580             new ArraysParallelSortHelpers.FJChar.Sorter
       
   581                 (null, a, new char[n], fromIndex, n, 0,
       
   582                  ((g = n / (p << 2)) <= MIN_ARRAY_SORT_GRAN) ?
       
   583                  MIN_ARRAY_SORT_GRAN : g).invoke();
       
   584     }
       
   585 
       
   586     /**
       
   587      * Sorts the specified array into ascending numerical order.
       
   588      *
       
   589      * @implNote The sorting algorithm is a parallel sort-merge that breaks the
       
   590      * array into sub-arrays that are themselves sorted and then merged. When
       
   591      * the sub-array length reaches a minimum granularity, the sub-array is
       
   592      * sorted using the appropriate {@link Arrays#sort(short[]) Arrays.sort}
       
   593      * method. If the length of the specified array is less than the minimum
       
   594      * granularity, then it is sorted using the appropriate {@link
       
   595      * Arrays#sort(short[]) Arrays.sort} method. The algorithm requires a
       
   596      * working space no greater than the size of the original array. The
       
   597      * {@link ForkJoinPool#commonPool() ForkJoin common pool} is used to
       
   598      * execute any parallel tasks.
       
   599      *
       
   600      * @param a the array to be sorted
       
   601      *
       
   602      * @since 1.8
       
   603      */
       
   604     public static void parallelSort(short[] a) {
       
   605         int n = a.length, p, g;
       
   606         if (n <= MIN_ARRAY_SORT_GRAN ||
       
   607             (p = ForkJoinPool.getCommonPoolParallelism()) == 1)
       
   608             DualPivotQuicksort.sort(a, 0, n - 1, null, 0, 0);
       
   609         else
       
   610             new ArraysParallelSortHelpers.FJShort.Sorter
       
   611                 (null, a, new short[n], 0, n, 0,
       
   612                  ((g = n / (p << 2)) <= MIN_ARRAY_SORT_GRAN) ?
       
   613                  MIN_ARRAY_SORT_GRAN : g).invoke();
       
   614     }
       
   615 
       
   616     /**
       
   617      * Sorts the specified range of the array into ascending numerical order.
       
   618      * The range to be sorted extends from the index {@code fromIndex},
       
   619      * inclusive, to the index {@code toIndex}, exclusive. If
       
   620      * {@code fromIndex == toIndex}, the range to be sorted is empty.
       
   621      *
       
   622      * @implNote The sorting algorithm is a parallel sort-merge that breaks the
       
   623      * array into sub-arrays that are themselves sorted and then merged. When
       
   624      * the sub-array length reaches a minimum granularity, the sub-array is
       
   625      * sorted using the appropriate {@link Arrays#sort(short[]) Arrays.sort}
       
   626      * method. If the length of the specified array is less than the minimum
       
   627      * granularity, then it is sorted using the appropriate {@link
       
   628      * Arrays#sort(short[]) Arrays.sort} method. The algorithm requires a working
       
   629      * space no greater than the size of the specified range of the original
       
   630      * array. The {@link ForkJoinPool#commonPool() ForkJoin common pool} is
       
   631      * used to execute any parallel tasks.
       
   632      *
       
   633      * @param a the array to be sorted
       
   634      * @param fromIndex the index of the first element, inclusive, to be sorted
       
   635      * @param toIndex the index of the last element, exclusive, to be sorted
       
   636      *
       
   637      * @throws IllegalArgumentException if {@code fromIndex > toIndex}
       
   638      * @throws ArrayIndexOutOfBoundsException
       
   639      *     if {@code fromIndex < 0} or {@code toIndex > a.length}
       
   640      *
       
   641      * @since 1.8
       
   642      */
       
   643     public static void parallelSort(short[] a, int fromIndex, int toIndex) {
       
   644         rangeCheck(a.length, fromIndex, toIndex);
       
   645         int n = toIndex - fromIndex, p, g;
       
   646         if (n <= MIN_ARRAY_SORT_GRAN ||
       
   647             (p = ForkJoinPool.getCommonPoolParallelism()) == 1)
       
   648             DualPivotQuicksort.sort(a, fromIndex, toIndex - 1, null, 0, 0);
       
   649         else
       
   650             new ArraysParallelSortHelpers.FJShort.Sorter
       
   651                 (null, a, new short[n], fromIndex, n, 0,
       
   652                  ((g = n / (p << 2)) <= MIN_ARRAY_SORT_GRAN) ?
       
   653                  MIN_ARRAY_SORT_GRAN : g).invoke();
       
   654     }
       
   655 
       
   656     /**
       
   657      * Sorts the specified array into ascending numerical order.
       
   658      *
       
   659      * @implNote The sorting algorithm is a parallel sort-merge that breaks the
       
   660      * array into sub-arrays that are themselves sorted and then merged. When
       
   661      * the sub-array length reaches a minimum granularity, the sub-array is
       
   662      * sorted using the appropriate {@link Arrays#sort(int[]) Arrays.sort}
       
   663      * method. If the length of the specified array is less than the minimum
       
   664      * granularity, then it is sorted using the appropriate {@link
       
   665      * Arrays#sort(int[]) Arrays.sort} method. The algorithm requires a
       
   666      * working space no greater than the size of the original array. The
       
   667      * {@link ForkJoinPool#commonPool() ForkJoin common pool} is used to
       
   668      * execute any parallel tasks.
       
   669      *
       
   670      * @param a the array to be sorted
       
   671      *
       
   672      * @since 1.8
       
   673      */
       
   674     public static void parallelSort(int[] a) {
       
   675         int n = a.length, p, g;
       
   676         if (n <= MIN_ARRAY_SORT_GRAN ||
       
   677             (p = ForkJoinPool.getCommonPoolParallelism()) == 1)
       
   678             DualPivotQuicksort.sort(a, 0, n - 1, null, 0, 0);
       
   679         else
       
   680             new ArraysParallelSortHelpers.FJInt.Sorter
       
   681                 (null, a, new int[n], 0, n, 0,
       
   682                  ((g = n / (p << 2)) <= MIN_ARRAY_SORT_GRAN) ?
       
   683                  MIN_ARRAY_SORT_GRAN : g).invoke();
       
   684     }
       
   685 
       
   686     /**
       
   687      * Sorts the specified range of the array into ascending numerical order.
       
   688      * The range to be sorted extends from the index {@code fromIndex},
       
   689      * inclusive, to the index {@code toIndex}, exclusive. If
       
   690      * {@code fromIndex == toIndex}, the range to be sorted is empty.
       
   691      *
       
   692      * @implNote The sorting algorithm is a parallel sort-merge that breaks the
       
   693      * array into sub-arrays that are themselves sorted and then merged. When
       
   694      * the sub-array length reaches a minimum granularity, the sub-array is
       
   695      * sorted using the appropriate {@link Arrays#sort(int[]) Arrays.sort}
       
   696      * method. If the length of the specified array is less than the minimum
       
   697      * granularity, then it is sorted using the appropriate {@link
       
   698      * Arrays#sort(int[]) Arrays.sort} method. The algorithm requires a working
       
   699      * space no greater than the size of the specified range of the original
       
   700      * array. The {@link ForkJoinPool#commonPool() ForkJoin common pool} is
       
   701      * used to execute any parallel tasks.
       
   702      *
       
   703      * @param a the array to be sorted
       
   704      * @param fromIndex the index of the first element, inclusive, to be sorted
       
   705      * @param toIndex the index of the last element, exclusive, to be sorted
       
   706      *
       
   707      * @throws IllegalArgumentException if {@code fromIndex > toIndex}
       
   708      * @throws ArrayIndexOutOfBoundsException
       
   709      *     if {@code fromIndex < 0} or {@code toIndex > a.length}
       
   710      *
       
   711      * @since 1.8
       
   712      */
       
   713     public static void parallelSort(int[] a, int fromIndex, int toIndex) {
       
   714         rangeCheck(a.length, fromIndex, toIndex);
       
   715         int n = toIndex - fromIndex, p, g;
       
   716         if (n <= MIN_ARRAY_SORT_GRAN ||
       
   717             (p = ForkJoinPool.getCommonPoolParallelism()) == 1)
       
   718             DualPivotQuicksort.sort(a, fromIndex, toIndex - 1, null, 0, 0);
       
   719         else
       
   720             new ArraysParallelSortHelpers.FJInt.Sorter
       
   721                 (null, a, new int[n], fromIndex, n, 0,
       
   722                  ((g = n / (p << 2)) <= MIN_ARRAY_SORT_GRAN) ?
       
   723                  MIN_ARRAY_SORT_GRAN : g).invoke();
       
   724     }
       
   725 
       
   726     /**
       
   727      * Sorts the specified array into ascending numerical order.
       
   728      *
       
   729      * @implNote The sorting algorithm is a parallel sort-merge that breaks the
       
   730      * array into sub-arrays that are themselves sorted and then merged. When
       
   731      * the sub-array length reaches a minimum granularity, the sub-array is
       
   732      * sorted using the appropriate {@link Arrays#sort(long[]) Arrays.sort}
       
   733      * method. If the length of the specified array is less than the minimum
       
   734      * granularity, then it is sorted using the appropriate {@link
       
   735      * Arrays#sort(long[]) Arrays.sort} method. The algorithm requires a
       
   736      * working space no greater than the size of the original array. The
       
   737      * {@link ForkJoinPool#commonPool() ForkJoin common pool} is used to
       
   738      * execute any parallel tasks.
       
   739      *
       
   740      * @param a the array to be sorted
       
   741      *
       
   742      * @since 1.8
       
   743      */
       
   744     public static void parallelSort(long[] a) {
       
   745         int n = a.length, p, g;
       
   746         if (n <= MIN_ARRAY_SORT_GRAN ||
       
   747             (p = ForkJoinPool.getCommonPoolParallelism()) == 1)
       
   748             DualPivotQuicksort.sort(a, 0, n - 1, null, 0, 0);
       
   749         else
       
   750             new ArraysParallelSortHelpers.FJLong.Sorter
       
   751                 (null, a, new long[n], 0, n, 0,
       
   752                  ((g = n / (p << 2)) <= MIN_ARRAY_SORT_GRAN) ?
       
   753                  MIN_ARRAY_SORT_GRAN : g).invoke();
       
   754     }
       
   755 
       
   756     /**
       
   757      * Sorts the specified range of the array into ascending numerical order.
       
   758      * The range to be sorted extends from the index {@code fromIndex},
       
   759      * inclusive, to the index {@code toIndex}, exclusive. If
       
   760      * {@code fromIndex == toIndex}, the range to be sorted is empty.
       
   761      *
       
   762      * @implNote The sorting algorithm is a parallel sort-merge that breaks the
       
   763      * array into sub-arrays that are themselves sorted and then merged. When
       
   764      * the sub-array length reaches a minimum granularity, the sub-array is
       
   765      * sorted using the appropriate {@link Arrays#sort(long[]) Arrays.sort}
       
   766      * method. If the length of the specified array is less than the minimum
       
   767      * granularity, then it is sorted using the appropriate {@link
       
   768      * Arrays#sort(long[]) Arrays.sort} method. The algorithm requires a working
       
   769      * space no greater than the size of the specified range of the original
       
   770      * array. The {@link ForkJoinPool#commonPool() ForkJoin common pool} is
       
   771      * used to execute any parallel tasks.
       
   772      *
       
   773      * @param a the array to be sorted
       
   774      * @param fromIndex the index of the first element, inclusive, to be sorted
       
   775      * @param toIndex the index of the last element, exclusive, to be sorted
       
   776      *
       
   777      * @throws IllegalArgumentException if {@code fromIndex > toIndex}
       
   778      * @throws ArrayIndexOutOfBoundsException
       
   779      *     if {@code fromIndex < 0} or {@code toIndex > a.length}
       
   780      *
       
   781      * @since 1.8
       
   782      */
       
   783     public static void parallelSort(long[] a, int fromIndex, int toIndex) {
       
   784         rangeCheck(a.length, fromIndex, toIndex);
       
   785         int n = toIndex - fromIndex, p, g;
       
   786         if (n <= MIN_ARRAY_SORT_GRAN ||
       
   787             (p = ForkJoinPool.getCommonPoolParallelism()) == 1)
       
   788             DualPivotQuicksort.sort(a, fromIndex, toIndex - 1, null, 0, 0);
       
   789         else
       
   790             new ArraysParallelSortHelpers.FJLong.Sorter
       
   791                 (null, a, new long[n], fromIndex, n, 0,
       
   792                  ((g = n / (p << 2)) <= MIN_ARRAY_SORT_GRAN) ?
       
   793                  MIN_ARRAY_SORT_GRAN : g).invoke();
       
   794     }
       
   795 
       
   796     /**
       
   797      * Sorts the specified array into ascending numerical order.
       
   798      *
       
   799      * <p>The {@code <} relation does not provide a total order on all float
       
   800      * values: {@code -0.0f == 0.0f} is {@code true} and a {@code Float.NaN}
       
   801      * value compares neither less than, greater than, nor equal to any value,
       
   802      * even itself. This method uses the total order imposed by the method
       
   803      * {@link Float#compareTo}: {@code -0.0f} is treated as less than value
       
   804      * {@code 0.0f} and {@code Float.NaN} is considered greater than any
       
   805      * other value and all {@code Float.NaN} values are considered equal.
       
   806      *
       
   807      * @implNote The sorting algorithm is a parallel sort-merge that breaks the
       
   808      * array into sub-arrays that are themselves sorted and then merged. When
       
   809      * the sub-array length reaches a minimum granularity, the sub-array is
       
   810      * sorted using the appropriate {@link Arrays#sort(float[]) Arrays.sort}
       
   811      * method. If the length of the specified array is less than the minimum
       
   812      * granularity, then it is sorted using the appropriate {@link
       
   813      * Arrays#sort(float[]) Arrays.sort} method. The algorithm requires a
       
   814      * working space no greater than the size of the original array. The
       
   815      * {@link ForkJoinPool#commonPool() ForkJoin common pool} is used to
       
   816      * execute any parallel tasks.
       
   817      *
       
   818      * @param a the array to be sorted
       
   819      *
       
   820      * @since 1.8
       
   821      */
       
   822     public static void parallelSort(float[] a) {
       
   823         int n = a.length, p, g;
       
   824         if (n <= MIN_ARRAY_SORT_GRAN ||
       
   825             (p = ForkJoinPool.getCommonPoolParallelism()) == 1)
       
   826             DualPivotQuicksort.sort(a, 0, n - 1, null, 0, 0);
       
   827         else
       
   828             new ArraysParallelSortHelpers.FJFloat.Sorter
       
   829                 (null, a, new float[n], 0, n, 0,
       
   830                  ((g = n / (p << 2)) <= MIN_ARRAY_SORT_GRAN) ?
       
   831                  MIN_ARRAY_SORT_GRAN : g).invoke();
       
   832     }
       
   833 
       
   834     /**
       
   835      * Sorts the specified range of the array into ascending numerical order.
       
   836      * The range to be sorted extends from the index {@code fromIndex},
       
   837      * inclusive, to the index {@code toIndex}, exclusive. If
       
   838      * {@code fromIndex == toIndex}, the range to be sorted is empty.
       
   839      *
       
   840      * <p>The {@code <} relation does not provide a total order on all float
       
   841      * values: {@code -0.0f == 0.0f} is {@code true} and a {@code Float.NaN}
       
   842      * value compares neither less than, greater than, nor equal to any value,
       
   843      * even itself. This method uses the total order imposed by the method
       
   844      * {@link Float#compareTo}: {@code -0.0f} is treated as less than value
       
   845      * {@code 0.0f} and {@code Float.NaN} is considered greater than any
       
   846      * other value and all {@code Float.NaN} values are considered equal.
       
   847      *
       
   848      * @implNote The sorting algorithm is a parallel sort-merge that breaks the
       
   849      * array into sub-arrays that are themselves sorted and then merged. When
       
   850      * the sub-array length reaches a minimum granularity, the sub-array is
       
   851      * sorted using the appropriate {@link Arrays#sort(float[]) Arrays.sort}
       
   852      * method. If the length of the specified array is less than the minimum
       
   853      * granularity, then it is sorted using the appropriate {@link
       
   854      * Arrays#sort(float[]) Arrays.sort} method. The algorithm requires a working
       
   855      * space no greater than the size of the specified range of the original
       
   856      * array. The {@link ForkJoinPool#commonPool() ForkJoin common pool} is
       
   857      * used to execute any parallel tasks.
       
   858      *
       
   859      * @param a the array to be sorted
       
   860      * @param fromIndex the index of the first element, inclusive, to be sorted
       
   861      * @param toIndex the index of the last element, exclusive, to be sorted
       
   862      *
       
   863      * @throws IllegalArgumentException if {@code fromIndex > toIndex}
       
   864      * @throws ArrayIndexOutOfBoundsException
       
   865      *     if {@code fromIndex < 0} or {@code toIndex > a.length}
       
   866      *
       
   867      * @since 1.8
       
   868      */
       
   869     public static void parallelSort(float[] a, int fromIndex, int toIndex) {
       
   870         rangeCheck(a.length, fromIndex, toIndex);
       
   871         int n = toIndex - fromIndex, p, g;
       
   872         if (n <= MIN_ARRAY_SORT_GRAN ||
       
   873             (p = ForkJoinPool.getCommonPoolParallelism()) == 1)
       
   874             DualPivotQuicksort.sort(a, fromIndex, toIndex - 1, null, 0, 0);
       
   875         else
       
   876             new ArraysParallelSortHelpers.FJFloat.Sorter
       
   877                 (null, a, new float[n], fromIndex, n, 0,
       
   878                  ((g = n / (p << 2)) <= MIN_ARRAY_SORT_GRAN) ?
       
   879                  MIN_ARRAY_SORT_GRAN : g).invoke();
       
   880     }
       
   881 
       
   882     /**
       
   883      * Sorts the specified array into ascending numerical order.
       
   884      *
       
   885      * <p>The {@code <} relation does not provide a total order on all double
       
   886      * values: {@code -0.0d == 0.0d} is {@code true} and a {@code Double.NaN}
       
   887      * value compares neither less than, greater than, nor equal to any value,
       
   888      * even itself. This method uses the total order imposed by the method
       
   889      * {@link Double#compareTo}: {@code -0.0d} is treated as less than value
       
   890      * {@code 0.0d} and {@code Double.NaN} is considered greater than any
       
   891      * other value and all {@code Double.NaN} values are considered equal.
       
   892      *
       
   893      * @implNote The sorting algorithm is a parallel sort-merge that breaks the
       
   894      * array into sub-arrays that are themselves sorted and then merged. When
       
   895      * the sub-array length reaches a minimum granularity, the sub-array is
       
   896      * sorted using the appropriate {@link Arrays#sort(double[]) Arrays.sort}
       
   897      * method. If the length of the specified array is less than the minimum
       
   898      * granularity, then it is sorted using the appropriate {@link
       
   899      * Arrays#sort(double[]) Arrays.sort} method. The algorithm requires a
       
   900      * working space no greater than the size of the original array. The
       
   901      * {@link ForkJoinPool#commonPool() ForkJoin common pool} is used to
       
   902      * execute any parallel tasks.
       
   903      *
       
   904      * @param a the array to be sorted
       
   905      *
       
   906      * @since 1.8
       
   907      */
       
   908     public static void parallelSort(double[] a) {
       
   909         int n = a.length, p, g;
       
   910         if (n <= MIN_ARRAY_SORT_GRAN ||
       
   911             (p = ForkJoinPool.getCommonPoolParallelism()) == 1)
       
   912             DualPivotQuicksort.sort(a, 0, n - 1, null, 0, 0);
       
   913         else
       
   914             new ArraysParallelSortHelpers.FJDouble.Sorter
       
   915                 (null, a, new double[n], 0, n, 0,
       
   916                  ((g = n / (p << 2)) <= MIN_ARRAY_SORT_GRAN) ?
       
   917                  MIN_ARRAY_SORT_GRAN : g).invoke();
       
   918     }
       
   919 
       
   920     /**
       
   921      * Sorts the specified range of the array into ascending numerical order.
       
   922      * The range to be sorted extends from the index {@code fromIndex},
       
   923      * inclusive, to the index {@code toIndex}, exclusive. If
       
   924      * {@code fromIndex == toIndex}, the range to be sorted is empty.
       
   925      *
       
   926      * <p>The {@code <} relation does not provide a total order on all double
       
   927      * values: {@code -0.0d == 0.0d} is {@code true} and a {@code Double.NaN}
       
   928      * value compares neither less than, greater than, nor equal to any value,
       
   929      * even itself. This method uses the total order imposed by the method
       
   930      * {@link Double#compareTo}: {@code -0.0d} is treated as less than value
       
   931      * {@code 0.0d} and {@code Double.NaN} is considered greater than any
       
   932      * other value and all {@code Double.NaN} values are considered equal.
       
   933      *
       
   934      * @implNote The sorting algorithm is a parallel sort-merge that breaks the
       
   935      * array into sub-arrays that are themselves sorted and then merged. When
       
   936      * the sub-array length reaches a minimum granularity, the sub-array is
       
   937      * sorted using the appropriate {@link Arrays#sort(double[]) Arrays.sort}
       
   938      * method. If the length of the specified array is less than the minimum
       
   939      * granularity, then it is sorted using the appropriate {@link
       
   940      * Arrays#sort(double[]) Arrays.sort} method. The algorithm requires a working
       
   941      * space no greater than the size of the specified range of the original
       
   942      * array. The {@link ForkJoinPool#commonPool() ForkJoin common pool} is
       
   943      * used to execute any parallel tasks.
       
   944      *
       
   945      * @param a the array to be sorted
       
   946      * @param fromIndex the index of the first element, inclusive, to be sorted
       
   947      * @param toIndex the index of the last element, exclusive, to be sorted
       
   948      *
       
   949      * @throws IllegalArgumentException if {@code fromIndex > toIndex}
       
   950      * @throws ArrayIndexOutOfBoundsException
       
   951      *     if {@code fromIndex < 0} or {@code toIndex > a.length}
       
   952      *
       
   953      * @since 1.8
       
   954      */
       
   955     public static void parallelSort(double[] a, int fromIndex, int toIndex) {
       
   956         rangeCheck(a.length, fromIndex, toIndex);
       
   957         int n = toIndex - fromIndex, p, g;
       
   958         if (n <= MIN_ARRAY_SORT_GRAN ||
       
   959             (p = ForkJoinPool.getCommonPoolParallelism()) == 1)
       
   960             DualPivotQuicksort.sort(a, fromIndex, toIndex - 1, null, 0, 0);
       
   961         else
       
   962             new ArraysParallelSortHelpers.FJDouble.Sorter
       
   963                 (null, a, new double[n], fromIndex, n, 0,
       
   964                  ((g = n / (p << 2)) <= MIN_ARRAY_SORT_GRAN) ?
       
   965                  MIN_ARRAY_SORT_GRAN : g).invoke();
       
   966     }
       
   967 
       
   968     /**
       
   969      * Sorts the specified array of objects into ascending order, according
       
   970      * to the {@linkplain Comparable natural ordering} of its elements.
       
   971      * All elements in the array must implement the {@link Comparable}
       
   972      * interface.  Furthermore, all elements in the array must be
       
   973      * <i>mutually comparable</i> (that is, {@code e1.compareTo(e2)} must
       
   974      * not throw a {@code ClassCastException} for any elements {@code e1}
       
   975      * and {@code e2} in the array).
       
   976      *
       
   977      * <p>This sort is guaranteed to be <i>stable</i>:  equal elements will
       
   978      * not be reordered as a result of the sort.
       
   979      *
       
   980      * @implNote The sorting algorithm is a parallel sort-merge that breaks the
       
   981      * array into sub-arrays that are themselves sorted and then merged. When
       
   982      * the sub-array length reaches a minimum granularity, the sub-array is
       
   983      * sorted using the appropriate {@link Arrays#sort(Object[]) Arrays.sort}
       
   984      * method. If the length of the specified array is less than the minimum
       
   985      * granularity, then it is sorted using the appropriate {@link
       
   986      * Arrays#sort(Object[]) Arrays.sort} method. The algorithm requires a
       
   987      * working space no greater than the size of the original array. The
       
   988      * {@link ForkJoinPool#commonPool() ForkJoin common pool} is used to
       
   989      * execute any parallel tasks.
       
   990      *
       
   991      * @param <T> the class of the objects to be sorted
       
   992      * @param a the array to be sorted
       
   993      *
       
   994      * @throws ClassCastException if the array contains elements that are not
       
   995      *         <i>mutually comparable</i> (for example, strings and integers)
       
   996      * @throws IllegalArgumentException (optional) if the natural
       
   997      *         ordering of the array elements is found to violate the
       
   998      *         {@link Comparable} contract
       
   999      *
       
  1000      * @since 1.8
       
  1001      */
       
  1002     @SuppressWarnings("unchecked")
       
  1003     public static <T extends Comparable<? super T>> void parallelSort(T[] a) {
       
  1004         int n = a.length, p, g;
       
  1005         if (n <= MIN_ARRAY_SORT_GRAN ||
       
  1006             (p = ForkJoinPool.getCommonPoolParallelism()) == 1)
       
  1007             TimSort.sort(a, 0, n, NaturalOrder.INSTANCE, null, 0, 0);
       
  1008         else
       
  1009             new ArraysParallelSortHelpers.FJObject.Sorter<>
       
  1010                 (null, a,
       
  1011                  (T[])Array.newInstance(a.getClass().getComponentType(), n),
       
  1012                  0, n, 0, ((g = n / (p << 2)) <= MIN_ARRAY_SORT_GRAN) ?
       
  1013                  MIN_ARRAY_SORT_GRAN : g, NaturalOrder.INSTANCE).invoke();
       
  1014     }
       
  1015 
       
  1016     /**
       
  1017      * Sorts the specified range of the specified array of objects into
       
  1018      * ascending order, according to the
       
  1019      * {@linkplain Comparable natural ordering} of its
       
  1020      * elements.  The range to be sorted extends from index
       
  1021      * {@code fromIndex}, inclusive, to index {@code toIndex}, exclusive.
       
  1022      * (If {@code fromIndex==toIndex}, the range to be sorted is empty.)  All
       
  1023      * elements in this range must implement the {@link Comparable}
       
  1024      * interface.  Furthermore, all elements in this range must be <i>mutually
       
  1025      * comparable</i> (that is, {@code e1.compareTo(e2)} must not throw a
       
  1026      * {@code ClassCastException} for any elements {@code e1} and
       
  1027      * {@code e2} in the array).
       
  1028      *
       
  1029      * <p>This sort is guaranteed to be <i>stable</i>:  equal elements will
       
  1030      * not be reordered as a result of the sort.
       
  1031      *
       
  1032      * @implNote The sorting algorithm is a parallel sort-merge that breaks the
       
  1033      * array into sub-arrays that are themselves sorted and then merged. When
       
  1034      * the sub-array length reaches a minimum granularity, the sub-array is
       
  1035      * sorted using the appropriate {@link Arrays#sort(Object[]) Arrays.sort}
       
  1036      * method. If the length of the specified array is less than the minimum
       
  1037      * granularity, then it is sorted using the appropriate {@link
       
  1038      * Arrays#sort(Object[]) Arrays.sort} method. The algorithm requires a working
       
  1039      * space no greater than the size of the specified range of the original
       
  1040      * array. The {@link ForkJoinPool#commonPool() ForkJoin common pool} is
       
  1041      * used to execute any parallel tasks.
       
  1042      *
       
  1043      * @param <T> the class of the objects to be sorted
       
  1044      * @param a the array to be sorted
       
  1045      * @param fromIndex the index of the first element (inclusive) to be
       
  1046      *        sorted
       
  1047      * @param toIndex the index of the last element (exclusive) to be sorted
       
  1048      * @throws IllegalArgumentException if {@code fromIndex > toIndex} or
       
  1049      *         (optional) if the natural ordering of the array elements is
       
  1050      *         found to violate the {@link Comparable} contract
       
  1051      * @throws ArrayIndexOutOfBoundsException if {@code fromIndex < 0} or
       
  1052      *         {@code toIndex > a.length}
       
  1053      * @throws ClassCastException if the array contains elements that are
       
  1054      *         not <i>mutually comparable</i> (for example, strings and
       
  1055      *         integers).
       
  1056      *
       
  1057      * @since 1.8
       
  1058      */
       
  1059     @SuppressWarnings("unchecked")
       
  1060     public static <T extends Comparable<? super T>>
       
  1061     void parallelSort(T[] a, int fromIndex, int toIndex) {
       
  1062         rangeCheck(a.length, fromIndex, toIndex);
       
  1063         int n = toIndex - fromIndex, p, g;
       
  1064         if (n <= MIN_ARRAY_SORT_GRAN ||
       
  1065             (p = ForkJoinPool.getCommonPoolParallelism()) == 1)
       
  1066             TimSort.sort(a, fromIndex, toIndex, NaturalOrder.INSTANCE, null, 0, 0);
       
  1067         else
       
  1068             new ArraysParallelSortHelpers.FJObject.Sorter<>
       
  1069                 (null, a,
       
  1070                  (T[])Array.newInstance(a.getClass().getComponentType(), n),
       
  1071                  fromIndex, n, 0, ((g = n / (p << 2)) <= MIN_ARRAY_SORT_GRAN) ?
       
  1072                  MIN_ARRAY_SORT_GRAN : g, NaturalOrder.INSTANCE).invoke();
       
  1073     }
       
  1074 
       
  1075     /**
       
  1076      * Sorts the specified array of objects according to the order induced by
       
  1077      * the specified comparator.  All elements in the array must be
       
  1078      * <i>mutually comparable</i> by the specified comparator (that is,
       
  1079      * {@code c.compare(e1, e2)} must not throw a {@code ClassCastException}
       
  1080      * for any elements {@code e1} and {@code e2} in the array).
       
  1081      *
       
  1082      * <p>This sort is guaranteed to be <i>stable</i>:  equal elements will
       
  1083      * not be reordered as a result of the sort.
       
  1084      *
       
  1085      * @implNote The sorting algorithm is a parallel sort-merge that breaks the
       
  1086      * array into sub-arrays that are themselves sorted and then merged. When
       
  1087      * the sub-array length reaches a minimum granularity, the sub-array is
       
  1088      * sorted using the appropriate {@link Arrays#sort(Object[]) Arrays.sort}
       
  1089      * method. If the length of the specified array is less than the minimum
       
  1090      * granularity, then it is sorted using the appropriate {@link
       
  1091      * Arrays#sort(Object[]) Arrays.sort} method. The algorithm requires a
       
  1092      * working space no greater than the size of the original array. The
       
  1093      * {@link ForkJoinPool#commonPool() ForkJoin common pool} is used to
       
  1094      * execute any parallel tasks.
       
  1095      *
       
  1096      * @param <T> the class of the objects to be sorted
       
  1097      * @param a the array to be sorted
       
  1098      * @param cmp the comparator to determine the order of the array.  A
       
  1099      *        {@code null} value indicates that the elements'
       
  1100      *        {@linkplain Comparable natural ordering} should be used.
       
  1101      * @throws ClassCastException if the array contains elements that are
       
  1102      *         not <i>mutually comparable</i> using the specified comparator
       
  1103      * @throws IllegalArgumentException (optional) if the comparator is
       
  1104      *         found to violate the {@link java.util.Comparator} contract
       
  1105      *
       
  1106      * @since 1.8
       
  1107      */
       
  1108     @SuppressWarnings("unchecked")
       
  1109     public static <T> void parallelSort(T[] a, Comparator<? super T> cmp) {
       
  1110         if (cmp == null)
       
  1111             cmp = NaturalOrder.INSTANCE;
       
  1112         int n = a.length, p, g;
       
  1113         if (n <= MIN_ARRAY_SORT_GRAN ||
       
  1114             (p = ForkJoinPool.getCommonPoolParallelism()) == 1)
       
  1115             TimSort.sort(a, 0, n, cmp, null, 0, 0);
       
  1116         else
       
  1117             new ArraysParallelSortHelpers.FJObject.Sorter<>
       
  1118                 (null, a,
       
  1119                  (T[])Array.newInstance(a.getClass().getComponentType(), n),
       
  1120                  0, n, 0, ((g = n / (p << 2)) <= MIN_ARRAY_SORT_GRAN) ?
       
  1121                  MIN_ARRAY_SORT_GRAN : g, cmp).invoke();
       
  1122     }
       
  1123 
       
  1124     /**
       
  1125      * Sorts the specified range of the specified array of objects according
       
  1126      * to the order induced by the specified comparator.  The range to be
       
  1127      * sorted extends from index {@code fromIndex}, inclusive, to index
       
  1128      * {@code toIndex}, exclusive.  (If {@code fromIndex==toIndex}, the
       
  1129      * range to be sorted is empty.)  All elements in the range must be
       
  1130      * <i>mutually comparable</i> by the specified comparator (that is,
       
  1131      * {@code c.compare(e1, e2)} must not throw a {@code ClassCastException}
       
  1132      * for any elements {@code e1} and {@code e2} in the range).
       
  1133      *
       
  1134      * <p>This sort is guaranteed to be <i>stable</i>:  equal elements will
       
  1135      * not be reordered as a result of the sort.
       
  1136      *
       
  1137      * @implNote The sorting algorithm is a parallel sort-merge that breaks the
       
  1138      * array into sub-arrays that are themselves sorted and then merged. When
       
  1139      * the sub-array length reaches a minimum granularity, the sub-array is
       
  1140      * sorted using the appropriate {@link Arrays#sort(Object[]) Arrays.sort}
       
  1141      * method. If the length of the specified array is less than the minimum
       
  1142      * granularity, then it is sorted using the appropriate {@link
       
  1143      * Arrays#sort(Object[]) Arrays.sort} method. The algorithm requires a working
       
  1144      * space no greater than the size of the specified range of the original
       
  1145      * array. The {@link ForkJoinPool#commonPool() ForkJoin common pool} is
       
  1146      * used to execute any parallel tasks.
       
  1147      *
       
  1148      * @param <T> the class of the objects to be sorted
       
  1149      * @param a the array to be sorted
       
  1150      * @param fromIndex the index of the first element (inclusive) to be
       
  1151      *        sorted
       
  1152      * @param toIndex the index of the last element (exclusive) to be sorted
       
  1153      * @param cmp the comparator to determine the order of the array.  A
       
  1154      *        {@code null} value indicates that the elements'
       
  1155      *        {@linkplain Comparable natural ordering} should be used.
       
  1156      * @throws IllegalArgumentException if {@code fromIndex > toIndex} or
       
  1157      *         (optional) if the natural ordering of the array elements is
       
  1158      *         found to violate the {@link Comparable} contract
       
  1159      * @throws ArrayIndexOutOfBoundsException if {@code fromIndex < 0} or
       
  1160      *         {@code toIndex > a.length}
       
  1161      * @throws ClassCastException if the array contains elements that are
       
  1162      *         not <i>mutually comparable</i> (for example, strings and
       
  1163      *         integers).
       
  1164      *
       
  1165      * @since 1.8
       
  1166      */
       
  1167     @SuppressWarnings("unchecked")
       
  1168     public static <T> void parallelSort(T[] a, int fromIndex, int toIndex,
       
  1169                                         Comparator<? super T> cmp) {
       
  1170         rangeCheck(a.length, fromIndex, toIndex);
       
  1171         if (cmp == null)
       
  1172             cmp = NaturalOrder.INSTANCE;
       
  1173         int n = toIndex - fromIndex, p, g;
       
  1174         if (n <= MIN_ARRAY_SORT_GRAN ||
       
  1175             (p = ForkJoinPool.getCommonPoolParallelism()) == 1)
       
  1176             TimSort.sort(a, fromIndex, toIndex, cmp, null, 0, 0);
       
  1177         else
       
  1178             new ArraysParallelSortHelpers.FJObject.Sorter<>
       
  1179                 (null, a,
       
  1180                  (T[])Array.newInstance(a.getClass().getComponentType(), n),
       
  1181                  fromIndex, n, 0, ((g = n / (p << 2)) <= MIN_ARRAY_SORT_GRAN) ?
       
  1182                  MIN_ARRAY_SORT_GRAN : g, cmp).invoke();
       
  1183     }
       
  1184 
       
  1185     /*
       
  1186      * Sorting of complex type arrays.
       
  1187      */
       
  1188 
       
  1189     /**
       
  1190      * Old merge sort implementation can be selected (for
       
  1191      * compatibility with broken comparators) using a system property.
       
  1192      * Cannot be a static boolean in the enclosing class due to
       
  1193      * circular dependencies. To be removed in a future release.
       
  1194      */
       
  1195     static final class LegacyMergeSort {
       
  1196         private static final boolean userRequested =
       
  1197             java.security.AccessController.doPrivileged(
       
  1198                 new sun.security.action.GetBooleanAction(
       
  1199                     "java.util.Arrays.useLegacyMergeSort")).booleanValue();
       
  1200     }
       
  1201 
       
  1202     /**
       
  1203      * Sorts the specified array of objects into ascending order, according
       
  1204      * to the {@linkplain Comparable natural ordering} of its elements.
       
  1205      * All elements in the array must implement the {@link Comparable}
       
  1206      * interface.  Furthermore, all elements in the array must be
       
  1207      * <i>mutually comparable</i> (that is, {@code e1.compareTo(e2)} must
       
  1208      * not throw a {@code ClassCastException} for any elements {@code e1}
       
  1209      * and {@code e2} in the array).
       
  1210      *
       
  1211      * <p>This sort is guaranteed to be <i>stable</i>:  equal elements will
       
  1212      * not be reordered as a result of the sort.
       
  1213      *
       
  1214      * <p>Implementation note: This implementation is a stable, adaptive,
       
  1215      * iterative mergesort that requires far fewer than n lg(n) comparisons
       
  1216      * when the input array is partially sorted, while offering the
       
  1217      * performance of a traditional mergesort when the input array is
       
  1218      * randomly ordered.  If the input array is nearly sorted, the
       
  1219      * implementation requires approximately n comparisons.  Temporary
       
  1220      * storage requirements vary from a small constant for nearly sorted
       
  1221      * input arrays to n/2 object references for randomly ordered input
       
  1222      * arrays.
       
  1223      *
       
  1224      * <p>The implementation takes equal advantage of ascending and
       
  1225      * descending order in its input array, and can take advantage of
       
  1226      * ascending and descending order in different parts of the same
       
  1227      * input array.  It is well-suited to merging two or more sorted arrays:
       
  1228      * simply concatenate the arrays and sort the resulting array.
       
  1229      *
       
  1230      * <p>The implementation was adapted from Tim Peters's list sort for Python
       
  1231      * (<a href="http://svn.python.org/projects/python/trunk/Objects/listsort.txt">
       
  1232      * TimSort</a>).  It uses techniques from Peter McIlroy's "Optimistic
       
  1233      * Sorting and Information Theoretic Complexity", in Proceedings of the
       
  1234      * Fourth Annual ACM-SIAM Symposium on Discrete Algorithms, pp 467-474,
       
  1235      * January 1993.
       
  1236      *
       
  1237      * @param a the array to be sorted
       
  1238      * @throws ClassCastException if the array contains elements that are not
       
  1239      *         <i>mutually comparable</i> (for example, strings and integers)
       
  1240      * @throws IllegalArgumentException (optional) if the natural
       
  1241      *         ordering of the array elements is found to violate the
       
  1242      *         {@link Comparable} contract
       
  1243      */
       
  1244     public static void sort(Object[] a) {
       
  1245         if (LegacyMergeSort.userRequested)
       
  1246             legacyMergeSort(a);
       
  1247         else
       
  1248             ComparableTimSort.sort(a, 0, a.length, null, 0, 0);
       
  1249     }
       
  1250 
       
  1251     /** To be removed in a future release. */
       
  1252     private static void legacyMergeSort(Object[] a) {
       
  1253         Object[] aux = a.clone();
       
  1254         mergeSort(aux, a, 0, a.length, 0);
       
  1255     }
       
  1256 
       
  1257     /**
       
  1258      * Sorts the specified range of the specified array of objects into
       
  1259      * ascending order, according to the
       
  1260      * {@linkplain Comparable natural ordering} of its
       
  1261      * elements.  The range to be sorted extends from index
       
  1262      * {@code fromIndex}, inclusive, to index {@code toIndex}, exclusive.
       
  1263      * (If {@code fromIndex==toIndex}, the range to be sorted is empty.)  All
       
  1264      * elements in this range must implement the {@link Comparable}
       
  1265      * interface.  Furthermore, all elements in this range must be <i>mutually
       
  1266      * comparable</i> (that is, {@code e1.compareTo(e2)} must not throw a
       
  1267      * {@code ClassCastException} for any elements {@code e1} and
       
  1268      * {@code e2} in the array).
       
  1269      *
       
  1270      * <p>This sort is guaranteed to be <i>stable</i>:  equal elements will
       
  1271      * not be reordered as a result of the sort.
       
  1272      *
       
  1273      * <p>Implementation note: This implementation is a stable, adaptive,
       
  1274      * iterative mergesort that requires far fewer than n lg(n) comparisons
       
  1275      * when the input array is partially sorted, while offering the
       
  1276      * performance of a traditional mergesort when the input array is
       
  1277      * randomly ordered.  If the input array is nearly sorted, the
       
  1278      * implementation requires approximately n comparisons.  Temporary
       
  1279      * storage requirements vary from a small constant for nearly sorted
       
  1280      * input arrays to n/2 object references for randomly ordered input
       
  1281      * arrays.
       
  1282      *
       
  1283      * <p>The implementation takes equal advantage of ascending and
       
  1284      * descending order in its input array, and can take advantage of
       
  1285      * ascending and descending order in different parts of the same
       
  1286      * input array.  It is well-suited to merging two or more sorted arrays:
       
  1287      * simply concatenate the arrays and sort the resulting array.
       
  1288      *
       
  1289      * <p>The implementation was adapted from Tim Peters's list sort for Python
       
  1290      * (<a href="http://svn.python.org/projects/python/trunk/Objects/listsort.txt">
       
  1291      * TimSort</a>).  It uses techniques from Peter McIlroy's "Optimistic
       
  1292      * Sorting and Information Theoretic Complexity", in Proceedings of the
       
  1293      * Fourth Annual ACM-SIAM Symposium on Discrete Algorithms, pp 467-474,
       
  1294      * January 1993.
       
  1295      *
       
  1296      * @param a the array to be sorted
       
  1297      * @param fromIndex the index of the first element (inclusive) to be
       
  1298      *        sorted
       
  1299      * @param toIndex the index of the last element (exclusive) to be sorted
       
  1300      * @throws IllegalArgumentException if {@code fromIndex > toIndex} or
       
  1301      *         (optional) if the natural ordering of the array elements is
       
  1302      *         found to violate the {@link Comparable} contract
       
  1303      * @throws ArrayIndexOutOfBoundsException if {@code fromIndex < 0} or
       
  1304      *         {@code toIndex > a.length}
       
  1305      * @throws ClassCastException if the array contains elements that are
       
  1306      *         not <i>mutually comparable</i> (for example, strings and
       
  1307      *         integers).
       
  1308      */
       
  1309     public static void sort(Object[] a, int fromIndex, int toIndex) {
       
  1310         rangeCheck(a.length, fromIndex, toIndex);
       
  1311         if (LegacyMergeSort.userRequested)
       
  1312             legacyMergeSort(a, fromIndex, toIndex);
       
  1313         else
       
  1314             ComparableTimSort.sort(a, fromIndex, toIndex, null, 0, 0);
       
  1315     }
       
  1316 
       
  1317     /** To be removed in a future release. */
       
  1318     private static void legacyMergeSort(Object[] a,
       
  1319                                         int fromIndex, int toIndex) {
       
  1320         Object[] aux = copyOfRange(a, fromIndex, toIndex);
       
  1321         mergeSort(aux, a, fromIndex, toIndex, -fromIndex);
       
  1322     }
       
  1323 
       
  1324     /**
       
  1325      * Tuning parameter: list size at or below which insertion sort will be
       
  1326      * used in preference to mergesort.
       
  1327      * To be removed in a future release.
       
  1328      */
       
  1329     private static final int INSERTIONSORT_THRESHOLD = 7;
       
  1330 
       
  1331     /**
       
  1332      * Src is the source array that starts at index 0
       
  1333      * Dest is the (possibly larger) array destination with a possible offset
       
  1334      * low is the index in dest to start sorting
       
  1335      * high is the end index in dest to end sorting
       
  1336      * off is the offset to generate corresponding low, high in src
       
  1337      * To be removed in a future release.
       
  1338      */
       
  1339     @SuppressWarnings({"unchecked", "rawtypes"})
       
  1340     private static void mergeSort(Object[] src,
       
  1341                                   Object[] dest,
       
  1342                                   int low,
       
  1343                                   int high,
       
  1344                                   int off) {
       
  1345         int length = high - low;
       
  1346 
       
  1347         // Insertion sort on smallest arrays
       
  1348         if (length < INSERTIONSORT_THRESHOLD) {
       
  1349             for (int i=low; i<high; i++)
       
  1350                 for (int j=i; j>low &&
       
  1351                          ((Comparable) dest[j-1]).compareTo(dest[j])>0; j--)
       
  1352                     swap(dest, j, j-1);
       
  1353             return;
       
  1354         }
       
  1355 
       
  1356         // Recursively sort halves of dest into src
       
  1357         int destLow  = low;
       
  1358         int destHigh = high;
       
  1359         low  += off;
       
  1360         high += off;
       
  1361         int mid = (low + high) >>> 1;
       
  1362         mergeSort(dest, src, low, mid, -off);
       
  1363         mergeSort(dest, src, mid, high, -off);
       
  1364 
       
  1365         // If list is already sorted, just copy from src to dest.  This is an
       
  1366         // optimization that results in faster sorts for nearly ordered lists.
       
  1367         if (((Comparable)src[mid-1]).compareTo(src[mid]) <= 0) {
       
  1368             System.arraycopy(src, low, dest, destLow, length);
       
  1369             return;
       
  1370         }
       
  1371 
       
  1372         // Merge sorted halves (now in src) into dest
       
  1373         for(int i = destLow, p = low, q = mid; i < destHigh; i++) {
       
  1374             if (q >= high || p < mid && ((Comparable)src[p]).compareTo(src[q])<=0)
       
  1375                 dest[i] = src[p++];
       
  1376             else
       
  1377                 dest[i] = src[q++];
       
  1378         }
       
  1379     }
       
  1380 
       
  1381     /**
       
  1382      * Swaps x[a] with x[b].
       
  1383      */
       
  1384     private static void swap(Object[] x, int a, int b) {
       
  1385         Object t = x[a];
       
  1386         x[a] = x[b];
       
  1387         x[b] = t;
       
  1388     }
       
  1389 
       
  1390     /**
       
  1391      * Sorts the specified array of objects according to the order induced by
       
  1392      * the specified comparator.  All elements in the array must be
       
  1393      * <i>mutually comparable</i> by the specified comparator (that is,
       
  1394      * {@code c.compare(e1, e2)} must not throw a {@code ClassCastException}
       
  1395      * for any elements {@code e1} and {@code e2} in the array).
       
  1396      *
       
  1397      * <p>This sort is guaranteed to be <i>stable</i>:  equal elements will
       
  1398      * not be reordered as a result of the sort.
       
  1399      *
       
  1400      * <p>Implementation note: This implementation is a stable, adaptive,
       
  1401      * iterative mergesort that requires far fewer than n lg(n) comparisons
       
  1402      * when the input array is partially sorted, while offering the
       
  1403      * performance of a traditional mergesort when the input array is
       
  1404      * randomly ordered.  If the input array is nearly sorted, the
       
  1405      * implementation requires approximately n comparisons.  Temporary
       
  1406      * storage requirements vary from a small constant for nearly sorted
       
  1407      * input arrays to n/2 object references for randomly ordered input
       
  1408      * arrays.
       
  1409      *
       
  1410      * <p>The implementation takes equal advantage of ascending and
       
  1411      * descending order in its input array, and can take advantage of
       
  1412      * ascending and descending order in different parts of the same
       
  1413      * input array.  It is well-suited to merging two or more sorted arrays:
       
  1414      * simply concatenate the arrays and sort the resulting array.
       
  1415      *
       
  1416      * <p>The implementation was adapted from Tim Peters's list sort for Python
       
  1417      * (<a href="http://svn.python.org/projects/python/trunk/Objects/listsort.txt">
       
  1418      * TimSort</a>).  It uses techniques from Peter McIlroy's "Optimistic
       
  1419      * Sorting and Information Theoretic Complexity", in Proceedings of the
       
  1420      * Fourth Annual ACM-SIAM Symposium on Discrete Algorithms, pp 467-474,
       
  1421      * January 1993.
       
  1422      *
       
  1423      * @param <T> the class of the objects to be sorted
       
  1424      * @param a the array to be sorted
       
  1425      * @param c the comparator to determine the order of the array.  A
       
  1426      *        {@code null} value indicates that the elements'
       
  1427      *        {@linkplain Comparable natural ordering} should be used.
       
  1428      * @throws ClassCastException if the array contains elements that are
       
  1429      *         not <i>mutually comparable</i> using the specified comparator
       
  1430      * @throws IllegalArgumentException (optional) if the comparator is
       
  1431      *         found to violate the {@link Comparator} contract
       
  1432      */
       
  1433     public static <T> void sort(T[] a, Comparator<? super T> c) {
       
  1434         if (c == null) {
       
  1435             sort(a);
       
  1436         } else {
       
  1437             if (LegacyMergeSort.userRequested)
       
  1438                 legacyMergeSort(a, c);
       
  1439             else
       
  1440                 TimSort.sort(a, 0, a.length, c, null, 0, 0);
       
  1441         }
       
  1442     }
       
  1443 
       
  1444     /** To be removed in a future release. */
       
  1445     private static <T> void legacyMergeSort(T[] a, Comparator<? super T> c) {
       
  1446         T[] aux = a.clone();
       
  1447         if (c==null)
       
  1448             mergeSort(aux, a, 0, a.length, 0);
       
  1449         else
       
  1450             mergeSort(aux, a, 0, a.length, 0, c);
       
  1451     }
       
  1452 
       
  1453     /**
       
  1454      * Sorts the specified range of the specified array of objects according
       
  1455      * to the order induced by the specified comparator.  The range to be
       
  1456      * sorted extends from index {@code fromIndex}, inclusive, to index
       
  1457      * {@code toIndex}, exclusive.  (If {@code fromIndex==toIndex}, the
       
  1458      * range to be sorted is empty.)  All elements in the range must be
       
  1459      * <i>mutually comparable</i> by the specified comparator (that is,
       
  1460      * {@code c.compare(e1, e2)} must not throw a {@code ClassCastException}
       
  1461      * for any elements {@code e1} and {@code e2} in the range).
       
  1462      *
       
  1463      * <p>This sort is guaranteed to be <i>stable</i>:  equal elements will
       
  1464      * not be reordered as a result of the sort.
       
  1465      *
       
  1466      * <p>Implementation note: This implementation is a stable, adaptive,
       
  1467      * iterative mergesort that requires far fewer than n lg(n) comparisons
       
  1468      * when the input array is partially sorted, while offering the
       
  1469      * performance of a traditional mergesort when the input array is
       
  1470      * randomly ordered.  If the input array is nearly sorted, the
       
  1471      * implementation requires approximately n comparisons.  Temporary
       
  1472      * storage requirements vary from a small constant for nearly sorted
       
  1473      * input arrays to n/2 object references for randomly ordered input
       
  1474      * arrays.
       
  1475      *
       
  1476      * <p>The implementation takes equal advantage of ascending and
       
  1477      * descending order in its input array, and can take advantage of
       
  1478      * ascending and descending order in different parts of the same
       
  1479      * input array.  It is well-suited to merging two or more sorted arrays:
       
  1480      * simply concatenate the arrays and sort the resulting array.
       
  1481      *
       
  1482      * <p>The implementation was adapted from Tim Peters's list sort for Python
       
  1483      * (<a href="http://svn.python.org/projects/python/trunk/Objects/listsort.txt">
       
  1484      * TimSort</a>).  It uses techniques from Peter McIlroy's "Optimistic
       
  1485      * Sorting and Information Theoretic Complexity", in Proceedings of the
       
  1486      * Fourth Annual ACM-SIAM Symposium on Discrete Algorithms, pp 467-474,
       
  1487      * January 1993.
       
  1488      *
       
  1489      * @param <T> the class of the objects to be sorted
       
  1490      * @param a the array to be sorted
       
  1491      * @param fromIndex the index of the first element (inclusive) to be
       
  1492      *        sorted
       
  1493      * @param toIndex the index of the last element (exclusive) to be sorted
       
  1494      * @param c the comparator to determine the order of the array.  A
       
  1495      *        {@code null} value indicates that the elements'
       
  1496      *        {@linkplain Comparable natural ordering} should be used.
       
  1497      * @throws ClassCastException if the array contains elements that are not
       
  1498      *         <i>mutually comparable</i> using the specified comparator.
       
  1499      * @throws IllegalArgumentException if {@code fromIndex > toIndex} or
       
  1500      *         (optional) if the comparator is found to violate the
       
  1501      *         {@link Comparator} contract
       
  1502      * @throws ArrayIndexOutOfBoundsException if {@code fromIndex < 0} or
       
  1503      *         {@code toIndex > a.length}
       
  1504      */
       
  1505     public static <T> void sort(T[] a, int fromIndex, int toIndex,
       
  1506                                 Comparator<? super T> c) {
       
  1507         if (c == null) {
       
  1508             sort(a, fromIndex, toIndex);
       
  1509         } else {
       
  1510             rangeCheck(a.length, fromIndex, toIndex);
       
  1511             if (LegacyMergeSort.userRequested)
       
  1512                 legacyMergeSort(a, fromIndex, toIndex, c);
       
  1513             else
       
  1514                 TimSort.sort(a, fromIndex, toIndex, c, null, 0, 0);
       
  1515         }
       
  1516     }
       
  1517 
       
  1518     /** To be removed in a future release. */
       
  1519     private static <T> void legacyMergeSort(T[] a, int fromIndex, int toIndex,
       
  1520                                             Comparator<? super T> c) {
       
  1521         T[] aux = copyOfRange(a, fromIndex, toIndex);
       
  1522         if (c==null)
       
  1523             mergeSort(aux, a, fromIndex, toIndex, -fromIndex);
       
  1524         else
       
  1525             mergeSort(aux, a, fromIndex, toIndex, -fromIndex, c);
       
  1526     }
       
  1527 
       
  1528     /**
       
  1529      * Src is the source array that starts at index 0
       
  1530      * Dest is the (possibly larger) array destination with a possible offset
       
  1531      * low is the index in dest to start sorting
       
  1532      * high is the end index in dest to end sorting
       
  1533      * off is the offset into src corresponding to low in dest
       
  1534      * To be removed in a future release.
       
  1535      */
       
  1536     @SuppressWarnings({"rawtypes", "unchecked"})
       
  1537     private static void mergeSort(Object[] src,
       
  1538                                   Object[] dest,
       
  1539                                   int low, int high, int off,
       
  1540                                   Comparator c) {
       
  1541         int length = high - low;
       
  1542 
       
  1543         // Insertion sort on smallest arrays
       
  1544         if (length < INSERTIONSORT_THRESHOLD) {
       
  1545             for (int i=low; i<high; i++)
       
  1546                 for (int j=i; j>low && c.compare(dest[j-1], dest[j])>0; j--)
       
  1547                     swap(dest, j, j-1);
       
  1548             return;
       
  1549         }
       
  1550 
       
  1551         // Recursively sort halves of dest into src
       
  1552         int destLow  = low;
       
  1553         int destHigh = high;
       
  1554         low  += off;
       
  1555         high += off;
       
  1556         int mid = (low + high) >>> 1;
       
  1557         mergeSort(dest, src, low, mid, -off, c);
       
  1558         mergeSort(dest, src, mid, high, -off, c);
       
  1559 
       
  1560         // If list is already sorted, just copy from src to dest.  This is an
       
  1561         // optimization that results in faster sorts for nearly ordered lists.
       
  1562         if (c.compare(src[mid-1], src[mid]) <= 0) {
       
  1563            System.arraycopy(src, low, dest, destLow, length);
       
  1564            return;
       
  1565         }
       
  1566 
       
  1567         // Merge sorted halves (now in src) into dest
       
  1568         for(int i = destLow, p = low, q = mid; i < destHigh; i++) {
       
  1569             if (q >= high || p < mid && c.compare(src[p], src[q]) <= 0)
       
  1570                 dest[i] = src[p++];
       
  1571             else
       
  1572                 dest[i] = src[q++];
       
  1573         }
       
  1574     }
       
  1575 
       
  1576     // Parallel prefix
       
  1577 
       
  1578     /**
       
  1579      * Cumulates, in parallel, each element of the given array in place,
       
  1580      * using the supplied function. For example if the array initially
       
  1581      * holds {@code [2, 1, 0, 3]} and the operation performs addition,
       
  1582      * then upon return the array holds {@code [2, 3, 3, 6]}.
       
  1583      * Parallel prefix computation is usually more efficient than
       
  1584      * sequential loops for large arrays.
       
  1585      *
       
  1586      * @param <T> the class of the objects in the array
       
  1587      * @param array the array, which is modified in-place by this method
       
  1588      * @param op a side-effect-free, associative function to perform the
       
  1589      * cumulation
       
  1590      * @throws NullPointerException if the specified array or function is null
       
  1591      * @since 1.8
       
  1592      */
       
  1593     public static <T> void parallelPrefix(T[] array, BinaryOperator<T> op) {
       
  1594         Objects.requireNonNull(op);
       
  1595         if (array.length > 0)
       
  1596             new ArrayPrefixHelpers.CumulateTask<>
       
  1597                     (null, op, array, 0, array.length).invoke();
       
  1598     }
       
  1599 
       
  1600     /**
       
  1601      * Performs {@link #parallelPrefix(Object[], BinaryOperator)}
       
  1602      * for the given subrange of the array.
       
  1603      *
       
  1604      * @param <T> the class of the objects in the array
       
  1605      * @param array the array
       
  1606      * @param fromIndex the index of the first element, inclusive
       
  1607      * @param toIndex the index of the last element, exclusive
       
  1608      * @param op a side-effect-free, associative function to perform the
       
  1609      * cumulation
       
  1610      * @throws IllegalArgumentException if {@code fromIndex > toIndex}
       
  1611      * @throws ArrayIndexOutOfBoundsException
       
  1612      *     if {@code fromIndex < 0} or {@code toIndex > array.length}
       
  1613      * @throws NullPointerException if the specified array or function is null
       
  1614      * @since 1.8
       
  1615      */
       
  1616     public static <T> void parallelPrefix(T[] array, int fromIndex,
       
  1617                                           int toIndex, BinaryOperator<T> op) {
       
  1618         Objects.requireNonNull(op);
       
  1619         rangeCheck(array.length, fromIndex, toIndex);
       
  1620         if (fromIndex < toIndex)
       
  1621             new ArrayPrefixHelpers.CumulateTask<>
       
  1622                     (null, op, array, fromIndex, toIndex).invoke();
       
  1623     }
       
  1624 
       
  1625     /**
       
  1626      * Cumulates, in parallel, each element of the given array in place,
       
  1627      * using the supplied function. For example if the array initially
       
  1628      * holds {@code [2, 1, 0, 3]} and the operation performs addition,
       
  1629      * then upon return the array holds {@code [2, 3, 3, 6]}.
       
  1630      * Parallel prefix computation is usually more efficient than
       
  1631      * sequential loops for large arrays.
       
  1632      *
       
  1633      * @param array the array, which is modified in-place by this method
       
  1634      * @param op a side-effect-free, associative function to perform the
       
  1635      * cumulation
       
  1636      * @throws NullPointerException if the specified array or function is null
       
  1637      * @since 1.8
       
  1638      */
       
  1639     public static void parallelPrefix(long[] array, LongBinaryOperator op) {
       
  1640         Objects.requireNonNull(op);
       
  1641         if (array.length > 0)
       
  1642             new ArrayPrefixHelpers.LongCumulateTask
       
  1643                     (null, op, array, 0, array.length).invoke();
       
  1644     }
       
  1645 
       
  1646     /**
       
  1647      * Performs {@link #parallelPrefix(long[], LongBinaryOperator)}
       
  1648      * for the given subrange of the array.
       
  1649      *
       
  1650      * @param array the array
       
  1651      * @param fromIndex the index of the first element, inclusive
       
  1652      * @param toIndex the index of the last element, exclusive
       
  1653      * @param op a side-effect-free, associative function to perform the
       
  1654      * cumulation
       
  1655      * @throws IllegalArgumentException if {@code fromIndex > toIndex}
       
  1656      * @throws ArrayIndexOutOfBoundsException
       
  1657      *     if {@code fromIndex < 0} or {@code toIndex > array.length}
       
  1658      * @throws NullPointerException if the specified array or function is null
       
  1659      * @since 1.8
       
  1660      */
       
  1661     public static void parallelPrefix(long[] array, int fromIndex,
       
  1662                                       int toIndex, LongBinaryOperator op) {
       
  1663         Objects.requireNonNull(op);
       
  1664         rangeCheck(array.length, fromIndex, toIndex);
       
  1665         if (fromIndex < toIndex)
       
  1666             new ArrayPrefixHelpers.LongCumulateTask
       
  1667                     (null, op, array, fromIndex, toIndex).invoke();
       
  1668     }
       
  1669 
       
  1670     /**
       
  1671      * Cumulates, in parallel, each element of the given array in place,
       
  1672      * using the supplied function. For example if the array initially
       
  1673      * holds {@code [2.0, 1.0, 0.0, 3.0]} and the operation performs addition,
       
  1674      * then upon return the array holds {@code [2.0, 3.0, 3.0, 6.0]}.
       
  1675      * Parallel prefix computation is usually more efficient than
       
  1676      * sequential loops for large arrays.
       
  1677      *
       
  1678      * <p> Because floating-point operations may not be strictly associative,
       
  1679      * the returned result may not be identical to the value that would be
       
  1680      * obtained if the operation was performed sequentially.
       
  1681      *
       
  1682      * @param array the array, which is modified in-place by this method
       
  1683      * @param op a side-effect-free function to perform the cumulation
       
  1684      * @throws NullPointerException if the specified array or function is null
       
  1685      * @since 1.8
       
  1686      */
       
  1687     public static void parallelPrefix(double[] array, DoubleBinaryOperator op) {
       
  1688         Objects.requireNonNull(op);
       
  1689         if (array.length > 0)
       
  1690             new ArrayPrefixHelpers.DoubleCumulateTask
       
  1691                     (null, op, array, 0, array.length).invoke();
       
  1692     }
       
  1693 
       
  1694     /**
       
  1695      * Performs {@link #parallelPrefix(double[], DoubleBinaryOperator)}
       
  1696      * for the given subrange of the array.
       
  1697      *
       
  1698      * @param array the array
       
  1699      * @param fromIndex the index of the first element, inclusive
       
  1700      * @param toIndex the index of the last element, exclusive
       
  1701      * @param op a side-effect-free, associative function to perform the
       
  1702      * cumulation
       
  1703      * @throws IllegalArgumentException if {@code fromIndex > toIndex}
       
  1704      * @throws ArrayIndexOutOfBoundsException
       
  1705      *     if {@code fromIndex < 0} or {@code toIndex > array.length}
       
  1706      * @throws NullPointerException if the specified array or function is null
       
  1707      * @since 1.8
       
  1708      */
       
  1709     public static void parallelPrefix(double[] array, int fromIndex,
       
  1710                                       int toIndex, DoubleBinaryOperator op) {
       
  1711         Objects.requireNonNull(op);
       
  1712         rangeCheck(array.length, fromIndex, toIndex);
       
  1713         if (fromIndex < toIndex)
       
  1714             new ArrayPrefixHelpers.DoubleCumulateTask
       
  1715                     (null, op, array, fromIndex, toIndex).invoke();
       
  1716     }
       
  1717 
       
  1718     /**
       
  1719      * Cumulates, in parallel, each element of the given array in place,
       
  1720      * using the supplied function. For example if the array initially
       
  1721      * holds {@code [2, 1, 0, 3]} and the operation performs addition,
       
  1722      * then upon return the array holds {@code [2, 3, 3, 6]}.
       
  1723      * Parallel prefix computation is usually more efficient than
       
  1724      * sequential loops for large arrays.
       
  1725      *
       
  1726      * @param array the array, which is modified in-place by this method
       
  1727      * @param op a side-effect-free, associative function to perform the
       
  1728      * cumulation
       
  1729      * @throws NullPointerException if the specified array or function is null
       
  1730      * @since 1.8
       
  1731      */
       
  1732     public static void parallelPrefix(int[] array, IntBinaryOperator op) {
       
  1733         Objects.requireNonNull(op);
       
  1734         if (array.length > 0)
       
  1735             new ArrayPrefixHelpers.IntCumulateTask
       
  1736                     (null, op, array, 0, array.length).invoke();
       
  1737     }
       
  1738 
       
  1739     /**
       
  1740      * Performs {@link #parallelPrefix(int[], IntBinaryOperator)}
       
  1741      * for the given subrange of the array.
       
  1742      *
       
  1743      * @param array the array
       
  1744      * @param fromIndex the index of the first element, inclusive
       
  1745      * @param toIndex the index of the last element, exclusive
       
  1746      * @param op a side-effect-free, associative function to perform the
       
  1747      * cumulation
       
  1748      * @throws IllegalArgumentException if {@code fromIndex > toIndex}
       
  1749      * @throws ArrayIndexOutOfBoundsException
       
  1750      *     if {@code fromIndex < 0} or {@code toIndex > array.length}
       
  1751      * @throws NullPointerException if the specified array or function is null
       
  1752      * @since 1.8
       
  1753      */
       
  1754     public static void parallelPrefix(int[] array, int fromIndex,
       
  1755                                       int toIndex, IntBinaryOperator op) {
       
  1756         Objects.requireNonNull(op);
       
  1757         rangeCheck(array.length, fromIndex, toIndex);
       
  1758         if (fromIndex < toIndex)
       
  1759             new ArrayPrefixHelpers.IntCumulateTask
       
  1760                     (null, op, array, fromIndex, toIndex).invoke();
       
  1761     }
       
  1762 
       
  1763     // Searching
       
  1764 
       
  1765     /**
       
  1766      * Searches the specified array of longs for the specified value using the
       
  1767      * binary search algorithm.  The array must be sorted (as
       
  1768      * by the {@link #sort(long[])} method) prior to making this call.  If it
       
  1769      * is not sorted, the results are undefined.  If the array contains
       
  1770      * multiple elements with the specified value, there is no guarantee which
       
  1771      * one will be found.
       
  1772      *
       
  1773      * @param a the array to be searched
       
  1774      * @param key the value to be searched for
       
  1775      * @return index of the search key, if it is contained in the array;
       
  1776      *         otherwise, <code>(-(<i>insertion point</i>) - 1)</code>.  The
       
  1777      *         <i>insertion point</i> is defined as the point at which the
       
  1778      *         key would be inserted into the array: the index of the first
       
  1779      *         element greater than the key, or {@code a.length} if all
       
  1780      *         elements in the array are less than the specified key.  Note
       
  1781      *         that this guarantees that the return value will be &gt;= 0 if
       
  1782      *         and only if the key is found.
       
  1783      */
       
  1784     public static int binarySearch(long[] a, long key) {
       
  1785         return binarySearch0(a, 0, a.length, key);
       
  1786     }
       
  1787 
       
  1788     /**
       
  1789      * Searches a range of
       
  1790      * the specified array of longs for the specified value using the
       
  1791      * binary search algorithm.
       
  1792      * The range must be sorted (as
       
  1793      * by the {@link #sort(long[], int, int)} method)
       
  1794      * prior to making this call.  If it
       
  1795      * is not sorted, the results are undefined.  If the range contains
       
  1796      * multiple elements with the specified value, there is no guarantee which
       
  1797      * one will be found.
       
  1798      *
       
  1799      * @param a the array to be searched
       
  1800      * @param fromIndex the index of the first element (inclusive) to be
       
  1801      *          searched
       
  1802      * @param toIndex the index of the last element (exclusive) to be searched
       
  1803      * @param key the value to be searched for
       
  1804      * @return index of the search key, if it is contained in the array
       
  1805      *         within the specified range;
       
  1806      *         otherwise, <code>(-(<i>insertion point</i>) - 1)</code>.  The
       
  1807      *         <i>insertion point</i> is defined as the point at which the
       
  1808      *         key would be inserted into the array: the index of the first
       
  1809      *         element in the range greater than the key,
       
  1810      *         or {@code toIndex} if all
       
  1811      *         elements in the range are less than the specified key.  Note
       
  1812      *         that this guarantees that the return value will be &gt;= 0 if
       
  1813      *         and only if the key is found.
       
  1814      * @throws IllegalArgumentException
       
  1815      *         if {@code fromIndex > toIndex}
       
  1816      * @throws ArrayIndexOutOfBoundsException
       
  1817      *         if {@code fromIndex < 0 or toIndex > a.length}
       
  1818      * @since 1.6
       
  1819      */
       
  1820     public static int binarySearch(long[] a, int fromIndex, int toIndex,
       
  1821                                    long key) {
       
  1822         rangeCheck(a.length, fromIndex, toIndex);
       
  1823         return binarySearch0(a, fromIndex, toIndex, key);
       
  1824     }
       
  1825 
       
  1826     // Like public version, but without range checks.
       
  1827     private static int binarySearch0(long[] a, int fromIndex, int toIndex,
       
  1828                                      long key) {
       
  1829         int low = fromIndex;
       
  1830         int high = toIndex - 1;
       
  1831 
       
  1832         while (low <= high) {
       
  1833             int mid = (low + high) >>> 1;
       
  1834             long midVal = a[mid];
       
  1835 
       
  1836             if (midVal < key)
       
  1837                 low = mid + 1;
       
  1838             else if (midVal > key)
       
  1839                 high = mid - 1;
       
  1840             else
       
  1841                 return mid; // key found
       
  1842         }
       
  1843         return -(low + 1);  // key not found.
       
  1844     }
       
  1845 
       
  1846     /**
       
  1847      * Searches the specified array of ints for the specified value using the
       
  1848      * binary search algorithm.  The array must be sorted (as
       
  1849      * by the {@link #sort(int[])} method) prior to making this call.  If it
       
  1850      * is not sorted, the results are undefined.  If the array contains
       
  1851      * multiple elements with the specified value, there is no guarantee which
       
  1852      * one will be found.
       
  1853      *
       
  1854      * @param a the array to be searched
       
  1855      * @param key the value to be searched for
       
  1856      * @return index of the search key, if it is contained in the array;
       
  1857      *         otherwise, <code>(-(<i>insertion point</i>) - 1)</code>.  The
       
  1858      *         <i>insertion point</i> is defined as the point at which the
       
  1859      *         key would be inserted into the array: the index of the first
       
  1860      *         element greater than the key, or {@code a.length} if all
       
  1861      *         elements in the array are less than the specified key.  Note
       
  1862      *         that this guarantees that the return value will be &gt;= 0 if
       
  1863      *         and only if the key is found.
       
  1864      */
       
  1865     public static int binarySearch(int[] a, int key) {
       
  1866         return binarySearch0(a, 0, a.length, key);
       
  1867     }
       
  1868 
       
  1869     /**
       
  1870      * Searches a range of
       
  1871      * the specified array of ints for the specified value using the
       
  1872      * binary search algorithm.
       
  1873      * The range must be sorted (as
       
  1874      * by the {@link #sort(int[], int, int)} method)
       
  1875      * prior to making this call.  If it
       
  1876      * is not sorted, the results are undefined.  If the range contains
       
  1877      * multiple elements with the specified value, there is no guarantee which
       
  1878      * one will be found.
       
  1879      *
       
  1880      * @param a the array to be searched
       
  1881      * @param fromIndex the index of the first element (inclusive) to be
       
  1882      *          searched
       
  1883      * @param toIndex the index of the last element (exclusive) to be searched
       
  1884      * @param key the value to be searched for
       
  1885      * @return index of the search key, if it is contained in the array
       
  1886      *         within the specified range;
       
  1887      *         otherwise, <code>(-(<i>insertion point</i>) - 1)</code>.  The
       
  1888      *         <i>insertion point</i> is defined as the point at which the
       
  1889      *         key would be inserted into the array: the index of the first
       
  1890      *         element in the range greater than the key,
       
  1891      *         or {@code toIndex} if all
       
  1892      *         elements in the range are less than the specified key.  Note
       
  1893      *         that this guarantees that the return value will be &gt;= 0 if
       
  1894      *         and only if the key is found.
       
  1895      * @throws IllegalArgumentException
       
  1896      *         if {@code fromIndex > toIndex}
       
  1897      * @throws ArrayIndexOutOfBoundsException
       
  1898      *         if {@code fromIndex < 0 or toIndex > a.length}
       
  1899      * @since 1.6
       
  1900      */
       
  1901     public static int binarySearch(int[] a, int fromIndex, int toIndex,
       
  1902                                    int key) {
       
  1903         rangeCheck(a.length, fromIndex, toIndex);
       
  1904         return binarySearch0(a, fromIndex, toIndex, key);
       
  1905     }
       
  1906 
       
  1907     // Like public version, but without range checks.
       
  1908     private static int binarySearch0(int[] a, int fromIndex, int toIndex,
       
  1909                                      int key) {
       
  1910         int low = fromIndex;
       
  1911         int high = toIndex - 1;
       
  1912 
       
  1913         while (low <= high) {
       
  1914             int mid = (low + high) >>> 1;
       
  1915             int midVal = a[mid];
       
  1916 
       
  1917             if (midVal < key)
       
  1918                 low = mid + 1;
       
  1919             else if (midVal > key)
       
  1920                 high = mid - 1;
       
  1921             else
       
  1922                 return mid; // key found
       
  1923         }
       
  1924         return -(low + 1);  // key not found.
       
  1925     }
       
  1926 
       
  1927     /**
       
  1928      * Searches the specified array of shorts for the specified value using
       
  1929      * the binary search algorithm.  The array must be sorted
       
  1930      * (as by the {@link #sort(short[])} method) prior to making this call.  If
       
  1931      * it is not sorted, the results are undefined.  If the array contains
       
  1932      * multiple elements with the specified value, there is no guarantee which
       
  1933      * one will be found.
       
  1934      *
       
  1935      * @param a the array to be searched
       
  1936      * @param key the value to be searched for
       
  1937      * @return index of the search key, if it is contained in the array;
       
  1938      *         otherwise, <code>(-(<i>insertion point</i>) - 1)</code>.  The
       
  1939      *         <i>insertion point</i> is defined as the point at which the
       
  1940      *         key would be inserted into the array: the index of the first
       
  1941      *         element greater than the key, or {@code a.length} if all
       
  1942      *         elements in the array are less than the specified key.  Note
       
  1943      *         that this guarantees that the return value will be &gt;= 0 if
       
  1944      *         and only if the key is found.
       
  1945      */
       
  1946     public static int binarySearch(short[] a, short key) {
       
  1947         return binarySearch0(a, 0, a.length, key);
       
  1948     }
       
  1949 
       
  1950     /**
       
  1951      * Searches a range of
       
  1952      * the specified array of shorts for the specified value using
       
  1953      * the binary search algorithm.
       
  1954      * The range must be sorted
       
  1955      * (as by the {@link #sort(short[], int, int)} method)
       
  1956      * prior to making this call.  If
       
  1957      * it is not sorted, the results are undefined.  If the range contains
       
  1958      * multiple elements with the specified value, there is no guarantee which
       
  1959      * one will be found.
       
  1960      *
       
  1961      * @param a the array to be searched
       
  1962      * @param fromIndex the index of the first element (inclusive) to be
       
  1963      *          searched
       
  1964      * @param toIndex the index of the last element (exclusive) to be searched
       
  1965      * @param key the value to be searched for
       
  1966      * @return index of the search key, if it is contained in the array
       
  1967      *         within the specified range;
       
  1968      *         otherwise, <code>(-(<i>insertion point</i>) - 1)</code>.  The
       
  1969      *         <i>insertion point</i> is defined as the point at which the
       
  1970      *         key would be inserted into the array: the index of the first
       
  1971      *         element in the range greater than the key,
       
  1972      *         or {@code toIndex} if all
       
  1973      *         elements in the range are less than the specified key.  Note
       
  1974      *         that this guarantees that the return value will be &gt;= 0 if
       
  1975      *         and only if the key is found.
       
  1976      * @throws IllegalArgumentException
       
  1977      *         if {@code fromIndex > toIndex}
       
  1978      * @throws ArrayIndexOutOfBoundsException
       
  1979      *         if {@code fromIndex < 0 or toIndex > a.length}
       
  1980      * @since 1.6
       
  1981      */
       
  1982     public static int binarySearch(short[] a, int fromIndex, int toIndex,
       
  1983                                    short key) {
       
  1984         rangeCheck(a.length, fromIndex, toIndex);
       
  1985         return binarySearch0(a, fromIndex, toIndex, key);
       
  1986     }
       
  1987 
       
  1988     // Like public version, but without range checks.
       
  1989     private static int binarySearch0(short[] a, int fromIndex, int toIndex,
       
  1990                                      short key) {
       
  1991         int low = fromIndex;
       
  1992         int high = toIndex - 1;
       
  1993 
       
  1994         while (low <= high) {
       
  1995             int mid = (low + high) >>> 1;
       
  1996             short midVal = a[mid];
       
  1997 
       
  1998             if (midVal < key)
       
  1999                 low = mid + 1;
       
  2000             else if (midVal > key)
       
  2001                 high = mid - 1;
       
  2002             else
       
  2003                 return mid; // key found
       
  2004         }
       
  2005         return -(low + 1);  // key not found.
       
  2006     }
       
  2007 
       
  2008     /**
       
  2009      * Searches the specified array of chars for the specified value using the
       
  2010      * binary search algorithm.  The array must be sorted (as
       
  2011      * by the {@link #sort(char[])} method) prior to making this call.  If it
       
  2012      * is not sorted, the results are undefined.  If the array contains
       
  2013      * multiple elements with the specified value, there is no guarantee which
       
  2014      * one will be found.
       
  2015      *
       
  2016      * @param a the array to be searched
       
  2017      * @param key the value to be searched for
       
  2018      * @return index of the search key, if it is contained in the array;
       
  2019      *         otherwise, <code>(-(<i>insertion point</i>) - 1)</code>.  The
       
  2020      *         <i>insertion point</i> is defined as the point at which the
       
  2021      *         key would be inserted into the array: the index of the first
       
  2022      *         element greater than the key, or {@code a.length} if all
       
  2023      *         elements in the array are less than the specified key.  Note
       
  2024      *         that this guarantees that the return value will be &gt;= 0 if
       
  2025      *         and only if the key is found.
       
  2026      */
       
  2027     public static int binarySearch(char[] a, char key) {
       
  2028         return binarySearch0(a, 0, a.length, key);
       
  2029     }
       
  2030 
       
  2031     /**
       
  2032      * Searches a range of
       
  2033      * the specified array of chars for the specified value using the
       
  2034      * binary search algorithm.
       
  2035      * The range must be sorted (as
       
  2036      * by the {@link #sort(char[], int, int)} method)
       
  2037      * prior to making this call.  If it
       
  2038      * is not sorted, the results are undefined.  If the range contains
       
  2039      * multiple elements with the specified value, there is no guarantee which
       
  2040      * one will be found.
       
  2041      *
       
  2042      * @param a the array to be searched
       
  2043      * @param fromIndex the index of the first element (inclusive) to be
       
  2044      *          searched
       
  2045      * @param toIndex the index of the last element (exclusive) to be searched
       
  2046      * @param key the value to be searched for
       
  2047      * @return index of the search key, if it is contained in the array
       
  2048      *         within the specified range;
       
  2049      *         otherwise, <code>(-(<i>insertion point</i>) - 1)</code>.  The
       
  2050      *         <i>insertion point</i> is defined as the point at which the
       
  2051      *         key would be inserted into the array: the index of the first
       
  2052      *         element in the range greater than the key,
       
  2053      *         or {@code toIndex} if all
       
  2054      *         elements in the range are less than the specified key.  Note
       
  2055      *         that this guarantees that the return value will be &gt;= 0 if
       
  2056      *         and only if the key is found.
       
  2057      * @throws IllegalArgumentException
       
  2058      *         if {@code fromIndex > toIndex}
       
  2059      * @throws ArrayIndexOutOfBoundsException
       
  2060      *         if {@code fromIndex < 0 or toIndex > a.length}
       
  2061      * @since 1.6
       
  2062      */
       
  2063     public static int binarySearch(char[] a, int fromIndex, int toIndex,
       
  2064                                    char key) {
       
  2065         rangeCheck(a.length, fromIndex, toIndex);
       
  2066         return binarySearch0(a, fromIndex, toIndex, key);
       
  2067     }
       
  2068 
       
  2069     // Like public version, but without range checks.
       
  2070     private static int binarySearch0(char[] a, int fromIndex, int toIndex,
       
  2071                                      char key) {
       
  2072         int low = fromIndex;
       
  2073         int high = toIndex - 1;
       
  2074 
       
  2075         while (low <= high) {
       
  2076             int mid = (low + high) >>> 1;
       
  2077             char midVal = a[mid];
       
  2078 
       
  2079             if (midVal < key)
       
  2080                 low = mid + 1;
       
  2081             else if (midVal > key)
       
  2082                 high = mid - 1;
       
  2083             else
       
  2084                 return mid; // key found
       
  2085         }
       
  2086         return -(low + 1);  // key not found.
       
  2087     }
       
  2088 
       
  2089     /**
       
  2090      * Searches the specified array of bytes for the specified value using the
       
  2091      * binary search algorithm.  The array must be sorted (as
       
  2092      * by the {@link #sort(byte[])} method) prior to making this call.  If it
       
  2093      * is not sorted, the results are undefined.  If the array contains
       
  2094      * multiple elements with the specified value, there is no guarantee which
       
  2095      * one will be found.
       
  2096      *
       
  2097      * @param a the array to be searched
       
  2098      * @param key the value to be searched for
       
  2099      * @return index of the search key, if it is contained in the array;
       
  2100      *         otherwise, <code>(-(<i>insertion point</i>) - 1)</code>.  The
       
  2101      *         <i>insertion point</i> is defined as the point at which the
       
  2102      *         key would be inserted into the array: the index of the first
       
  2103      *         element greater than the key, or {@code a.length} if all
       
  2104      *         elements in the array are less than the specified key.  Note
       
  2105      *         that this guarantees that the return value will be &gt;= 0 if
       
  2106      *         and only if the key is found.
       
  2107      */
       
  2108     public static int binarySearch(byte[] a, byte key) {
       
  2109         return binarySearch0(a, 0, a.length, key);
       
  2110     }
       
  2111 
       
  2112     /**
       
  2113      * Searches a range of
       
  2114      * the specified array of bytes for the specified value using the
       
  2115      * binary search algorithm.
       
  2116      * The range must be sorted (as
       
  2117      * by the {@link #sort(byte[], int, int)} method)
       
  2118      * prior to making this call.  If it
       
  2119      * is not sorted, the results are undefined.  If the range contains
       
  2120      * multiple elements with the specified value, there is no guarantee which
       
  2121      * one will be found.
       
  2122      *
       
  2123      * @param a the array to be searched
       
  2124      * @param fromIndex the index of the first element (inclusive) to be
       
  2125      *          searched
       
  2126      * @param toIndex the index of the last element (exclusive) to be searched
       
  2127      * @param key the value to be searched for
       
  2128      * @return index of the search key, if it is contained in the array
       
  2129      *         within the specified range;
       
  2130      *         otherwise, <code>(-(<i>insertion point</i>) - 1)</code>.  The
       
  2131      *         <i>insertion point</i> is defined as the point at which the
       
  2132      *         key would be inserted into the array: the index of the first
       
  2133      *         element in the range greater than the key,
       
  2134      *         or {@code toIndex} if all
       
  2135      *         elements in the range are less than the specified key.  Note
       
  2136      *         that this guarantees that the return value will be &gt;= 0 if
       
  2137      *         and only if the key is found.
       
  2138      * @throws IllegalArgumentException
       
  2139      *         if {@code fromIndex > toIndex}
       
  2140      * @throws ArrayIndexOutOfBoundsException
       
  2141      *         if {@code fromIndex < 0 or toIndex > a.length}
       
  2142      * @since 1.6
       
  2143      */
       
  2144     public static int binarySearch(byte[] a, int fromIndex, int toIndex,
       
  2145                                    byte key) {
       
  2146         rangeCheck(a.length, fromIndex, toIndex);
       
  2147         return binarySearch0(a, fromIndex, toIndex, key);
       
  2148     }
       
  2149 
       
  2150     // Like public version, but without range checks.
       
  2151     private static int binarySearch0(byte[] a, int fromIndex, int toIndex,
       
  2152                                      byte key) {
       
  2153         int low = fromIndex;
       
  2154         int high = toIndex - 1;
       
  2155 
       
  2156         while (low <= high) {
       
  2157             int mid = (low + high) >>> 1;
       
  2158             byte midVal = a[mid];
       
  2159 
       
  2160             if (midVal < key)
       
  2161                 low = mid + 1;
       
  2162             else if (midVal > key)
       
  2163                 high = mid - 1;
       
  2164             else
       
  2165                 return mid; // key found
       
  2166         }
       
  2167         return -(low + 1);  // key not found.
       
  2168     }
       
  2169 
       
  2170     /**
       
  2171      * Searches the specified array of doubles for the specified value using
       
  2172      * the binary search algorithm.  The array must be sorted
       
  2173      * (as by the {@link #sort(double[])} method) prior to making this call.
       
  2174      * If it is not sorted, the results are undefined.  If the array contains
       
  2175      * multiple elements with the specified value, there is no guarantee which
       
  2176      * one will be found.  This method considers all NaN values to be
       
  2177      * equivalent and equal.
       
  2178      *
       
  2179      * @param a the array to be searched
       
  2180      * @param key the value to be searched for
       
  2181      * @return index of the search key, if it is contained in the array;
       
  2182      *         otherwise, <code>(-(<i>insertion point</i>) - 1)</code>.  The
       
  2183      *         <i>insertion point</i> is defined as the point at which the
       
  2184      *         key would be inserted into the array: the index of the first
       
  2185      *         element greater than the key, or {@code a.length} if all
       
  2186      *         elements in the array are less than the specified key.  Note
       
  2187      *         that this guarantees that the return value will be &gt;= 0 if
       
  2188      *         and only if the key is found.
       
  2189      */
       
  2190     public static int binarySearch(double[] a, double key) {
       
  2191         return binarySearch0(a, 0, a.length, key);
       
  2192     }
       
  2193 
       
  2194     /**
       
  2195      * Searches a range of
       
  2196      * the specified array of doubles for the specified value using
       
  2197      * the binary search algorithm.
       
  2198      * The range must be sorted
       
  2199      * (as by the {@link #sort(double[], int, int)} method)
       
  2200      * prior to making this call.
       
  2201      * If it is not sorted, the results are undefined.  If the range contains
       
  2202      * multiple elements with the specified value, there is no guarantee which
       
  2203      * one will be found.  This method considers all NaN values to be
       
  2204      * equivalent and equal.
       
  2205      *
       
  2206      * @param a the array to be searched
       
  2207      * @param fromIndex the index of the first element (inclusive) to be
       
  2208      *          searched
       
  2209      * @param toIndex the index of the last element (exclusive) to be searched
       
  2210      * @param key the value to be searched for
       
  2211      * @return index of the search key, if it is contained in the array
       
  2212      *         within the specified range;
       
  2213      *         otherwise, <code>(-(<i>insertion point</i>) - 1)</code>.  The
       
  2214      *         <i>insertion point</i> is defined as the point at which the
       
  2215      *         key would be inserted into the array: the index of the first
       
  2216      *         element in the range greater than the key,
       
  2217      *         or {@code toIndex} if all
       
  2218      *         elements in the range are less than the specified key.  Note
       
  2219      *         that this guarantees that the return value will be &gt;= 0 if
       
  2220      *         and only if the key is found.
       
  2221      * @throws IllegalArgumentException
       
  2222      *         if {@code fromIndex > toIndex}
       
  2223      * @throws ArrayIndexOutOfBoundsException
       
  2224      *         if {@code fromIndex < 0 or toIndex > a.length}
       
  2225      * @since 1.6
       
  2226      */
       
  2227     public static int binarySearch(double[] a, int fromIndex, int toIndex,
       
  2228                                    double key) {
       
  2229         rangeCheck(a.length, fromIndex, toIndex);
       
  2230         return binarySearch0(a, fromIndex, toIndex, key);
       
  2231     }
       
  2232 
       
  2233     // Like public version, but without range checks.
       
  2234     private static int binarySearch0(double[] a, int fromIndex, int toIndex,
       
  2235                                      double key) {
       
  2236         int low = fromIndex;
       
  2237         int high = toIndex - 1;
       
  2238 
       
  2239         while (low <= high) {
       
  2240             int mid = (low + high) >>> 1;
       
  2241             double midVal = a[mid];
       
  2242 
       
  2243             if (midVal < key)
       
  2244                 low = mid + 1;  // Neither val is NaN, thisVal is smaller
       
  2245             else if (midVal > key)
       
  2246                 high = mid - 1; // Neither val is NaN, thisVal is larger
       
  2247             else {
       
  2248                 long midBits = Double.doubleToLongBits(midVal);
       
  2249                 long keyBits = Double.doubleToLongBits(key);
       
  2250                 if (midBits == keyBits)     // Values are equal
       
  2251                     return mid;             // Key found
       
  2252                 else if (midBits < keyBits) // (-0.0, 0.0) or (!NaN, NaN)
       
  2253                     low = mid + 1;
       
  2254                 else                        // (0.0, -0.0) or (NaN, !NaN)
       
  2255                     high = mid - 1;
       
  2256             }
       
  2257         }
       
  2258         return -(low + 1);  // key not found.
       
  2259     }
       
  2260 
       
  2261     /**
       
  2262      * Searches the specified array of floats for the specified value using
       
  2263      * the binary search algorithm. The array must be sorted
       
  2264      * (as by the {@link #sort(float[])} method) prior to making this call. If
       
  2265      * it is not sorted, the results are undefined. If the array contains
       
  2266      * multiple elements with the specified value, there is no guarantee which
       
  2267      * one will be found. This method considers all NaN values to be
       
  2268      * equivalent and equal.
       
  2269      *
       
  2270      * @param a the array to be searched
       
  2271      * @param key the value to be searched for
       
  2272      * @return index of the search key, if it is contained in the array;
       
  2273      *         otherwise, <code>(-(<i>insertion point</i>) - 1)</code>. The
       
  2274      *         <i>insertion point</i> is defined as the point at which the
       
  2275      *         key would be inserted into the array: the index of the first
       
  2276      *         element greater than the key, or {@code a.length} if all
       
  2277      *         elements in the array are less than the specified key. Note
       
  2278      *         that this guarantees that the return value will be &gt;= 0 if
       
  2279      *         and only if the key is found.
       
  2280      */
       
  2281     public static int binarySearch(float[] a, float key) {
       
  2282         return binarySearch0(a, 0, a.length, key);
       
  2283     }
       
  2284 
       
  2285     /**
       
  2286      * Searches a range of
       
  2287      * the specified array of floats for the specified value using
       
  2288      * the binary search algorithm.
       
  2289      * The range must be sorted
       
  2290      * (as by the {@link #sort(float[], int, int)} method)
       
  2291      * prior to making this call. If
       
  2292      * it is not sorted, the results are undefined. If the range contains
       
  2293      * multiple elements with the specified value, there is no guarantee which
       
  2294      * one will be found. This method considers all NaN values to be
       
  2295      * equivalent and equal.
       
  2296      *
       
  2297      * @param a the array to be searched
       
  2298      * @param fromIndex the index of the first element (inclusive) to be
       
  2299      *          searched
       
  2300      * @param toIndex the index of the last element (exclusive) to be searched
       
  2301      * @param key the value to be searched for
       
  2302      * @return index of the search key, if it is contained in the array
       
  2303      *         within the specified range;
       
  2304      *         otherwise, <code>(-(<i>insertion point</i>) - 1)</code>. The
       
  2305      *         <i>insertion point</i> is defined as the point at which the
       
  2306      *         key would be inserted into the array: the index of the first
       
  2307      *         element in the range greater than the key,
       
  2308      *         or {@code toIndex} if all
       
  2309      *         elements in the range are less than the specified key. Note
       
  2310      *         that this guarantees that the return value will be &gt;= 0 if
       
  2311      *         and only if the key is found.
       
  2312      * @throws IllegalArgumentException
       
  2313      *         if {@code fromIndex > toIndex}
       
  2314      * @throws ArrayIndexOutOfBoundsException
       
  2315      *         if {@code fromIndex < 0 or toIndex > a.length}
       
  2316      * @since 1.6
       
  2317      */
       
  2318     public static int binarySearch(float[] a, int fromIndex, int toIndex,
       
  2319                                    float key) {
       
  2320         rangeCheck(a.length, fromIndex, toIndex);
       
  2321         return binarySearch0(a, fromIndex, toIndex, key);
       
  2322     }
       
  2323 
       
  2324     // Like public version, but without range checks.
       
  2325     private static int binarySearch0(float[] a, int fromIndex, int toIndex,
       
  2326                                      float key) {
       
  2327         int low = fromIndex;
       
  2328         int high = toIndex - 1;
       
  2329 
       
  2330         while (low <= high) {
       
  2331             int mid = (low + high) >>> 1;
       
  2332             float midVal = a[mid];
       
  2333 
       
  2334             if (midVal < key)
       
  2335                 low = mid + 1;  // Neither val is NaN, thisVal is smaller
       
  2336             else if (midVal > key)
       
  2337                 high = mid - 1; // Neither val is NaN, thisVal is larger
       
  2338             else {
       
  2339                 int midBits = Float.floatToIntBits(midVal);
       
  2340                 int keyBits = Float.floatToIntBits(key);
       
  2341                 if (midBits == keyBits)     // Values are equal
       
  2342                     return mid;             // Key found
       
  2343                 else if (midBits < keyBits) // (-0.0, 0.0) or (!NaN, NaN)
       
  2344                     low = mid + 1;
       
  2345                 else                        // (0.0, -0.0) or (NaN, !NaN)
       
  2346                     high = mid - 1;
       
  2347             }
       
  2348         }
       
  2349         return -(low + 1);  // key not found.
       
  2350     }
       
  2351 
       
  2352     /**
       
  2353      * Searches the specified array for the specified object using the binary
       
  2354      * search algorithm. The array must be sorted into ascending order
       
  2355      * according to the
       
  2356      * {@linkplain Comparable natural ordering}
       
  2357      * of its elements (as by the
       
  2358      * {@link #sort(Object[])} method) prior to making this call.
       
  2359      * If it is not sorted, the results are undefined.
       
  2360      * (If the array contains elements that are not mutually comparable (for
       
  2361      * example, strings and integers), it <i>cannot</i> be sorted according
       
  2362      * to the natural ordering of its elements, hence results are undefined.)
       
  2363      * If the array contains multiple
       
  2364      * elements equal to the specified object, there is no guarantee which
       
  2365      * one will be found.
       
  2366      *
       
  2367      * @param a the array to be searched
       
  2368      * @param key the value to be searched for
       
  2369      * @return index of the search key, if it is contained in the array;
       
  2370      *         otherwise, <code>(-(<i>insertion point</i>) - 1)</code>.  The
       
  2371      *         <i>insertion point</i> is defined as the point at which the
       
  2372      *         key would be inserted into the array: the index of the first
       
  2373      *         element greater than the key, or {@code a.length} if all
       
  2374      *         elements in the array are less than the specified key.  Note
       
  2375      *         that this guarantees that the return value will be &gt;= 0 if
       
  2376      *         and only if the key is found.
       
  2377      * @throws ClassCastException if the search key is not comparable to the
       
  2378      *         elements of the array.
       
  2379      */
       
  2380     public static int binarySearch(Object[] a, Object key) {
       
  2381         return binarySearch0(a, 0, a.length, key);
       
  2382     }
       
  2383 
       
  2384     /**
       
  2385      * Searches a range of
       
  2386      * the specified array for the specified object using the binary
       
  2387      * search algorithm.
       
  2388      * The range must be sorted into ascending order
       
  2389      * according to the
       
  2390      * {@linkplain Comparable natural ordering}
       
  2391      * of its elements (as by the
       
  2392      * {@link #sort(Object[], int, int)} method) prior to making this
       
  2393      * call.  If it is not sorted, the results are undefined.
       
  2394      * (If the range contains elements that are not mutually comparable (for
       
  2395      * example, strings and integers), it <i>cannot</i> be sorted according
       
  2396      * to the natural ordering of its elements, hence results are undefined.)
       
  2397      * If the range contains multiple
       
  2398      * elements equal to the specified object, there is no guarantee which
       
  2399      * one will be found.
       
  2400      *
       
  2401      * @param a the array to be searched
       
  2402      * @param fromIndex the index of the first element (inclusive) to be
       
  2403      *          searched
       
  2404      * @param toIndex the index of the last element (exclusive) to be searched
       
  2405      * @param key the value to be searched for
       
  2406      * @return index of the search key, if it is contained in the array
       
  2407      *         within the specified range;
       
  2408      *         otherwise, <code>(-(<i>insertion point</i>) - 1)</code>.  The
       
  2409      *         <i>insertion point</i> is defined as the point at which the
       
  2410      *         key would be inserted into the array: the index of the first
       
  2411      *         element in the range greater than the key,
       
  2412      *         or {@code toIndex} if all
       
  2413      *         elements in the range are less than the specified key.  Note
       
  2414      *         that this guarantees that the return value will be &gt;= 0 if
       
  2415      *         and only if the key is found.
       
  2416      * @throws ClassCastException if the search key is not comparable to the
       
  2417      *         elements of the array within the specified range.
       
  2418      * @throws IllegalArgumentException
       
  2419      *         if {@code fromIndex > toIndex}
       
  2420      * @throws ArrayIndexOutOfBoundsException
       
  2421      *         if {@code fromIndex < 0 or toIndex > a.length}
       
  2422      * @since 1.6
       
  2423      */
       
  2424     public static int binarySearch(Object[] a, int fromIndex, int toIndex,
       
  2425                                    Object key) {
       
  2426         rangeCheck(a.length, fromIndex, toIndex);
       
  2427         return binarySearch0(a, fromIndex, toIndex, key);
       
  2428     }
       
  2429 
       
  2430     // Like public version, but without range checks.
       
  2431     private static int binarySearch0(Object[] a, int fromIndex, int toIndex,
       
  2432                                      Object key) {
       
  2433         int low = fromIndex;
       
  2434         int high = toIndex - 1;
       
  2435 
       
  2436         while (low <= high) {
       
  2437             int mid = (low + high) >>> 1;
       
  2438             @SuppressWarnings("rawtypes")
       
  2439             Comparable midVal = (Comparable)a[mid];
       
  2440             @SuppressWarnings("unchecked")
       
  2441             int cmp = midVal.compareTo(key);
       
  2442 
       
  2443             if (cmp < 0)
       
  2444                 low = mid + 1;
       
  2445             else if (cmp > 0)
       
  2446                 high = mid - 1;
       
  2447             else
       
  2448                 return mid; // key found
       
  2449         }
       
  2450         return -(low + 1);  // key not found.
       
  2451     }
       
  2452 
       
  2453     /**
       
  2454      * Searches the specified array for the specified object using the binary
       
  2455      * search algorithm.  The array must be sorted into ascending order
       
  2456      * according to the specified comparator (as by the
       
  2457      * {@link #sort(Object[], Comparator) sort(T[], Comparator)}
       
  2458      * method) prior to making this call.  If it is
       
  2459      * not sorted, the results are undefined.
       
  2460      * If the array contains multiple
       
  2461      * elements equal to the specified object, there is no guarantee which one
       
  2462      * will be found.
       
  2463      *
       
  2464      * @param <T> the class of the objects in the array
       
  2465      * @param a the array to be searched
       
  2466      * @param key the value to be searched for
       
  2467      * @param c the comparator by which the array is ordered.  A
       
  2468      *        {@code null} value indicates that the elements'
       
  2469      *        {@linkplain Comparable natural ordering} should be used.
       
  2470      * @return index of the search key, if it is contained in the array;
       
  2471      *         otherwise, <code>(-(<i>insertion point</i>) - 1)</code>.  The
       
  2472      *         <i>insertion point</i> is defined as the point at which the
       
  2473      *         key would be inserted into the array: the index of the first
       
  2474      *         element greater than the key, or {@code a.length} if all
       
  2475      *         elements in the array are less than the specified key.  Note
       
  2476      *         that this guarantees that the return value will be &gt;= 0 if
       
  2477      *         and only if the key is found.
       
  2478      * @throws ClassCastException if the array contains elements that are not
       
  2479      *         <i>mutually comparable</i> using the specified comparator,
       
  2480      *         or the search key is not comparable to the
       
  2481      *         elements of the array using this comparator.
       
  2482      */
       
  2483     public static <T> int binarySearch(T[] a, T key, Comparator<? super T> c) {
       
  2484         return binarySearch0(a, 0, a.length, key, c);
       
  2485     }
       
  2486 
       
  2487     /**
       
  2488      * Searches a range of
       
  2489      * the specified array for the specified object using the binary
       
  2490      * search algorithm.
       
  2491      * The range must be sorted into ascending order
       
  2492      * according to the specified comparator (as by the
       
  2493      * {@link #sort(Object[], int, int, Comparator)
       
  2494      * sort(T[], int, int, Comparator)}
       
  2495      * method) prior to making this call.
       
  2496      * If it is not sorted, the results are undefined.
       
  2497      * If the range contains multiple elements equal to the specified object,
       
  2498      * there is no guarantee which one will be found.
       
  2499      *
       
  2500      * @param <T> the class of the objects in the array
       
  2501      * @param a the array to be searched
       
  2502      * @param fromIndex the index of the first element (inclusive) to be
       
  2503      *          searched
       
  2504      * @param toIndex the index of the last element (exclusive) to be searched
       
  2505      * @param key the value to be searched for
       
  2506      * @param c the comparator by which the array is ordered.  A
       
  2507      *        {@code null} value indicates that the elements'
       
  2508      *        {@linkplain Comparable natural ordering} should be used.
       
  2509      * @return index of the search key, if it is contained in the array
       
  2510      *         within the specified range;
       
  2511      *         otherwise, <code>(-(<i>insertion point</i>) - 1)</code>.  The
       
  2512      *         <i>insertion point</i> is defined as the point at which the
       
  2513      *         key would be inserted into the array: the index of the first
       
  2514      *         element in the range greater than the key,
       
  2515      *         or {@code toIndex} if all
       
  2516      *         elements in the range are less than the specified key.  Note
       
  2517      *         that this guarantees that the return value will be &gt;= 0 if
       
  2518      *         and only if the key is found.
       
  2519      * @throws ClassCastException if the range contains elements that are not
       
  2520      *         <i>mutually comparable</i> using the specified comparator,
       
  2521      *         or the search key is not comparable to the
       
  2522      *         elements in the range using this comparator.
       
  2523      * @throws IllegalArgumentException
       
  2524      *         if {@code fromIndex > toIndex}
       
  2525      * @throws ArrayIndexOutOfBoundsException
       
  2526      *         if {@code fromIndex < 0 or toIndex > a.length}
       
  2527      * @since 1.6
       
  2528      */
       
  2529     public static <T> int binarySearch(T[] a, int fromIndex, int toIndex,
       
  2530                                        T key, Comparator<? super T> c) {
       
  2531         rangeCheck(a.length, fromIndex, toIndex);
       
  2532         return binarySearch0(a, fromIndex, toIndex, key, c);
       
  2533     }
       
  2534 
       
  2535     // Like public version, but without range checks.
       
  2536     private static <T> int binarySearch0(T[] a, int fromIndex, int toIndex,
       
  2537                                          T key, Comparator<? super T> c) {
       
  2538         if (c == null) {
       
  2539             return binarySearch0(a, fromIndex, toIndex, key);
       
  2540         }
       
  2541         int low = fromIndex;
       
  2542         int high = toIndex - 1;
       
  2543 
       
  2544         while (low <= high) {
       
  2545             int mid = (low + high) >>> 1;
       
  2546             T midVal = a[mid];
       
  2547             int cmp = c.compare(midVal, key);
       
  2548             if (cmp < 0)
       
  2549                 low = mid + 1;
       
  2550             else if (cmp > 0)
       
  2551                 high = mid - 1;
       
  2552             else
       
  2553                 return mid; // key found
       
  2554         }
       
  2555         return -(low + 1);  // key not found.
       
  2556     }
       
  2557 
       
  2558     // Equality Testing
       
  2559 
       
  2560     /**
       
  2561      * Returns {@code true} if the two specified arrays of longs are
       
  2562      * <i>equal</i> to one another.  Two arrays are considered equal if both
       
  2563      * arrays contain the same number of elements, and all corresponding pairs
       
  2564      * of elements in the two arrays are equal.  In other words, two arrays
       
  2565      * are equal if they contain the same elements in the same order.  Also,
       
  2566      * two array references are considered equal if both are {@code null}.
       
  2567      *
       
  2568      * @param a one array to be tested for equality
       
  2569      * @param a2 the other array to be tested for equality
       
  2570      * @return {@code true} if the two arrays are equal
       
  2571      */
       
  2572     public static boolean equals(long[] a, long[] a2) {
       
  2573         if (a==a2)
       
  2574             return true;
       
  2575         if (a==null || a2==null)
       
  2576             return false;
       
  2577 
       
  2578         int length = a.length;
       
  2579         if (a2.length != length)
       
  2580             return false;
       
  2581 
       
  2582         return ArraysSupport.mismatch(a, a2, length) < 0;
       
  2583     }
       
  2584 
       
  2585     /**
       
  2586      * Returns true if the two specified arrays of longs, over the specified
       
  2587      * ranges, are <i>equal</i> to one another.
       
  2588      *
       
  2589      * <p>Two arrays are considered equal if the number of elements covered by
       
  2590      * each range is the same, and all corresponding pairs of elements over the
       
  2591      * specified ranges in the two arrays are equal.  In other words, two arrays
       
  2592      * are equal if they contain, over the specified ranges, the same elements
       
  2593      * in the same order.
       
  2594      *
       
  2595      * @param a the first array to be tested for equality
       
  2596      * @param aFromIndex the index (inclusive) of the first element in the
       
  2597      *                   first array to be tested
       
  2598      * @param aToIndex the index (exclusive) of the last element in the
       
  2599      *                 first array to be tested
       
  2600      * @param b the second array to be tested fro equality
       
  2601      * @param bFromIndex the index (inclusive) of the first element in the
       
  2602      *                   second array to be tested
       
  2603      * @param bToIndex the index (exclusive) of the last element in the
       
  2604      *                 second array to be tested
       
  2605      * @return {@code true} if the two arrays, over the specified ranges, are
       
  2606      *         equal
       
  2607      * @throws IllegalArgumentException
       
  2608      *         if {@code aFromIndex > aToIndex} or
       
  2609      *         if {@code bFromIndex > bToIndex}
       
  2610      * @throws ArrayIndexOutOfBoundsException
       
  2611      *         if {@code aFromIndex < 0 or aToIndex > a.length} or
       
  2612      *         if {@code bFromIndex < 0 or bToIndex > b.length}
       
  2613      * @throws NullPointerException
       
  2614      *         if either array is {@code null}
       
  2615      * @since 9
       
  2616      */
       
  2617     public static boolean equals(long[] a, int aFromIndex, int aToIndex,
       
  2618                                  long[] b, int bFromIndex, int bToIndex) {
       
  2619         rangeCheck(a.length, aFromIndex, aToIndex);
       
  2620         rangeCheck(b.length, bFromIndex, bToIndex);
       
  2621 
       
  2622         int aLength = aToIndex - aFromIndex;
       
  2623         int bLength = bToIndex - bFromIndex;
       
  2624         if (aLength != bLength)
       
  2625             return false;
       
  2626 
       
  2627         return ArraysSupport.mismatch(a, aFromIndex,
       
  2628                                       b, bFromIndex,
       
  2629                                       aLength) < 0;
       
  2630     }
       
  2631 
       
  2632     /**
       
  2633      * Returns {@code true} if the two specified arrays of ints are
       
  2634      * <i>equal</i> to one another.  Two arrays are considered equal if both
       
  2635      * arrays contain the same number of elements, and all corresponding pairs
       
  2636      * of elements in the two arrays are equal.  In other words, two arrays
       
  2637      * are equal if they contain the same elements in the same order.  Also,
       
  2638      * two array references are considered equal if both are {@code null}.
       
  2639      *
       
  2640      * @param a one array to be tested for equality
       
  2641      * @param a2 the other array to be tested for equality
       
  2642      * @return {@code true} if the two arrays are equal
       
  2643      */
       
  2644     public static boolean equals(int[] a, int[] a2) {
       
  2645         if (a==a2)
       
  2646             return true;
       
  2647         if (a==null || a2==null)
       
  2648             return false;
       
  2649 
       
  2650         int length = a.length;
       
  2651         if (a2.length != length)
       
  2652             return false;
       
  2653 
       
  2654         return ArraysSupport.mismatch(a, a2, length) < 0;
       
  2655     }
       
  2656 
       
  2657     /**
       
  2658      * Returns true if the two specified arrays of ints, over the specified
       
  2659      * ranges, are <i>equal</i> to one another.
       
  2660      *
       
  2661      * <p>Two arrays are considered equal if the number of elements covered by
       
  2662      * each range is the same, and all corresponding pairs of elements over the
       
  2663      * specified ranges in the two arrays are equal.  In other words, two arrays
       
  2664      * are equal if they contain, over the specified ranges, the same elements
       
  2665      * in the same order.
       
  2666      *
       
  2667      * @param a the first array to be tested for equality
       
  2668      * @param aFromIndex the index (inclusive) of the first element in the
       
  2669      *                   first array to be tested
       
  2670      * @param aToIndex the index (exclusive) of the last element in the
       
  2671      *                 first array to be tested
       
  2672      * @param b the second array to be tested fro equality
       
  2673      * @param bFromIndex the index (inclusive) of the first element in the
       
  2674      *                   second array to be tested
       
  2675      * @param bToIndex the index (exclusive) of the last element in the
       
  2676      *                 second array to be tested
       
  2677      * @return {@code true} if the two arrays, over the specified ranges, are
       
  2678      *         equal
       
  2679      * @throws IllegalArgumentException
       
  2680      *         if {@code aFromIndex > aToIndex} or
       
  2681      *         if {@code bFromIndex > bToIndex}
       
  2682      * @throws ArrayIndexOutOfBoundsException
       
  2683      *         if {@code aFromIndex < 0 or aToIndex > a.length} or
       
  2684      *         if {@code bFromIndex < 0 or bToIndex > b.length}
       
  2685      * @throws NullPointerException
       
  2686      *         if either array is {@code null}
       
  2687      * @since 9
       
  2688      */
       
  2689     public static boolean equals(int[] a, int aFromIndex, int aToIndex,
       
  2690                                  int[] b, int bFromIndex, int bToIndex) {
       
  2691         rangeCheck(a.length, aFromIndex, aToIndex);
       
  2692         rangeCheck(b.length, bFromIndex, bToIndex);
       
  2693 
       
  2694         int aLength = aToIndex - aFromIndex;
       
  2695         int bLength = bToIndex - bFromIndex;
       
  2696         if (aLength != bLength)
       
  2697             return false;
       
  2698 
       
  2699         return ArraysSupport.mismatch(a, aFromIndex,
       
  2700                                       b, bFromIndex,
       
  2701                                       aLength) < 0;
       
  2702     }
       
  2703 
       
  2704     /**
       
  2705      * Returns {@code true} if the two specified arrays of shorts are
       
  2706      * <i>equal</i> to one another.  Two arrays are considered equal if both
       
  2707      * arrays contain the same number of elements, and all corresponding pairs
       
  2708      * of elements in the two arrays are equal.  In other words, two arrays
       
  2709      * are equal if they contain the same elements in the same order.  Also,
       
  2710      * two array references are considered equal if both are {@code null}.
       
  2711      *
       
  2712      * @param a one array to be tested for equality
       
  2713      * @param a2 the other array to be tested for equality
       
  2714      * @return {@code true} if the two arrays are equal
       
  2715      */
       
  2716     public static boolean equals(short[] a, short a2[]) {
       
  2717         if (a==a2)
       
  2718             return true;
       
  2719         if (a==null || a2==null)
       
  2720             return false;
       
  2721 
       
  2722         int length = a.length;
       
  2723         if (a2.length != length)
       
  2724             return false;
       
  2725 
       
  2726         return ArraysSupport.mismatch(a, a2, length) < 0;
       
  2727     }
       
  2728 
       
  2729     /**
       
  2730      * Returns true if the two specified arrays of shorts, over the specified
       
  2731      * ranges, are <i>equal</i> to one another.
       
  2732      *
       
  2733      * <p>Two arrays are considered equal if the number of elements covered by
       
  2734      * each range is the same, and all corresponding pairs of elements over the
       
  2735      * specified ranges in the two arrays are equal.  In other words, two arrays
       
  2736      * are equal if they contain, over the specified ranges, the same elements
       
  2737      * in the same order.
       
  2738      *
       
  2739      * @param a the first array to be tested for equality
       
  2740      * @param aFromIndex the index (inclusive) of the first element in the
       
  2741      *                   first array to be tested
       
  2742      * @param aToIndex the index (exclusive) of the last element in the
       
  2743      *                 first array to be tested
       
  2744      * @param b the second array to be tested fro equality
       
  2745      * @param bFromIndex the index (inclusive) of the first element in the
       
  2746      *                   second array to be tested
       
  2747      * @param bToIndex the index (exclusive) of the last element in the
       
  2748      *                 second array to be tested
       
  2749      * @return {@code true} if the two arrays, over the specified ranges, are
       
  2750      *         equal
       
  2751      * @throws IllegalArgumentException
       
  2752      *         if {@code aFromIndex > aToIndex} or
       
  2753      *         if {@code bFromIndex > bToIndex}
       
  2754      * @throws ArrayIndexOutOfBoundsException
       
  2755      *         if {@code aFromIndex < 0 or aToIndex > a.length} or
       
  2756      *         if {@code bFromIndex < 0 or bToIndex > b.length}
       
  2757      * @throws NullPointerException
       
  2758      *         if either array is {@code null}
       
  2759      * @since 9
       
  2760      */
       
  2761     public static boolean equals(short[] a, int aFromIndex, int aToIndex,
       
  2762                                  short[] b, int bFromIndex, int bToIndex) {
       
  2763         rangeCheck(a.length, aFromIndex, aToIndex);
       
  2764         rangeCheck(b.length, bFromIndex, bToIndex);
       
  2765 
       
  2766         int aLength = aToIndex - aFromIndex;
       
  2767         int bLength = bToIndex - bFromIndex;
       
  2768         if (aLength != bLength)
       
  2769             return false;
       
  2770 
       
  2771         return ArraysSupport.mismatch(a, aFromIndex,
       
  2772                                       b, bFromIndex,
       
  2773                                       aLength) < 0;
       
  2774     }
       
  2775 
       
  2776     /**
       
  2777      * Returns {@code true} if the two specified arrays of chars are
       
  2778      * <i>equal</i> to one another.  Two arrays are considered equal if both
       
  2779      * arrays contain the same number of elements, and all corresponding pairs
       
  2780      * of elements in the two arrays are equal.  In other words, two arrays
       
  2781      * are equal if they contain the same elements in the same order.  Also,
       
  2782      * two array references are considered equal if both are {@code null}.
       
  2783      *
       
  2784      * @param a one array to be tested for equality
       
  2785      * @param a2 the other array to be tested for equality
       
  2786      * @return {@code true} if the two arrays are equal
       
  2787      */
       
  2788     @HotSpotIntrinsicCandidate
       
  2789     public static boolean equals(char[] a, char[] a2) {
       
  2790         if (a==a2)
       
  2791             return true;
       
  2792         if (a==null || a2==null)
       
  2793             return false;
       
  2794 
       
  2795         int length = a.length;
       
  2796         if (a2.length != length)
       
  2797             return false;
       
  2798 
       
  2799         return ArraysSupport.mismatch(a, a2, length) < 0;
       
  2800     }
       
  2801 
       
  2802     /**
       
  2803      * Returns true if the two specified arrays of chars, over the specified
       
  2804      * ranges, are <i>equal</i> to one another.
       
  2805      *
       
  2806      * <p>Two arrays are considered equal if the number of elements covered by
       
  2807      * each range is the same, and all corresponding pairs of elements over the
       
  2808      * specified ranges in the two arrays are equal.  In other words, two arrays
       
  2809      * are equal if they contain, over the specified ranges, the same elements
       
  2810      * in the same order.
       
  2811      *
       
  2812      * @param a the first array to be tested for equality
       
  2813      * @param aFromIndex the index (inclusive) of the first element in the
       
  2814      *                   first array to be tested
       
  2815      * @param aToIndex the index (exclusive) of the last element in the
       
  2816      *                 first array to be tested
       
  2817      * @param b the second array to be tested fro equality
       
  2818      * @param bFromIndex the index (inclusive) of the first element in the
       
  2819      *                   second array to be tested
       
  2820      * @param bToIndex the index (exclusive) of the last element in the
       
  2821      *                 second array to be tested
       
  2822      * @return {@code true} if the two arrays, over the specified ranges, are
       
  2823      *         equal
       
  2824      * @throws IllegalArgumentException
       
  2825      *         if {@code aFromIndex > aToIndex} or
       
  2826      *         if {@code bFromIndex > bToIndex}
       
  2827      * @throws ArrayIndexOutOfBoundsException
       
  2828      *         if {@code aFromIndex < 0 or aToIndex > a.length} or
       
  2829      *         if {@code bFromIndex < 0 or bToIndex > b.length}
       
  2830      * @throws NullPointerException
       
  2831      *         if either array is {@code null}
       
  2832      * @since 9
       
  2833      */
       
  2834     public static boolean equals(char[] a, int aFromIndex, int aToIndex,
       
  2835                                  char[] b, int bFromIndex, int bToIndex) {
       
  2836         rangeCheck(a.length, aFromIndex, aToIndex);
       
  2837         rangeCheck(b.length, bFromIndex, bToIndex);
       
  2838 
       
  2839         int aLength = aToIndex - aFromIndex;
       
  2840         int bLength = bToIndex - bFromIndex;
       
  2841         if (aLength != bLength)
       
  2842             return false;
       
  2843 
       
  2844         return ArraysSupport.mismatch(a, aFromIndex,
       
  2845                                       b, bFromIndex,
       
  2846                                       aLength) < 0;
       
  2847     }
       
  2848 
       
  2849     /**
       
  2850      * Returns {@code true} if the two specified arrays of bytes are
       
  2851      * <i>equal</i> to one another.  Two arrays are considered equal if both
       
  2852      * arrays contain the same number of elements, and all corresponding pairs
       
  2853      * of elements in the two arrays are equal.  In other words, two arrays
       
  2854      * are equal if they contain the same elements in the same order.  Also,
       
  2855      * two array references are considered equal if both are {@code null}.
       
  2856      *
       
  2857      * @param a one array to be tested for equality
       
  2858      * @param a2 the other array to be tested for equality
       
  2859      * @return {@code true} if the two arrays are equal
       
  2860      */
       
  2861     @HotSpotIntrinsicCandidate
       
  2862     public static boolean equals(byte[] a, byte[] a2) {
       
  2863         if (a==a2)
       
  2864             return true;
       
  2865         if (a==null || a2==null)
       
  2866             return false;
       
  2867 
       
  2868         int length = a.length;
       
  2869         if (a2.length != length)
       
  2870             return false;
       
  2871 
       
  2872         return ArraysSupport.mismatch(a, a2, length) < 0;
       
  2873     }
       
  2874 
       
  2875     /**
       
  2876      * Returns true if the two specified arrays of bytes, over the specified
       
  2877      * ranges, are <i>equal</i> to one another.
       
  2878      *
       
  2879      * <p>Two arrays are considered equal if the number of elements covered by
       
  2880      * each range is the same, and all corresponding pairs of elements over the
       
  2881      * specified ranges in the two arrays are equal.  In other words, two arrays
       
  2882      * are equal if they contain, over the specified ranges, the same elements
       
  2883      * in the same order.
       
  2884      *
       
  2885      * @param a the first array to be tested for equality
       
  2886      * @param aFromIndex the index (inclusive) of the first element in the
       
  2887      *                   first array to be tested
       
  2888      * @param aToIndex the index (exclusive) of the last element in the
       
  2889      *                 first array to be tested
       
  2890      * @param b the second array to be tested fro equality
       
  2891      * @param bFromIndex the index (inclusive) of the first element in the
       
  2892      *                   second array to be tested
       
  2893      * @param bToIndex the index (exclusive) of the last element in the
       
  2894      *                 second array to be tested
       
  2895      * @return {@code true} if the two arrays, over the specified ranges, are
       
  2896      *         equal
       
  2897      * @throws IllegalArgumentException
       
  2898      *         if {@code aFromIndex > aToIndex} or
       
  2899      *         if {@code bFromIndex > bToIndex}
       
  2900      * @throws ArrayIndexOutOfBoundsException
       
  2901      *         if {@code aFromIndex < 0 or aToIndex > a.length} or
       
  2902      *         if {@code bFromIndex < 0 or bToIndex > b.length}
       
  2903      * @throws NullPointerException
       
  2904      *         if either array is {@code null}
       
  2905      * @since 9
       
  2906      */
       
  2907     public static boolean equals(byte[] a, int aFromIndex, int aToIndex,
       
  2908                                  byte[] b, int bFromIndex, int bToIndex) {
       
  2909         rangeCheck(a.length, aFromIndex, aToIndex);
       
  2910         rangeCheck(b.length, bFromIndex, bToIndex);
       
  2911 
       
  2912         int aLength = aToIndex - aFromIndex;
       
  2913         int bLength = bToIndex - bFromIndex;
       
  2914         if (aLength != bLength)
       
  2915             return false;
       
  2916 
       
  2917         return ArraysSupport.mismatch(a, aFromIndex,
       
  2918                                       b, bFromIndex,
       
  2919                                       aLength) < 0;
       
  2920     }
       
  2921 
       
  2922     /**
       
  2923      * Returns {@code true} if the two specified arrays of booleans are
       
  2924      * <i>equal</i> to one another.  Two arrays are considered equal if both
       
  2925      * arrays contain the same number of elements, and all corresponding pairs
       
  2926      * of elements in the two arrays are equal.  In other words, two arrays
       
  2927      * are equal if they contain the same elements in the same order.  Also,
       
  2928      * two array references are considered equal if both are {@code null}.
       
  2929      *
       
  2930      * @param a one array to be tested for equality
       
  2931      * @param a2 the other array to be tested for equality
       
  2932      * @return {@code true} if the two arrays are equal
       
  2933      */
       
  2934     public static boolean equals(boolean[] a, boolean[] a2) {
       
  2935         if (a==a2)
       
  2936             return true;
       
  2937         if (a==null || a2==null)
       
  2938             return false;
       
  2939 
       
  2940         int length = a.length;
       
  2941         if (a2.length != length)
       
  2942             return false;
       
  2943 
       
  2944         return ArraysSupport.mismatch(a, a2, length) < 0;
       
  2945     }
       
  2946 
       
  2947     /**
       
  2948      * Returns true if the two specified arrays of booleans, over the specified
       
  2949      * ranges, are <i>equal</i> to one another.
       
  2950      *
       
  2951      * <p>Two arrays are considered equal if the number of elements covered by
       
  2952      * each range is the same, and all corresponding pairs of elements over the
       
  2953      * specified ranges in the two arrays are equal.  In other words, two arrays
       
  2954      * are equal if they contain, over the specified ranges, the same elements
       
  2955      * in the same order.
       
  2956      *
       
  2957      * @param a the first array to be tested for equality
       
  2958      * @param aFromIndex the index (inclusive) of the first element in the
       
  2959      *                   first array to be tested
       
  2960      * @param aToIndex the index (exclusive) of the last element in the
       
  2961      *                 first array to be tested
       
  2962      * @param b the second array to be tested fro equality
       
  2963      * @param bFromIndex the index (inclusive) of the first element in the
       
  2964      *                   second array to be tested
       
  2965      * @param bToIndex the index (exclusive) of the last element in the
       
  2966      *                 second array to be tested
       
  2967      * @return {@code true} if the two arrays, over the specified ranges, are
       
  2968      *         equal
       
  2969      * @throws IllegalArgumentException
       
  2970      *         if {@code aFromIndex > aToIndex} or
       
  2971      *         if {@code bFromIndex > bToIndex}
       
  2972      * @throws ArrayIndexOutOfBoundsException
       
  2973      *         if {@code aFromIndex < 0 or aToIndex > a.length} or
       
  2974      *         if {@code bFromIndex < 0 or bToIndex > b.length}
       
  2975      * @throws NullPointerException
       
  2976      *         if either array is {@code null}
       
  2977      * @since 9
       
  2978      */
       
  2979     public static boolean equals(boolean[] a, int aFromIndex, int aToIndex,
       
  2980                                  boolean[] b, int bFromIndex, int bToIndex) {
       
  2981         rangeCheck(a.length, aFromIndex, aToIndex);
       
  2982         rangeCheck(b.length, bFromIndex, bToIndex);
       
  2983 
       
  2984         int aLength = aToIndex - aFromIndex;
       
  2985         int bLength = bToIndex - bFromIndex;
       
  2986         if (aLength != bLength)
       
  2987             return false;
       
  2988 
       
  2989         return ArraysSupport.mismatch(a, aFromIndex,
       
  2990                                       b, bFromIndex,
       
  2991                                       aLength) < 0;
       
  2992     }
       
  2993 
       
  2994     /**
       
  2995      * Returns {@code true} if the two specified arrays of doubles are
       
  2996      * <i>equal</i> to one another.  Two arrays are considered equal if both
       
  2997      * arrays contain the same number of elements, and all corresponding pairs
       
  2998      * of elements in the two arrays are equal.  In other words, two arrays
       
  2999      * are equal if they contain the same elements in the same order.  Also,
       
  3000      * two array references are considered equal if both are {@code null}.
       
  3001      *
       
  3002      * Two doubles {@code d1} and {@code d2} are considered equal if:
       
  3003      * <pre>    {@code new Double(d1).equals(new Double(d2))}</pre>
       
  3004      * (Unlike the {@code ==} operator, this method considers
       
  3005      * {@code NaN} equals to itself, and 0.0d unequal to -0.0d.)
       
  3006      *
       
  3007      * @param a one array to be tested for equality
       
  3008      * @param a2 the other array to be tested for equality
       
  3009      * @return {@code true} if the two arrays are equal
       
  3010      * @see Double#equals(Object)
       
  3011      */
       
  3012     public static boolean equals(double[] a, double[] a2) {
       
  3013         if (a==a2)
       
  3014             return true;
       
  3015         if (a==null || a2==null)
       
  3016             return false;
       
  3017 
       
  3018         int length = a.length;
       
  3019         if (a2.length != length)
       
  3020             return false;
       
  3021 
       
  3022         return ArraysSupport.mismatch(a, a2, length) < 0;
       
  3023     }
       
  3024 
       
  3025     /**
       
  3026      * Returns true if the two specified arrays of doubles, over the specified
       
  3027      * ranges, are <i>equal</i> to one another.
       
  3028      *
       
  3029      * <p>Two arrays are considered equal if the number of elements covered by
       
  3030      * each range is the same, and all corresponding pairs of elements over the
       
  3031      * specified ranges in the two arrays are equal.  In other words, two arrays
       
  3032      * are equal if they contain, over the specified ranges, the same elements
       
  3033      * in the same order.
       
  3034      *
       
  3035      * <p>Two doubles {@code d1} and {@code d2} are considered equal if:
       
  3036      * <pre>    {@code new Double(d1).equals(new Double(d2))}</pre>
       
  3037      * (Unlike the {@code ==} operator, this method considers
       
  3038      * {@code NaN} equals to itself, and 0.0d unequal to -0.0d.)
       
  3039      *
       
  3040      * @param a the first array to be tested for equality
       
  3041      * @param aFromIndex the index (inclusive) of the first element in the
       
  3042      *                   first array to be tested
       
  3043      * @param aToIndex the index (exclusive) of the last element in the
       
  3044      *                 first array to be tested
       
  3045      * @param b the second array to be tested fro equality
       
  3046      * @param bFromIndex the index (inclusive) of the first element in the
       
  3047      *                   second array to be tested
       
  3048      * @param bToIndex the index (exclusive) of the last element in the
       
  3049      *                 second array to be tested
       
  3050      * @return {@code true} if the two arrays, over the specified ranges, are
       
  3051      *         equal
       
  3052      * @throws IllegalArgumentException
       
  3053      *         if {@code aFromIndex > aToIndex} or
       
  3054      *         if {@code bFromIndex > bToIndex}
       
  3055      * @throws ArrayIndexOutOfBoundsException
       
  3056      *         if {@code aFromIndex < 0 or aToIndex > a.length} or
       
  3057      *         if {@code bFromIndex < 0 or bToIndex > b.length}
       
  3058      * @throws NullPointerException
       
  3059      *         if either array is {@code null}
       
  3060      * @see Double#equals(Object)
       
  3061      * @since 9
       
  3062      */
       
  3063     public static boolean equals(double[] a, int aFromIndex, int aToIndex,
       
  3064                                  double[] b, int bFromIndex, int bToIndex) {
       
  3065         rangeCheck(a.length, aFromIndex, aToIndex);
       
  3066         rangeCheck(b.length, bFromIndex, bToIndex);
       
  3067 
       
  3068         int aLength = aToIndex - aFromIndex;
       
  3069         int bLength = bToIndex - bFromIndex;
       
  3070         if (aLength != bLength)
       
  3071             return false;
       
  3072 
       
  3073         return ArraysSupport.mismatch(a, aFromIndex,
       
  3074                                       b, bFromIndex, aLength) < 0;
       
  3075     }
       
  3076 
       
  3077     /**
       
  3078      * Returns {@code true} if the two specified arrays of floats are
       
  3079      * <i>equal</i> to one another.  Two arrays are considered equal if both
       
  3080      * arrays contain the same number of elements, and all corresponding pairs
       
  3081      * of elements in the two arrays are equal.  In other words, two arrays
       
  3082      * are equal if they contain the same elements in the same order.  Also,
       
  3083      * two array references are considered equal if both are {@code null}.
       
  3084      *
       
  3085      * Two floats {@code f1} and {@code f2} are considered equal if:
       
  3086      * <pre>    {@code new Float(f1).equals(new Float(f2))}</pre>
       
  3087      * (Unlike the {@code ==} operator, this method considers
       
  3088      * {@code NaN} equals to itself, and 0.0f unequal to -0.0f.)
       
  3089      *
       
  3090      * @param a one array to be tested for equality
       
  3091      * @param a2 the other array to be tested for equality
       
  3092      * @return {@code true} if the two arrays are equal
       
  3093      * @see Float#equals(Object)
       
  3094      */
       
  3095     public static boolean equals(float[] a, float[] a2) {
       
  3096         if (a==a2)
       
  3097             return true;
       
  3098         if (a==null || a2==null)
       
  3099             return false;
       
  3100 
       
  3101         int length = a.length;
       
  3102         if (a2.length != length)
       
  3103             return false;
       
  3104 
       
  3105         return ArraysSupport.mismatch(a, a2, length) < 0;
       
  3106     }
       
  3107 
       
  3108     /**
       
  3109      * Returns true if the two specified arrays of floats, over the specified
       
  3110      * ranges, are <i>equal</i> to one another.
       
  3111      *
       
  3112      * <p>Two arrays are considered equal if the number of elements covered by
       
  3113      * each range is the same, and all corresponding pairs of elements over the
       
  3114      * specified ranges in the two arrays are equal.  In other words, two arrays
       
  3115      * are equal if they contain, over the specified ranges, the same elements
       
  3116      * in the same order.
       
  3117      *
       
  3118      * <p>Two floats {@code f1} and {@code f2} are considered equal if:
       
  3119      * <pre>    {@code new Float(f1).equals(new Float(f2))}</pre>
       
  3120      * (Unlike the {@code ==} operator, this method considers
       
  3121      * {@code NaN} equals to itself, and 0.0f unequal to -0.0f.)
       
  3122      *
       
  3123      * @param a the first array to be tested for equality
       
  3124      * @param aFromIndex the index (inclusive) of the first element in the
       
  3125      *                   first array to be tested
       
  3126      * @param aToIndex the index (exclusive) of the last element in the
       
  3127      *                 first array to be tested
       
  3128      * @param b the second array to be tested fro equality
       
  3129      * @param bFromIndex the index (inclusive) of the first element in the
       
  3130      *                   second array to be tested
       
  3131      * @param bToIndex the index (exclusive) of the last element in the
       
  3132      *                 second array to be tested
       
  3133      * @return {@code true} if the two arrays, over the specified ranges, are
       
  3134      *         equal
       
  3135      * @throws IllegalArgumentException
       
  3136      *         if {@code aFromIndex > aToIndex} or
       
  3137      *         if {@code bFromIndex > bToIndex}
       
  3138      * @throws ArrayIndexOutOfBoundsException
       
  3139      *         if {@code aFromIndex < 0 or aToIndex > a.length} or
       
  3140      *         if {@code bFromIndex < 0 or bToIndex > b.length}
       
  3141      * @throws NullPointerException
       
  3142      *         if either array is {@code null}
       
  3143      * @see Float#equals(Object)
       
  3144      * @since 9
       
  3145      */
       
  3146     public static boolean equals(float[] a, int aFromIndex, int aToIndex,
       
  3147                                  float[] b, int bFromIndex, int bToIndex) {
       
  3148         rangeCheck(a.length, aFromIndex, aToIndex);
       
  3149         rangeCheck(b.length, bFromIndex, bToIndex);
       
  3150 
       
  3151         int aLength = aToIndex - aFromIndex;
       
  3152         int bLength = bToIndex - bFromIndex;
       
  3153         if (aLength != bLength)
       
  3154             return false;
       
  3155 
       
  3156         return ArraysSupport.mismatch(a, aFromIndex,
       
  3157                                       b, bFromIndex, aLength) < 0;
       
  3158     }
       
  3159 
       
  3160     /**
       
  3161      * Returns {@code true} if the two specified arrays of Objects are
       
  3162      * <i>equal</i> to one another.  The two arrays are considered equal if
       
  3163      * both arrays contain the same number of elements, and all corresponding
       
  3164      * pairs of elements in the two arrays are equal.  Two objects {@code e1}
       
  3165      * and {@code e2} are considered <i>equal</i> if
       
  3166      * {@code Objects.equals(e1, e2)}.
       
  3167      * In other words, the two arrays are equal if
       
  3168      * they contain the same elements in the same order.  Also, two array
       
  3169      * references are considered equal if both are {@code null}.
       
  3170      *
       
  3171      * @param a one array to be tested for equality
       
  3172      * @param a2 the other array to be tested for equality
       
  3173      * @return {@code true} if the two arrays are equal
       
  3174      */
       
  3175     public static boolean equals(Object[] a, Object[] a2) {
       
  3176         if (a==a2)
       
  3177             return true;
       
  3178         if (a==null || a2==null)
       
  3179             return false;
       
  3180 
       
  3181         int length = a.length;
       
  3182         if (a2.length != length)
       
  3183             return false;
       
  3184 
       
  3185         for (int i=0; i<length; i++) {
       
  3186             if (!Objects.equals(a[i], a2[i]))
       
  3187                 return false;
       
  3188         }
       
  3189 
       
  3190         return true;
       
  3191     }
       
  3192 
       
  3193     /**
       
  3194      * Returns true if the two specified arrays of Objects, over the specified
       
  3195      * ranges, are <i>equal</i> to one another.
       
  3196      *
       
  3197      * <p>Two arrays are considered equal if the number of elements covered by
       
  3198      * each range is the same, and all corresponding pairs of elements over the
       
  3199      * specified ranges in the two arrays are equal.  In other words, two arrays
       
  3200      * are equal if they contain, over the specified ranges, the same elements
       
  3201      * in the same order.
       
  3202      *
       
  3203      * <p>Two objects {@code e1} and {@code e2} are considered <i>equal</i> if
       
  3204      * {@code Objects.equals(e1, e2)}.
       
  3205      *
       
  3206      * @param a the first array to be tested for equality
       
  3207      * @param aFromIndex the index (inclusive) of the first element in the
       
  3208      *                   first array to be tested
       
  3209      * @param aToIndex the index (exclusive) of the last element in the
       
  3210      *                 first array to be tested
       
  3211      * @param b the second array to be tested fro equality
       
  3212      * @param bFromIndex the index (inclusive) of the first element in the
       
  3213      *                   second array to be tested
       
  3214      * @param bToIndex the index (exclusive) of the last element in the
       
  3215      *                 second array to be tested
       
  3216      * @return {@code true} if the two arrays, over the specified ranges, are
       
  3217      *         equal
       
  3218      * @throws IllegalArgumentException
       
  3219      *         if {@code aFromIndex > aToIndex} or
       
  3220      *         if {@code bFromIndex > bToIndex}
       
  3221      * @throws ArrayIndexOutOfBoundsException
       
  3222      *         if {@code aFromIndex < 0 or aToIndex > a.length} or
       
  3223      *         if {@code bFromIndex < 0 or bToIndex > b.length}
       
  3224      * @throws NullPointerException
       
  3225      *         if either array is {@code null}
       
  3226      * @since 9
       
  3227      */
       
  3228     public static boolean equals(Object[] a, int aFromIndex, int aToIndex,
       
  3229                                  Object[] b, int bFromIndex, int bToIndex) {
       
  3230         rangeCheck(a.length, aFromIndex, aToIndex);
       
  3231         rangeCheck(b.length, bFromIndex, bToIndex);
       
  3232 
       
  3233         int aLength = aToIndex - aFromIndex;
       
  3234         int bLength = bToIndex - bFromIndex;
       
  3235         if (aLength != bLength)
       
  3236             return false;
       
  3237 
       
  3238         for (int i = 0; i < aLength; i++) {
       
  3239             if (!Objects.equals(a[aFromIndex++], b[bFromIndex++]))
       
  3240                 return false;
       
  3241         }
       
  3242 
       
  3243         return true;
       
  3244     }
       
  3245 
       
  3246     /**
       
  3247      * Returns {@code true} if the two specified arrays of Objects are
       
  3248      * <i>equal</i> to one another.
       
  3249      *
       
  3250      * <p>Two arrays are considered equal if both arrays contain the same number
       
  3251      * of elements, and all corresponding pairs of elements in the two arrays
       
  3252      * are equal.  In other words, the two arrays are equal if they contain the
       
  3253      * same elements in the same order.  Also, two array references are
       
  3254      * considered equal if both are {@code null}.
       
  3255      *
       
  3256      * <p>Two objects {@code e1} and {@code e2} are considered <i>equal</i> if,
       
  3257      * given the specified comparator, {@code cmp.compare(e1, e2) == 0}.
       
  3258      *
       
  3259      * @param a one array to be tested for equality
       
  3260      * @param a2 the other array to be tested for equality
       
  3261      * @param cmp the comparator to compare array elements
       
  3262      * @param <T> the type of array elements
       
  3263      * @return {@code true} if the two arrays are equal
       
  3264      * @throws NullPointerException if the comparator is {@code null}
       
  3265      * @since 9
       
  3266      */
       
  3267     public static <T> boolean equals(T[] a, T[] a2, Comparator<? super T> cmp) {
       
  3268         Objects.requireNonNull(cmp);
       
  3269         if (a==a2)
       
  3270             return true;
       
  3271         if (a==null || a2==null)
       
  3272             return false;
       
  3273 
       
  3274         int length = a.length;
       
  3275         if (a2.length != length)
       
  3276             return false;
       
  3277 
       
  3278         for (int i=0; i<length; i++) {
       
  3279             if (cmp.compare(a[i], a2[i]) != 0)
       
  3280                 return false;
       
  3281         }
       
  3282 
       
  3283         return true;
       
  3284     }
       
  3285 
       
  3286     /**
       
  3287      * Returns true if the two specified arrays of Objects, over the specified
       
  3288      * ranges, are <i>equal</i> to one another.
       
  3289      *
       
  3290      * <p>Two arrays are considered equal if the number of elements covered by
       
  3291      * each range is the same, and all corresponding pairs of elements over the
       
  3292      * specified ranges in the two arrays are equal.  In other words, two arrays
       
  3293      * are equal if they contain, over the specified ranges, the same elements
       
  3294      * in the same order.
       
  3295      *
       
  3296      * <p>Two objects {@code e1} and {@code e2} are considered <i>equal</i> if,
       
  3297      * given the specified comparator, {@code cmp.compare(e1, e2) == 0}.
       
  3298      *
       
  3299      * @param a the first array to be tested for equality
       
  3300      * @param aFromIndex the index (inclusive) of the first element in the
       
  3301      *                   first array to be tested
       
  3302      * @param aToIndex the index (exclusive) of the last element in the
       
  3303      *                 first array to be tested
       
  3304      * @param b the second array to be tested fro equality
       
  3305      * @param bFromIndex the index (inclusive) of the first element in the
       
  3306      *                   second array to be tested
       
  3307      * @param bToIndex the index (exclusive) of the last element in the
       
  3308      *                 second array to be tested
       
  3309      * @param cmp the comparator to compare array elements
       
  3310      * @param <T> the type of array elements
       
  3311      * @return {@code true} if the two arrays, over the specified ranges, are
       
  3312      *         equal
       
  3313      * @throws IllegalArgumentException
       
  3314      *         if {@code aFromIndex > aToIndex} or
       
  3315      *         if {@code bFromIndex > bToIndex}
       
  3316      * @throws ArrayIndexOutOfBoundsException
       
  3317      *         if {@code aFromIndex < 0 or aToIndex > a.length} or
       
  3318      *         if {@code bFromIndex < 0 or bToIndex > b.length}
       
  3319      * @throws NullPointerException
       
  3320      *         if either array or the comparator is {@code null}
       
  3321      * @since 9
       
  3322      */
       
  3323     public static <T> boolean equals(T[] a, int aFromIndex, int aToIndex,
       
  3324                                      T[] b, int bFromIndex, int bToIndex,
       
  3325                                      Comparator<? super T> cmp) {
       
  3326         Objects.requireNonNull(cmp);
       
  3327         rangeCheck(a.length, aFromIndex, aToIndex);
       
  3328         rangeCheck(b.length, bFromIndex, bToIndex);
       
  3329 
       
  3330         int aLength = aToIndex - aFromIndex;
       
  3331         int bLength = bToIndex - bFromIndex;
       
  3332         if (aLength != bLength)
       
  3333             return false;
       
  3334 
       
  3335         for (int i = 0; i < aLength; i++) {
       
  3336             if (cmp.compare(a[aFromIndex++], b[bFromIndex++]) != 0)
       
  3337                 return false;
       
  3338         }
       
  3339 
       
  3340         return true;
       
  3341     }
       
  3342 
       
  3343     // Filling
       
  3344 
       
  3345     /**
       
  3346      * Assigns the specified long value to each element of the specified array
       
  3347      * of longs.
       
  3348      *
       
  3349      * @param a the array to be filled
       
  3350      * @param val the value to be stored in all elements of the array
       
  3351      */
       
  3352     public static void fill(long[] a, long val) {
       
  3353         for (int i = 0, len = a.length; i < len; i++)
       
  3354             a[i] = val;
       
  3355     }
       
  3356 
       
  3357     /**
       
  3358      * Assigns the specified long value to each element of the specified
       
  3359      * range of the specified array of longs.  The range to be filled
       
  3360      * extends from index {@code fromIndex}, inclusive, to index
       
  3361      * {@code toIndex}, exclusive.  (If {@code fromIndex==toIndex}, the
       
  3362      * range to be filled is empty.)
       
  3363      *
       
  3364      * @param a the array to be filled
       
  3365      * @param fromIndex the index of the first element (inclusive) to be
       
  3366      *        filled with the specified value
       
  3367      * @param toIndex the index of the last element (exclusive) to be
       
  3368      *        filled with the specified value
       
  3369      * @param val the value to be stored in all elements of the array
       
  3370      * @throws IllegalArgumentException if {@code fromIndex > toIndex}
       
  3371      * @throws ArrayIndexOutOfBoundsException if {@code fromIndex < 0} or
       
  3372      *         {@code toIndex > a.length}
       
  3373      */
       
  3374     public static void fill(long[] a, int fromIndex, int toIndex, long val) {
       
  3375         rangeCheck(a.length, fromIndex, toIndex);
       
  3376         for (int i = fromIndex; i < toIndex; i++)
       
  3377             a[i] = val;
       
  3378     }
       
  3379 
       
  3380     /**
       
  3381      * Assigns the specified int value to each element of the specified array
       
  3382      * of ints.
       
  3383      *
       
  3384      * @param a the array to be filled
       
  3385      * @param val the value to be stored in all elements of the array
       
  3386      */
       
  3387     public static void fill(int[] a, int val) {
       
  3388         for (int i = 0, len = a.length; i < len; i++)
       
  3389             a[i] = val;
       
  3390     }
       
  3391 
       
  3392     /**
       
  3393      * Assigns the specified int value to each element of the specified
       
  3394      * range of the specified array of ints.  The range to be filled
       
  3395      * extends from index {@code fromIndex}, inclusive, to index
       
  3396      * {@code toIndex}, exclusive.  (If {@code fromIndex==toIndex}, the
       
  3397      * range to be filled is empty.)
       
  3398      *
       
  3399      * @param a the array to be filled
       
  3400      * @param fromIndex the index of the first element (inclusive) to be
       
  3401      *        filled with the specified value
       
  3402      * @param toIndex the index of the last element (exclusive) to be
       
  3403      *        filled with the specified value
       
  3404      * @param val the value to be stored in all elements of the array
       
  3405      * @throws IllegalArgumentException if {@code fromIndex > toIndex}
       
  3406      * @throws ArrayIndexOutOfBoundsException if {@code fromIndex < 0} or
       
  3407      *         {@code toIndex > a.length}
       
  3408      */
       
  3409     public static void fill(int[] a, int fromIndex, int toIndex, int val) {
       
  3410         rangeCheck(a.length, fromIndex, toIndex);
       
  3411         for (int i = fromIndex; i < toIndex; i++)
       
  3412             a[i] = val;
       
  3413     }
       
  3414 
       
  3415     /**
       
  3416      * Assigns the specified short value to each element of the specified array
       
  3417      * of shorts.
       
  3418      *
       
  3419      * @param a the array to be filled
       
  3420      * @param val the value to be stored in all elements of the array
       
  3421      */
       
  3422     public static void fill(short[] a, short val) {
       
  3423         for (int i = 0, len = a.length; i < len; i++)
       
  3424             a[i] = val;
       
  3425     }
       
  3426 
       
  3427     /**
       
  3428      * Assigns the specified short value to each element of the specified
       
  3429      * range of the specified array of shorts.  The range to be filled
       
  3430      * extends from index {@code fromIndex}, inclusive, to index
       
  3431      * {@code toIndex}, exclusive.  (If {@code fromIndex==toIndex}, the
       
  3432      * range to be filled is empty.)
       
  3433      *
       
  3434      * @param a the array to be filled
       
  3435      * @param fromIndex the index of the first element (inclusive) to be
       
  3436      *        filled with the specified value
       
  3437      * @param toIndex the index of the last element (exclusive) to be
       
  3438      *        filled with the specified value
       
  3439      * @param val the value to be stored in all elements of the array
       
  3440      * @throws IllegalArgumentException if {@code fromIndex > toIndex}
       
  3441      * @throws ArrayIndexOutOfBoundsException if {@code fromIndex < 0} or
       
  3442      *         {@code toIndex > a.length}
       
  3443      */
       
  3444     public static void fill(short[] a, int fromIndex, int toIndex, short val) {
       
  3445         rangeCheck(a.length, fromIndex, toIndex);
       
  3446         for (int i = fromIndex; i < toIndex; i++)
       
  3447             a[i] = val;
       
  3448     }
       
  3449 
       
  3450     /**
       
  3451      * Assigns the specified char value to each element of the specified array
       
  3452      * of chars.
       
  3453      *
       
  3454      * @param a the array to be filled
       
  3455      * @param val the value to be stored in all elements of the array
       
  3456      */
       
  3457     public static void fill(char[] a, char val) {
       
  3458         for (int i = 0, len = a.length; i < len; i++)
       
  3459             a[i] = val;
       
  3460     }
       
  3461 
       
  3462     /**
       
  3463      * Assigns the specified char value to each element of the specified
       
  3464      * range of the specified array of chars.  The range to be filled
       
  3465      * extends from index {@code fromIndex}, inclusive, to index
       
  3466      * {@code toIndex}, exclusive.  (If {@code fromIndex==toIndex}, the
       
  3467      * range to be filled is empty.)
       
  3468      *
       
  3469      * @param a the array to be filled
       
  3470      * @param fromIndex the index of the first element (inclusive) to be
       
  3471      *        filled with the specified value
       
  3472      * @param toIndex the index of the last element (exclusive) to be
       
  3473      *        filled with the specified value
       
  3474      * @param val the value to be stored in all elements of the array
       
  3475      * @throws IllegalArgumentException if {@code fromIndex > toIndex}
       
  3476      * @throws ArrayIndexOutOfBoundsException if {@code fromIndex < 0} or
       
  3477      *         {@code toIndex > a.length}
       
  3478      */
       
  3479     public static void fill(char[] a, int fromIndex, int toIndex, char val) {
       
  3480         rangeCheck(a.length, fromIndex, toIndex);
       
  3481         for (int i = fromIndex; i < toIndex; i++)
       
  3482             a[i] = val;
       
  3483     }
       
  3484 
       
  3485     /**
       
  3486      * Assigns the specified byte value to each element of the specified array
       
  3487      * of bytes.
       
  3488      *
       
  3489      * @param a the array to be filled
       
  3490      * @param val the value to be stored in all elements of the array
       
  3491      */
       
  3492     public static void fill(byte[] a, byte val) {
       
  3493         for (int i = 0, len = a.length; i < len; i++)
       
  3494             a[i] = val;
       
  3495     }
       
  3496 
       
  3497     /**
       
  3498      * Assigns the specified byte value to each element of the specified
       
  3499      * range of the specified array of bytes.  The range to be filled
       
  3500      * extends from index {@code fromIndex}, inclusive, to index
       
  3501      * {@code toIndex}, exclusive.  (If {@code fromIndex==toIndex}, the
       
  3502      * range to be filled is empty.)
       
  3503      *
       
  3504      * @param a the array to be filled
       
  3505      * @param fromIndex the index of the first element (inclusive) to be
       
  3506      *        filled with the specified value
       
  3507      * @param toIndex the index of the last element (exclusive) to be
       
  3508      *        filled with the specified value
       
  3509      * @param val the value to be stored in all elements of the array
       
  3510      * @throws IllegalArgumentException if {@code fromIndex > toIndex}
       
  3511      * @throws ArrayIndexOutOfBoundsException if {@code fromIndex < 0} or
       
  3512      *         {@code toIndex > a.length}
       
  3513      */
       
  3514     public static void fill(byte[] a, int fromIndex, int toIndex, byte val) {
       
  3515         rangeCheck(a.length, fromIndex, toIndex);
       
  3516         for (int i = fromIndex; i < toIndex; i++)
       
  3517             a[i] = val;
       
  3518     }
       
  3519 
       
  3520     /**
       
  3521      * Assigns the specified boolean value to each element of the specified
       
  3522      * array of booleans.
       
  3523      *
       
  3524      * @param a the array to be filled
       
  3525      * @param val the value to be stored in all elements of the array
       
  3526      */
       
  3527     public static void fill(boolean[] a, boolean val) {
       
  3528         for (int i = 0, len = a.length; i < len; i++)
       
  3529             a[i] = val;
       
  3530     }
       
  3531 
       
  3532     /**
       
  3533      * Assigns the specified boolean value to each element of the specified
       
  3534      * range of the specified array of booleans.  The range to be filled
       
  3535      * extends from index {@code fromIndex}, inclusive, to index
       
  3536      * {@code toIndex}, exclusive.  (If {@code fromIndex==toIndex}, the
       
  3537      * range to be filled is empty.)
       
  3538      *
       
  3539      * @param a the array to be filled
       
  3540      * @param fromIndex the index of the first element (inclusive) to be
       
  3541      *        filled with the specified value
       
  3542      * @param toIndex the index of the last element (exclusive) to be
       
  3543      *        filled with the specified value
       
  3544      * @param val the value to be stored in all elements of the array
       
  3545      * @throws IllegalArgumentException if {@code fromIndex > toIndex}
       
  3546      * @throws ArrayIndexOutOfBoundsException if {@code fromIndex < 0} or
       
  3547      *         {@code toIndex > a.length}
       
  3548      */
       
  3549     public static void fill(boolean[] a, int fromIndex, int toIndex,
       
  3550                             boolean val) {
       
  3551         rangeCheck(a.length, fromIndex, toIndex);
       
  3552         for (int i = fromIndex; i < toIndex; i++)
       
  3553             a[i] = val;
       
  3554     }
       
  3555 
       
  3556     /**
       
  3557      * Assigns the specified double value to each element of the specified
       
  3558      * array of doubles.
       
  3559      *
       
  3560      * @param a the array to be filled
       
  3561      * @param val the value to be stored in all elements of the array
       
  3562      */
       
  3563     public static void fill(double[] a, double val) {
       
  3564         for (int i = 0, len = a.length; i < len; i++)
       
  3565             a[i] = val;
       
  3566     }
       
  3567 
       
  3568     /**
       
  3569      * Assigns the specified double value to each element of the specified
       
  3570      * range of the specified array of doubles.  The range to be filled
       
  3571      * extends from index {@code fromIndex}, inclusive, to index
       
  3572      * {@code toIndex}, exclusive.  (If {@code fromIndex==toIndex}, the
       
  3573      * range to be filled is empty.)
       
  3574      *
       
  3575      * @param a the array to be filled
       
  3576      * @param fromIndex the index of the first element (inclusive) to be
       
  3577      *        filled with the specified value
       
  3578      * @param toIndex the index of the last element (exclusive) to be
       
  3579      *        filled with the specified value
       
  3580      * @param val the value to be stored in all elements of the array
       
  3581      * @throws IllegalArgumentException if {@code fromIndex > toIndex}
       
  3582      * @throws ArrayIndexOutOfBoundsException if {@code fromIndex < 0} or
       
  3583      *         {@code toIndex > a.length}
       
  3584      */
       
  3585     public static void fill(double[] a, int fromIndex, int toIndex,double val){
       
  3586         rangeCheck(a.length, fromIndex, toIndex);
       
  3587         for (int i = fromIndex; i < toIndex; i++)
       
  3588             a[i] = val;
       
  3589     }
       
  3590 
       
  3591     /**
       
  3592      * Assigns the specified float value to each element of the specified array
       
  3593      * of floats.
       
  3594      *
       
  3595      * @param a the array to be filled
       
  3596      * @param val the value to be stored in all elements of the array
       
  3597      */
       
  3598     public static void fill(float[] a, float val) {
       
  3599         for (int i = 0, len = a.length; i < len; i++)
       
  3600             a[i] = val;
       
  3601     }
       
  3602 
       
  3603     /**
       
  3604      * Assigns the specified float value to each element of the specified
       
  3605      * range of the specified array of floats.  The range to be filled
       
  3606      * extends from index {@code fromIndex}, inclusive, to index
       
  3607      * {@code toIndex}, exclusive.  (If {@code fromIndex==toIndex}, the
       
  3608      * range to be filled is empty.)
       
  3609      *
       
  3610      * @param a the array to be filled
       
  3611      * @param fromIndex the index of the first element (inclusive) to be
       
  3612      *        filled with the specified value
       
  3613      * @param toIndex the index of the last element (exclusive) to be
       
  3614      *        filled with the specified value
       
  3615      * @param val the value to be stored in all elements of the array
       
  3616      * @throws IllegalArgumentException if {@code fromIndex > toIndex}
       
  3617      * @throws ArrayIndexOutOfBoundsException if {@code fromIndex < 0} or
       
  3618      *         {@code toIndex > a.length}
       
  3619      */
       
  3620     public static void fill(float[] a, int fromIndex, int toIndex, float val) {
       
  3621         rangeCheck(a.length, fromIndex, toIndex);
       
  3622         for (int i = fromIndex; i < toIndex; i++)
       
  3623             a[i] = val;
       
  3624     }
       
  3625 
       
  3626     /**
       
  3627      * Assigns the specified Object reference to each element of the specified
       
  3628      * array of Objects.
       
  3629      *
       
  3630      * @param a the array to be filled
       
  3631      * @param val the value to be stored in all elements of the array
       
  3632      * @throws ArrayStoreException if the specified value is not of a
       
  3633      *         runtime type that can be stored in the specified array
       
  3634      */
       
  3635     public static void fill(Object[] a, Object val) {
       
  3636         for (int i = 0, len = a.length; i < len; i++)
       
  3637             a[i] = val;
       
  3638     }
       
  3639 
       
  3640     /**
       
  3641      * Assigns the specified Object reference to each element of the specified
       
  3642      * range of the specified array of Objects.  The range to be filled
       
  3643      * extends from index {@code fromIndex}, inclusive, to index
       
  3644      * {@code toIndex}, exclusive.  (If {@code fromIndex==toIndex}, the
       
  3645      * range to be filled is empty.)
       
  3646      *
       
  3647      * @param a the array to be filled
       
  3648      * @param fromIndex the index of the first element (inclusive) to be
       
  3649      *        filled with the specified value
       
  3650      * @param toIndex the index of the last element (exclusive) to be
       
  3651      *        filled with the specified value
       
  3652      * @param val the value to be stored in all elements of the array
       
  3653      * @throws IllegalArgumentException if {@code fromIndex > toIndex}
       
  3654      * @throws ArrayIndexOutOfBoundsException if {@code fromIndex < 0} or
       
  3655      *         {@code toIndex > a.length}
       
  3656      * @throws ArrayStoreException if the specified value is not of a
       
  3657      *         runtime type that can be stored in the specified array
       
  3658      */
       
  3659     public static void fill(Object[] a, int fromIndex, int toIndex, Object val) {
       
  3660         rangeCheck(a.length, fromIndex, toIndex);
       
  3661         for (int i = fromIndex; i < toIndex; i++)
       
  3662             a[i] = val;
       
  3663     }
       
  3664 
       
  3665     // Cloning
       
  3666 
       
  3667     /**
       
  3668      * Copies the specified array, truncating or padding with nulls (if necessary)
       
  3669      * so the copy has the specified length.  For all indices that are
       
  3670      * valid in both the original array and the copy, the two arrays will
       
  3671      * contain identical values.  For any indices that are valid in the
       
  3672      * copy but not the original, the copy will contain {@code null}.
       
  3673      * Such indices will exist if and only if the specified length
       
  3674      * is greater than that of the original array.
       
  3675      * The resulting array is of exactly the same class as the original array.
       
  3676      *
       
  3677      * @param <T> the class of the objects in the array
       
  3678      * @param original the array to be copied
       
  3679      * @param newLength the length of the copy to be returned
       
  3680      * @return a copy of the original array, truncated or padded with nulls
       
  3681      *     to obtain the specified length
       
  3682      * @throws NegativeArraySizeException if {@code newLength} is negative
       
  3683      * @throws NullPointerException if {@code original} is null
       
  3684      * @since 1.6
       
  3685      */
       
  3686     @SuppressWarnings("unchecked")
       
  3687     public static <T> T[] copyOf(T[] original, int newLength) {
       
  3688         return (T[]) copyOf(original, newLength, original.getClass());
       
  3689     }
       
  3690 
       
  3691     /**
       
  3692      * Copies the specified array, truncating or padding with nulls (if necessary)
       
  3693      * so the copy has the specified length.  For all indices that are
       
  3694      * valid in both the original array and the copy, the two arrays will
       
  3695      * contain identical values.  For any indices that are valid in the
       
  3696      * copy but not the original, the copy will contain {@code null}.
       
  3697      * Such indices will exist if and only if the specified length
       
  3698      * is greater than that of the original array.
       
  3699      * The resulting array is of the class {@code newType}.
       
  3700      *
       
  3701      * @param <U> the class of the objects in the original array
       
  3702      * @param <T> the class of the objects in the returned array
       
  3703      * @param original the array to be copied
       
  3704      * @param newLength the length of the copy to be returned
       
  3705      * @param newType the class of the copy to be returned
       
  3706      * @return a copy of the original array, truncated or padded with nulls
       
  3707      *     to obtain the specified length
       
  3708      * @throws NegativeArraySizeException if {@code newLength} is negative
       
  3709      * @throws NullPointerException if {@code original} is null
       
  3710      * @throws ArrayStoreException if an element copied from
       
  3711      *     {@code original} is not of a runtime type that can be stored in
       
  3712      *     an array of class {@code newType}
       
  3713      * @since 1.6
       
  3714      */
       
  3715     @HotSpotIntrinsicCandidate
       
  3716     public static <T,U> T[] copyOf(U[] original, int newLength, Class<? extends T[]> newType) {
       
  3717         @SuppressWarnings("unchecked")
       
  3718         T[] copy = ((Object)newType == (Object)Object[].class)
       
  3719             ? (T[]) new Object[newLength]
       
  3720             : (T[]) Array.newInstance(newType.getComponentType(), newLength);
       
  3721         System.arraycopy(original, 0, copy, 0,
       
  3722                          Math.min(original.length, newLength));
       
  3723         return copy;
       
  3724     }
       
  3725 
       
  3726     /**
       
  3727      * Copies the specified array, truncating or padding with zeros (if necessary)
       
  3728      * so the copy has the specified length.  For all indices that are
       
  3729      * valid in both the original array and the copy, the two arrays will
       
  3730      * contain identical values.  For any indices that are valid in the
       
  3731      * copy but not the original, the copy will contain {@code (byte)0}.
       
  3732      * Such indices will exist if and only if the specified length
       
  3733      * is greater than that of the original array.
       
  3734      *
       
  3735      * @param original the array to be copied
       
  3736      * @param newLength the length of the copy to be returned
       
  3737      * @return a copy of the original array, truncated or padded with zeros
       
  3738      *     to obtain the specified length
       
  3739      * @throws NegativeArraySizeException if {@code newLength} is negative
       
  3740      * @throws NullPointerException if {@code original} is null
       
  3741      * @since 1.6
       
  3742      */
       
  3743     public static byte[] copyOf(byte[] original, int newLength) {
       
  3744         byte[] copy = new byte[newLength];
       
  3745         System.arraycopy(original, 0, copy, 0,
       
  3746                          Math.min(original.length, newLength));
       
  3747         return copy;
       
  3748     }
       
  3749 
       
  3750     /**
       
  3751      * Copies the specified array, truncating or padding with zeros (if necessary)
       
  3752      * so the copy has the specified length.  For all indices that are
       
  3753      * valid in both the original array and the copy, the two arrays will
       
  3754      * contain identical values.  For any indices that are valid in the
       
  3755      * copy but not the original, the copy will contain {@code (short)0}.
       
  3756      * Such indices will exist if and only if the specified length
       
  3757      * is greater than that of the original array.
       
  3758      *
       
  3759      * @param original the array to be copied
       
  3760      * @param newLength the length of the copy to be returned
       
  3761      * @return a copy of the original array, truncated or padded with zeros
       
  3762      *     to obtain the specified length
       
  3763      * @throws NegativeArraySizeException if {@code newLength} is negative
       
  3764      * @throws NullPointerException if {@code original} is null
       
  3765      * @since 1.6
       
  3766      */
       
  3767     public static short[] copyOf(short[] original, int newLength) {
       
  3768         short[] copy = new short[newLength];
       
  3769         System.arraycopy(original, 0, copy, 0,
       
  3770                          Math.min(original.length, newLength));
       
  3771         return copy;
       
  3772     }
       
  3773 
       
  3774     /**
       
  3775      * Copies the specified array, truncating or padding with zeros (if necessary)
       
  3776      * so the copy has the specified length.  For all indices that are
       
  3777      * valid in both the original array and the copy, the two arrays will
       
  3778      * contain identical values.  For any indices that are valid in the
       
  3779      * copy but not the original, the copy will contain {@code 0}.
       
  3780      * Such indices will exist if and only if the specified length
       
  3781      * is greater than that of the original array.
       
  3782      *
       
  3783      * @param original the array to be copied
       
  3784      * @param newLength the length of the copy to be returned
       
  3785      * @return a copy of the original array, truncated or padded with zeros
       
  3786      *     to obtain the specified length
       
  3787      * @throws NegativeArraySizeException if {@code newLength} is negative
       
  3788      * @throws NullPointerException if {@code original} is null
       
  3789      * @since 1.6
       
  3790      */
       
  3791     public static int[] copyOf(int[] original, int newLength) {
       
  3792         int[] copy = new int[newLength];
       
  3793         System.arraycopy(original, 0, copy, 0,
       
  3794                          Math.min(original.length, newLength));
       
  3795         return copy;
       
  3796     }
       
  3797 
       
  3798     /**
       
  3799      * Copies the specified array, truncating or padding with zeros (if necessary)
       
  3800      * so the copy has the specified length.  For all indices that are
       
  3801      * valid in both the original array and the copy, the two arrays will
       
  3802      * contain identical values.  For any indices that are valid in the
       
  3803      * copy but not the original, the copy will contain {@code 0L}.
       
  3804      * Such indices will exist if and only if the specified length
       
  3805      * is greater than that of the original array.
       
  3806      *
       
  3807      * @param original the array to be copied
       
  3808      * @param newLength the length of the copy to be returned
       
  3809      * @return a copy of the original array, truncated or padded with zeros
       
  3810      *     to obtain the specified length
       
  3811      * @throws NegativeArraySizeException if {@code newLength} is negative
       
  3812      * @throws NullPointerException if {@code original} is null
       
  3813      * @since 1.6
       
  3814      */
       
  3815     public static long[] copyOf(long[] original, int newLength) {
       
  3816         long[] copy = new long[newLength];
       
  3817         System.arraycopy(original, 0, copy, 0,
       
  3818                          Math.min(original.length, newLength));
       
  3819         return copy;
       
  3820     }
       
  3821 
       
  3822     /**
       
  3823      * Copies the specified array, truncating or padding with null characters (if necessary)
       
  3824      * so the copy has the specified length.  For all indices that are valid
       
  3825      * in both the original array and the copy, the two arrays will contain
       
  3826      * identical values.  For any indices that are valid in the copy but not
       
  3827      * the original, the copy will contain {@code '\\u000'}.  Such indices
       
  3828      * will exist if and only if the specified length is greater than that of
       
  3829      * the original array.
       
  3830      *
       
  3831      * @param original the array to be copied
       
  3832      * @param newLength the length of the copy to be returned
       
  3833      * @return a copy of the original array, truncated or padded with null characters
       
  3834      *     to obtain the specified length
       
  3835      * @throws NegativeArraySizeException if {@code newLength} is negative
       
  3836      * @throws NullPointerException if {@code original} is null
       
  3837      * @since 1.6
       
  3838      */
       
  3839     public static char[] copyOf(char[] original, int newLength) {
       
  3840         char[] copy = new char[newLength];
       
  3841         System.arraycopy(original, 0, copy, 0,
       
  3842                          Math.min(original.length, newLength));
       
  3843         return copy;
       
  3844     }
       
  3845 
       
  3846     /**
       
  3847      * Copies the specified array, truncating or padding with zeros (if necessary)
       
  3848      * so the copy has the specified length.  For all indices that are
       
  3849      * valid in both the original array and the copy, the two arrays will
       
  3850      * contain identical values.  For any indices that are valid in the
       
  3851      * copy but not the original, the copy will contain {@code 0f}.
       
  3852      * Such indices will exist if and only if the specified length
       
  3853      * is greater than that of the original array.
       
  3854      *
       
  3855      * @param original the array to be copied
       
  3856      * @param newLength the length of the copy to be returned
       
  3857      * @return a copy of the original array, truncated or padded with zeros
       
  3858      *     to obtain the specified length
       
  3859      * @throws NegativeArraySizeException if {@code newLength} is negative
       
  3860      * @throws NullPointerException if {@code original} is null
       
  3861      * @since 1.6
       
  3862      */
       
  3863     public static float[] copyOf(float[] original, int newLength) {
       
  3864         float[] copy = new float[newLength];
       
  3865         System.arraycopy(original, 0, copy, 0,
       
  3866                          Math.min(original.length, newLength));
       
  3867         return copy;
       
  3868     }
       
  3869 
       
  3870     /**
       
  3871      * Copies the specified array, truncating or padding with zeros (if necessary)
       
  3872      * so the copy has the specified length.  For all indices that are
       
  3873      * valid in both the original array and the copy, the two arrays will
       
  3874      * contain identical values.  For any indices that are valid in the
       
  3875      * copy but not the original, the copy will contain {@code 0d}.
       
  3876      * Such indices will exist if and only if the specified length
       
  3877      * is greater than that of the original array.
       
  3878      *
       
  3879      * @param original the array to be copied
       
  3880      * @param newLength the length of the copy to be returned
       
  3881      * @return a copy of the original array, truncated or padded with zeros
       
  3882      *     to obtain the specified length
       
  3883      * @throws NegativeArraySizeException if {@code newLength} is negative
       
  3884      * @throws NullPointerException if {@code original} is null
       
  3885      * @since 1.6
       
  3886      */
       
  3887     public static double[] copyOf(double[] original, int newLength) {
       
  3888         double[] copy = new double[newLength];
       
  3889         System.arraycopy(original, 0, copy, 0,
       
  3890                          Math.min(original.length, newLength));
       
  3891         return copy;
       
  3892     }
       
  3893 
       
  3894     /**
       
  3895      * Copies the specified array, truncating or padding with {@code false} (if necessary)
       
  3896      * so the copy has the specified length.  For all indices that are
       
  3897      * valid in both the original array and the copy, the two arrays will
       
  3898      * contain identical values.  For any indices that are valid in the
       
  3899      * copy but not the original, the copy will contain {@code false}.
       
  3900      * Such indices will exist if and only if the specified length
       
  3901      * is greater than that of the original array.
       
  3902      *
       
  3903      * @param original the array to be copied
       
  3904      * @param newLength the length of the copy to be returned
       
  3905      * @return a copy of the original array, truncated or padded with false elements
       
  3906      *     to obtain the specified length
       
  3907      * @throws NegativeArraySizeException if {@code newLength} is negative
       
  3908      * @throws NullPointerException if {@code original} is null
       
  3909      * @since 1.6
       
  3910      */
       
  3911     public static boolean[] copyOf(boolean[] original, int newLength) {
       
  3912         boolean[] copy = new boolean[newLength];
       
  3913         System.arraycopy(original, 0, copy, 0,
       
  3914                          Math.min(original.length, newLength));
       
  3915         return copy;
       
  3916     }
       
  3917 
       
  3918     /**
       
  3919      * Copies the specified range of the specified array into a new array.
       
  3920      * The initial index of the range ({@code from}) must lie between zero
       
  3921      * and {@code original.length}, inclusive.  The value at
       
  3922      * {@code original[from]} is placed into the initial element of the copy
       
  3923      * (unless {@code from == original.length} or {@code from == to}).
       
  3924      * Values from subsequent elements in the original array are placed into
       
  3925      * subsequent elements in the copy.  The final index of the range
       
  3926      * ({@code to}), which must be greater than or equal to {@code from},
       
  3927      * may be greater than {@code original.length}, in which case
       
  3928      * {@code null} is placed in all elements of the copy whose index is
       
  3929      * greater than or equal to {@code original.length - from}.  The length
       
  3930      * of the returned array will be {@code to - from}.
       
  3931      * <p>
       
  3932      * The resulting array is of exactly the same class as the original array.
       
  3933      *
       
  3934      * @param <T> the class of the objects in the array
       
  3935      * @param original the array from which a range is to be copied
       
  3936      * @param from the initial index of the range to be copied, inclusive
       
  3937      * @param to the final index of the range to be copied, exclusive.
       
  3938      *     (This index may lie outside the array.)
       
  3939      * @return a new array containing the specified range from the original array,
       
  3940      *     truncated or padded with nulls to obtain the required length
       
  3941      * @throws ArrayIndexOutOfBoundsException if {@code from < 0}
       
  3942      *     or {@code from > original.length}
       
  3943      * @throws IllegalArgumentException if {@code from > to}
       
  3944      * @throws NullPointerException if {@code original} is null
       
  3945      * @since 1.6
       
  3946      */
       
  3947     @SuppressWarnings("unchecked")
       
  3948     public static <T> T[] copyOfRange(T[] original, int from, int to) {
       
  3949         return copyOfRange(original, from, to, (Class<? extends T[]>) original.getClass());
       
  3950     }
       
  3951 
       
  3952     /**
       
  3953      * Copies the specified range of the specified array into a new array.
       
  3954      * The initial index of the range ({@code from}) must lie between zero
       
  3955      * and {@code original.length}, inclusive.  The value at
       
  3956      * {@code original[from]} is placed into the initial element of the copy
       
  3957      * (unless {@code from == original.length} or {@code from == to}).
       
  3958      * Values from subsequent elements in the original array are placed into
       
  3959      * subsequent elements in the copy.  The final index of the range
       
  3960      * ({@code to}), which must be greater than or equal to {@code from},
       
  3961      * may be greater than {@code original.length}, in which case
       
  3962      * {@code null} is placed in all elements of the copy whose index is
       
  3963      * greater than or equal to {@code original.length - from}.  The length
       
  3964      * of the returned array will be {@code to - from}.
       
  3965      * The resulting array is of the class {@code newType}.
       
  3966      *
       
  3967      * @param <U> the class of the objects in the original array
       
  3968      * @param <T> the class of the objects in the returned array
       
  3969      * @param original the array from which a range is to be copied
       
  3970      * @param from the initial index of the range to be copied, inclusive
       
  3971      * @param to the final index of the range to be copied, exclusive.
       
  3972      *     (This index may lie outside the array.)
       
  3973      * @param newType the class of the copy to be returned
       
  3974      * @return a new array containing the specified range from the original array,
       
  3975      *     truncated or padded with nulls to obtain the required length
       
  3976      * @throws ArrayIndexOutOfBoundsException if {@code from < 0}
       
  3977      *     or {@code from > original.length}
       
  3978      * @throws IllegalArgumentException if {@code from > to}
       
  3979      * @throws NullPointerException if {@code original} is null
       
  3980      * @throws ArrayStoreException if an element copied from
       
  3981      *     {@code original} is not of a runtime type that can be stored in
       
  3982      *     an array of class {@code newType}.
       
  3983      * @since 1.6
       
  3984      */
       
  3985     @HotSpotIntrinsicCandidate
       
  3986     public static <T,U> T[] copyOfRange(U[] original, int from, int to, Class<? extends T[]> newType) {
       
  3987         int newLength = to - from;
       
  3988         if (newLength < 0)
       
  3989             throw new IllegalArgumentException(from + " > " + to);
       
  3990         @SuppressWarnings("unchecked")
       
  3991         T[] copy = ((Object)newType == (Object)Object[].class)
       
  3992             ? (T[]) new Object[newLength]
       
  3993             : (T[]) Array.newInstance(newType.getComponentType(), newLength);
       
  3994         System.arraycopy(original, from, copy, 0,
       
  3995                          Math.min(original.length - from, newLength));
       
  3996         return copy;
       
  3997     }
       
  3998 
       
  3999     /**
       
  4000      * Copies the specified range of the specified array into a new array.
       
  4001      * The initial index of the range ({@code from}) must lie between zero
       
  4002      * and {@code original.length}, inclusive.  The value at
       
  4003      * {@code original[from]} is placed into the initial element of the copy
       
  4004      * (unless {@code from == original.length} or {@code from == to}).
       
  4005      * Values from subsequent elements in the original array are placed into
       
  4006      * subsequent elements in the copy.  The final index of the range
       
  4007      * ({@code to}), which must be greater than or equal to {@code from},
       
  4008      * may be greater than {@code original.length}, in which case
       
  4009      * {@code (byte)0} is placed in all elements of the copy whose index is
       
  4010      * greater than or equal to {@code original.length - from}.  The length
       
  4011      * of the returned array will be {@code to - from}.
       
  4012      *
       
  4013      * @param original the array from which a range is to be copied
       
  4014      * @param from the initial index of the range to be copied, inclusive
       
  4015      * @param to the final index of the range to be copied, exclusive.
       
  4016      *     (This index may lie outside the array.)
       
  4017      * @return a new array containing the specified range from the original array,
       
  4018      *     truncated or padded with zeros to obtain the required length
       
  4019      * @throws ArrayIndexOutOfBoundsException if {@code from < 0}
       
  4020      *     or {@code from > original.length}
       
  4021      * @throws IllegalArgumentException if {@code from > to}
       
  4022      * @throws NullPointerException if {@code original} is null
       
  4023      * @since 1.6
       
  4024      */
       
  4025     public static byte[] copyOfRange(byte[] original, int from, int to) {
       
  4026         int newLength = to - from;
       
  4027         if (newLength < 0)
       
  4028             throw new IllegalArgumentException(from + " > " + to);
       
  4029         byte[] copy = new byte[newLength];
       
  4030         System.arraycopy(original, from, copy, 0,
       
  4031                          Math.min(original.length - from, newLength));
       
  4032         return copy;
       
  4033     }
       
  4034 
       
  4035     /**
       
  4036      * Copies the specified range of the specified array into a new array.
       
  4037      * The initial index of the range ({@code from}) must lie between zero
       
  4038      * and {@code original.length}, inclusive.  The value at
       
  4039      * {@code original[from]} is placed into the initial element of the copy
       
  4040      * (unless {@code from == original.length} or {@code from == to}).
       
  4041      * Values from subsequent elements in the original array are placed into
       
  4042      * subsequent elements in the copy.  The final index of the range
       
  4043      * ({@code to}), which must be greater than or equal to {@code from},
       
  4044      * may be greater than {@code original.length}, in which case
       
  4045      * {@code (short)0} is placed in all elements of the copy whose index is
       
  4046      * greater than or equal to {@code original.length - from}.  The length
       
  4047      * of the returned array will be {@code to - from}.
       
  4048      *
       
  4049      * @param original the array from which a range is to be copied
       
  4050      * @param from the initial index of the range to be copied, inclusive
       
  4051      * @param to the final index of the range to be copied, exclusive.
       
  4052      *     (This index may lie outside the array.)
       
  4053      * @return a new array containing the specified range from the original array,
       
  4054      *     truncated or padded with zeros to obtain the required length
       
  4055      * @throws ArrayIndexOutOfBoundsException if {@code from < 0}
       
  4056      *     or {@code from > original.length}
       
  4057      * @throws IllegalArgumentException if {@code from > to}
       
  4058      * @throws NullPointerException if {@code original} is null
       
  4059      * @since 1.6
       
  4060      */
       
  4061     public static short[] copyOfRange(short[] original, int from, int to) {
       
  4062         int newLength = to - from;
       
  4063         if (newLength < 0)
       
  4064             throw new IllegalArgumentException(from + " > " + to);
       
  4065         short[] copy = new short[newLength];
       
  4066         System.arraycopy(original, from, copy, 0,
       
  4067                          Math.min(original.length - from, newLength));
       
  4068         return copy;
       
  4069     }
       
  4070 
       
  4071     /**
       
  4072      * Copies the specified range of the specified array into a new array.
       
  4073      * The initial index of the range ({@code from}) must lie between zero
       
  4074      * and {@code original.length}, inclusive.  The value at
       
  4075      * {@code original[from]} is placed into the initial element of the copy
       
  4076      * (unless {@code from == original.length} or {@code from == to}).
       
  4077      * Values from subsequent elements in the original array are placed into
       
  4078      * subsequent elements in the copy.  The final index of the range
       
  4079      * ({@code to}), which must be greater than or equal to {@code from},
       
  4080      * may be greater than {@code original.length}, in which case
       
  4081      * {@code 0} is placed in all elements of the copy whose index is
       
  4082      * greater than or equal to {@code original.length - from}.  The length
       
  4083      * of the returned array will be {@code to - from}.
       
  4084      *
       
  4085      * @param original the array from which a range is to be copied
       
  4086      * @param from the initial index of the range to be copied, inclusive
       
  4087      * @param to the final index of the range to be copied, exclusive.
       
  4088      *     (This index may lie outside the array.)
       
  4089      * @return a new array containing the specified range from the original array,
       
  4090      *     truncated or padded with zeros to obtain the required length
       
  4091      * @throws ArrayIndexOutOfBoundsException if {@code from < 0}
       
  4092      *     or {@code from > original.length}
       
  4093      * @throws IllegalArgumentException if {@code from > to}
       
  4094      * @throws NullPointerException if {@code original} is null
       
  4095      * @since 1.6
       
  4096      */
       
  4097     public static int[] copyOfRange(int[] original, int from, int to) {
       
  4098         int newLength = to - from;
       
  4099         if (newLength < 0)
       
  4100             throw new IllegalArgumentException(from + " > " + to);
       
  4101         int[] copy = new int[newLength];
       
  4102         System.arraycopy(original, from, copy, 0,
       
  4103                          Math.min(original.length - from, newLength));
       
  4104         return copy;
       
  4105     }
       
  4106 
       
  4107     /**
       
  4108      * Copies the specified range of the specified array into a new array.
       
  4109      * The initial index of the range ({@code from}) must lie between zero
       
  4110      * and {@code original.length}, inclusive.  The value at
       
  4111      * {@code original[from]} is placed into the initial element of the copy
       
  4112      * (unless {@code from == original.length} or {@code from == to}).
       
  4113      * Values from subsequent elements in the original array are placed into
       
  4114      * subsequent elements in the copy.  The final index of the range
       
  4115      * ({@code to}), which must be greater than or equal to {@code from},
       
  4116      * may be greater than {@code original.length}, in which case
       
  4117      * {@code 0L} is placed in all elements of the copy whose index is
       
  4118      * greater than or equal to {@code original.length - from}.  The length
       
  4119      * of the returned array will be {@code to - from}.
       
  4120      *
       
  4121      * @param original the array from which a range is to be copied
       
  4122      * @param from the initial index of the range to be copied, inclusive
       
  4123      * @param to the final index of the range to be copied, exclusive.
       
  4124      *     (This index may lie outside the array.)
       
  4125      * @return a new array containing the specified range from the original array,
       
  4126      *     truncated or padded with zeros to obtain the required length
       
  4127      * @throws ArrayIndexOutOfBoundsException if {@code from < 0}
       
  4128      *     or {@code from > original.length}
       
  4129      * @throws IllegalArgumentException if {@code from > to}
       
  4130      * @throws NullPointerException if {@code original} is null
       
  4131      * @since 1.6
       
  4132      */
       
  4133     public static long[] copyOfRange(long[] original, int from, int to) {
       
  4134         int newLength = to - from;
       
  4135         if (newLength < 0)
       
  4136             throw new IllegalArgumentException(from + " > " + to);
       
  4137         long[] copy = new long[newLength];
       
  4138         System.arraycopy(original, from, copy, 0,
       
  4139                          Math.min(original.length - from, newLength));
       
  4140         return copy;
       
  4141     }
       
  4142 
       
  4143     /**
       
  4144      * Copies the specified range of the specified array into a new array.
       
  4145      * The initial index of the range ({@code from}) must lie between zero
       
  4146      * and {@code original.length}, inclusive.  The value at
       
  4147      * {@code original[from]} is placed into the initial element of the copy
       
  4148      * (unless {@code from == original.length} or {@code from == to}).
       
  4149      * Values from subsequent elements in the original array are placed into
       
  4150      * subsequent elements in the copy.  The final index of the range
       
  4151      * ({@code to}), which must be greater than or equal to {@code from},
       
  4152      * may be greater than {@code original.length}, in which case
       
  4153      * {@code '\\u000'} is placed in all elements of the copy whose index is
       
  4154      * greater than or equal to {@code original.length - from}.  The length
       
  4155      * of the returned array will be {@code to - from}.
       
  4156      *
       
  4157      * @param original the array from which a range is to be copied
       
  4158      * @param from the initial index of the range to be copied, inclusive
       
  4159      * @param to the final index of the range to be copied, exclusive.
       
  4160      *     (This index may lie outside the array.)
       
  4161      * @return a new array containing the specified range from the original array,
       
  4162      *     truncated or padded with null characters to obtain the required length
       
  4163      * @throws ArrayIndexOutOfBoundsException if {@code from < 0}
       
  4164      *     or {@code from > original.length}
       
  4165      * @throws IllegalArgumentException if {@code from > to}
       
  4166      * @throws NullPointerException if {@code original} is null
       
  4167      * @since 1.6
       
  4168      */
       
  4169     public static char[] copyOfRange(char[] original, int from, int to) {
       
  4170         int newLength = to - from;
       
  4171         if (newLength < 0)
       
  4172             throw new IllegalArgumentException(from + " > " + to);
       
  4173         char[] copy = new char[newLength];
       
  4174         System.arraycopy(original, from, copy, 0,
       
  4175                          Math.min(original.length - from, newLength));
       
  4176         return copy;
       
  4177     }
       
  4178 
       
  4179     /**
       
  4180      * Copies the specified range of the specified array into a new array.
       
  4181      * The initial index of the range ({@code from}) must lie between zero
       
  4182      * and {@code original.length}, inclusive.  The value at
       
  4183      * {@code original[from]} is placed into the initial element of the copy
       
  4184      * (unless {@code from == original.length} or {@code from == to}).
       
  4185      * Values from subsequent elements in the original array are placed into
       
  4186      * subsequent elements in the copy.  The final index of the range
       
  4187      * ({@code to}), which must be greater than or equal to {@code from},
       
  4188      * may be greater than {@code original.length}, in which case
       
  4189      * {@code 0f} is placed in all elements of the copy whose index is
       
  4190      * greater than or equal to {@code original.length - from}.  The length
       
  4191      * of the returned array will be {@code to - from}.
       
  4192      *
       
  4193      * @param original the array from which a range is to be copied
       
  4194      * @param from the initial index of the range to be copied, inclusive
       
  4195      * @param to the final index of the range to be copied, exclusive.
       
  4196      *     (This index may lie outside the array.)
       
  4197      * @return a new array containing the specified range from the original array,
       
  4198      *     truncated or padded with zeros to obtain the required length
       
  4199      * @throws ArrayIndexOutOfBoundsException if {@code from < 0}
       
  4200      *     or {@code from > original.length}
       
  4201      * @throws IllegalArgumentException if {@code from > to}
       
  4202      * @throws NullPointerException if {@code original} is null
       
  4203      * @since 1.6
       
  4204      */
       
  4205     public static float[] copyOfRange(float[] original, int from, int to) {
       
  4206         int newLength = to - from;
       
  4207         if (newLength < 0)
       
  4208             throw new IllegalArgumentException(from + " > " + to);
       
  4209         float[] copy = new float[newLength];
       
  4210         System.arraycopy(original, from, copy, 0,
       
  4211                          Math.min(original.length - from, newLength));
       
  4212         return copy;
       
  4213     }
       
  4214 
       
  4215     /**
       
  4216      * Copies the specified range of the specified array into a new array.
       
  4217      * The initial index of the range ({@code from}) must lie between zero
       
  4218      * and {@code original.length}, inclusive.  The value at
       
  4219      * {@code original[from]} is placed into the initial element of the copy
       
  4220      * (unless {@code from == original.length} or {@code from == to}).
       
  4221      * Values from subsequent elements in the original array are placed into
       
  4222      * subsequent elements in the copy.  The final index of the range
       
  4223      * ({@code to}), which must be greater than or equal to {@code from},
       
  4224      * may be greater than {@code original.length}, in which case
       
  4225      * {@code 0d} is placed in all elements of the copy whose index is
       
  4226      * greater than or equal to {@code original.length - from}.  The length
       
  4227      * of the returned array will be {@code to - from}.
       
  4228      *
       
  4229      * @param original the array from which a range is to be copied
       
  4230      * @param from the initial index of the range to be copied, inclusive
       
  4231      * @param to the final index of the range to be copied, exclusive.
       
  4232      *     (This index may lie outside the array.)
       
  4233      * @return a new array containing the specified range from the original array,
       
  4234      *     truncated or padded with zeros to obtain the required length
       
  4235      * @throws ArrayIndexOutOfBoundsException if {@code from < 0}
       
  4236      *     or {@code from > original.length}
       
  4237      * @throws IllegalArgumentException if {@code from > to}
       
  4238      * @throws NullPointerException if {@code original} is null
       
  4239      * @since 1.6
       
  4240      */
       
  4241     public static double[] copyOfRange(double[] original, int from, int to) {
       
  4242         int newLength = to - from;
       
  4243         if (newLength < 0)
       
  4244             throw new IllegalArgumentException(from + " > " + to);
       
  4245         double[] copy = new double[newLength];
       
  4246         System.arraycopy(original, from, copy, 0,
       
  4247                          Math.min(original.length - from, newLength));
       
  4248         return copy;
       
  4249     }
       
  4250 
       
  4251     /**
       
  4252      * Copies the specified range of the specified array into a new array.
       
  4253      * The initial index of the range ({@code from}) must lie between zero
       
  4254      * and {@code original.length}, inclusive.  The value at
       
  4255      * {@code original[from]} is placed into the initial element of the copy
       
  4256      * (unless {@code from == original.length} or {@code from == to}).
       
  4257      * Values from subsequent elements in the original array are placed into
       
  4258      * subsequent elements in the copy.  The final index of the range
       
  4259      * ({@code to}), which must be greater than or equal to {@code from},
       
  4260      * may be greater than {@code original.length}, in which case
       
  4261      * {@code false} is placed in all elements of the copy whose index is
       
  4262      * greater than or equal to {@code original.length - from}.  The length
       
  4263      * of the returned array will be {@code to - from}.
       
  4264      *
       
  4265      * @param original the array from which a range is to be copied
       
  4266      * @param from the initial index of the range to be copied, inclusive
       
  4267      * @param to the final index of the range to be copied, exclusive.
       
  4268      *     (This index may lie outside the array.)
       
  4269      * @return a new array containing the specified range from the original array,
       
  4270      *     truncated or padded with false elements to obtain the required length
       
  4271      * @throws ArrayIndexOutOfBoundsException if {@code from < 0}
       
  4272      *     or {@code from > original.length}
       
  4273      * @throws IllegalArgumentException if {@code from > to}
       
  4274      * @throws NullPointerException if {@code original} is null
       
  4275      * @since 1.6
       
  4276      */
       
  4277     public static boolean[] copyOfRange(boolean[] original, int from, int to) {
       
  4278         int newLength = to - from;
       
  4279         if (newLength < 0)
       
  4280             throw new IllegalArgumentException(from + " > " + to);
       
  4281         boolean[] copy = new boolean[newLength];
       
  4282         System.arraycopy(original, from, copy, 0,
       
  4283                          Math.min(original.length - from, newLength));
       
  4284         return copy;
       
  4285     }
       
  4286 
       
  4287     // Misc
       
  4288 
       
  4289     /**
       
  4290      * Returns a fixed-size list backed by the specified array.  (Changes to
       
  4291      * the returned list "write through" to the array.)  This method acts
       
  4292      * as bridge between array-based and collection-based APIs, in
       
  4293      * combination with {@link Collection#toArray}.  The returned list is
       
  4294      * serializable and implements {@link RandomAccess}.
       
  4295      *
       
  4296      * <p>This method also provides a convenient way to create a fixed-size
       
  4297      * list initialized to contain several elements:
       
  4298      * <pre>
       
  4299      *     List&lt;String&gt; stooges = Arrays.asList("Larry", "Moe", "Curly");
       
  4300      * </pre>
       
  4301      *
       
  4302      * @param <T> the class of the objects in the array
       
  4303      * @param a the array by which the list will be backed
       
  4304      * @return a list view of the specified array
       
  4305      */
       
  4306     @SafeVarargs
       
  4307     @SuppressWarnings("varargs")
       
  4308     public static <T> List<T> asList(T... a) {
       
  4309         return new ArrayList<>(a);
       
  4310     }
       
  4311 
       
  4312     /**
       
  4313      * @serial include
       
  4314      */
       
  4315     private static class ArrayList<E> extends AbstractList<E>
       
  4316         implements RandomAccess, java.io.Serializable
       
  4317     {
       
  4318         private static final long serialVersionUID = -2764017481108945198L;
       
  4319         private final E[] a;
       
  4320 
       
  4321         ArrayList(E[] array) {
       
  4322             a = Objects.requireNonNull(array);
       
  4323         }
       
  4324 
       
  4325         @Override
       
  4326         public int size() {
       
  4327             return a.length;
       
  4328         }
       
  4329 
       
  4330         @Override
       
  4331         public Object[] toArray() {
       
  4332             return Arrays.copyOf(a, a.length, Object[].class);
       
  4333         }
       
  4334 
       
  4335         @Override
       
  4336         @SuppressWarnings("unchecked")
       
  4337         public <T> T[] toArray(T[] a) {
       
  4338             int size = size();
       
  4339             if (a.length < size)
       
  4340                 return Arrays.copyOf(this.a, size,
       
  4341                                      (Class<? extends T[]>) a.getClass());
       
  4342             System.arraycopy(this.a, 0, a, 0, size);
       
  4343             if (a.length > size)
       
  4344                 a[size] = null;
       
  4345             return a;
       
  4346         }
       
  4347 
       
  4348         @Override
       
  4349         public E get(int index) {
       
  4350             return a[index];
       
  4351         }
       
  4352 
       
  4353         @Override
       
  4354         public E set(int index, E element) {
       
  4355             E oldValue = a[index];
       
  4356             a[index] = element;
       
  4357             return oldValue;
       
  4358         }
       
  4359 
       
  4360         @Override
       
  4361         public int indexOf(Object o) {
       
  4362             E[] a = this.a;
       
  4363             if (o == null) {
       
  4364                 for (int i = 0; i < a.length; i++)
       
  4365                     if (a[i] == null)
       
  4366                         return i;
       
  4367             } else {
       
  4368                 for (int i = 0; i < a.length; i++)
       
  4369                     if (o.equals(a[i]))
       
  4370                         return i;
       
  4371             }
       
  4372             return -1;
       
  4373         }
       
  4374 
       
  4375         @Override
       
  4376         public boolean contains(Object o) {
       
  4377             return indexOf(o) >= 0;
       
  4378         }
       
  4379 
       
  4380         @Override
       
  4381         public Spliterator<E> spliterator() {
       
  4382             return Spliterators.spliterator(a, Spliterator.ORDERED);
       
  4383         }
       
  4384 
       
  4385         @Override
       
  4386         public void forEach(Consumer<? super E> action) {
       
  4387             Objects.requireNonNull(action);
       
  4388             for (E e : a) {
       
  4389                 action.accept(e);
       
  4390             }
       
  4391         }
       
  4392 
       
  4393         @Override
       
  4394         public void replaceAll(UnaryOperator<E> operator) {
       
  4395             Objects.requireNonNull(operator);
       
  4396             E[] a = this.a;
       
  4397             for (int i = 0; i < a.length; i++) {
       
  4398                 a[i] = operator.apply(a[i]);
       
  4399             }
       
  4400         }
       
  4401 
       
  4402         @Override
       
  4403         public void sort(Comparator<? super E> c) {
       
  4404             Arrays.sort(a, c);
       
  4405         }
       
  4406 
       
  4407         @Override
       
  4408         public Iterator<E> iterator() {
       
  4409             return new ArrayItr<>(a);
       
  4410         }
       
  4411     }
       
  4412 
       
  4413     private static class ArrayItr<E> implements Iterator<E> {
       
  4414         private int cursor;
       
  4415         private final E[] a;
       
  4416 
       
  4417         ArrayItr(E[] a) {
       
  4418             this.a = a;
       
  4419         }
       
  4420 
       
  4421         @Override
       
  4422         public boolean hasNext() {
       
  4423             return cursor < a.length;
       
  4424         }
       
  4425 
       
  4426         @Override
       
  4427         public E next() {
       
  4428             int i = cursor;
       
  4429             if (i >= a.length) {
       
  4430                 throw new NoSuchElementException();
       
  4431             }
       
  4432             cursor = i + 1;
       
  4433             return a[i];
       
  4434         }
       
  4435     }
       
  4436 
       
  4437     /**
       
  4438      * Returns a hash code based on the contents of the specified array.
       
  4439      * For any two {@code long} arrays {@code a} and {@code b}
       
  4440      * such that {@code Arrays.equals(a, b)}, it is also the case that
       
  4441      * {@code Arrays.hashCode(a) == Arrays.hashCode(b)}.
       
  4442      *
       
  4443      * <p>The value returned by this method is the same value that would be
       
  4444      * obtained by invoking the {@link List#hashCode() hashCode}
       
  4445      * method on a {@link List} containing a sequence of {@link Long}
       
  4446      * instances representing the elements of {@code a} in the same order.
       
  4447      * If {@code a} is {@code null}, this method returns 0.
       
  4448      *
       
  4449      * @param a the array whose hash value to compute
       
  4450      * @return a content-based hash code for {@code a}
       
  4451      * @since 1.5
       
  4452      */
       
  4453     public static int hashCode(long a[]) {
       
  4454         if (a == null)
       
  4455             return 0;
       
  4456 
       
  4457         int result = 1;
       
  4458         for (long element : a) {
       
  4459             int elementHash = (int)(element ^ (element >>> 32));
       
  4460             result = 31 * result + elementHash;
       
  4461         }
       
  4462 
       
  4463         return result;
       
  4464     }
       
  4465 
       
  4466     /**
       
  4467      * Returns a hash code based on the contents of the specified array.
       
  4468      * For any two non-null {@code int} arrays {@code a} and {@code b}
       
  4469      * such that {@code Arrays.equals(a, b)}, it is also the case that
       
  4470      * {@code Arrays.hashCode(a) == Arrays.hashCode(b)}.
       
  4471      *
       
  4472      * <p>The value returned by this method is the same value that would be
       
  4473      * obtained by invoking the {@link List#hashCode() hashCode}
       
  4474      * method on a {@link List} containing a sequence of {@link Integer}
       
  4475      * instances representing the elements of {@code a} in the same order.
       
  4476      * If {@code a} is {@code null}, this method returns 0.
       
  4477      *
       
  4478      * @param a the array whose hash value to compute
       
  4479      * @return a content-based hash code for {@code a}
       
  4480      * @since 1.5
       
  4481      */
       
  4482     public static int hashCode(int a[]) {
       
  4483         if (a == null)
       
  4484             return 0;
       
  4485 
       
  4486         int result = 1;
       
  4487         for (int element : a)
       
  4488             result = 31 * result + element;
       
  4489 
       
  4490         return result;
       
  4491     }
       
  4492 
       
  4493     /**
       
  4494      * Returns a hash code based on the contents of the specified array.
       
  4495      * For any two {@code short} arrays {@code a} and {@code b}
       
  4496      * such that {@code Arrays.equals(a, b)}, it is also the case that
       
  4497      * {@code Arrays.hashCode(a) == Arrays.hashCode(b)}.
       
  4498      *
       
  4499      * <p>The value returned by this method is the same value that would be
       
  4500      * obtained by invoking the {@link List#hashCode() hashCode}
       
  4501      * method on a {@link List} containing a sequence of {@link Short}
       
  4502      * instances representing the elements of {@code a} in the same order.
       
  4503      * If {@code a} is {@code null}, this method returns 0.
       
  4504      *
       
  4505      * @param a the array whose hash value to compute
       
  4506      * @return a content-based hash code for {@code a}
       
  4507      * @since 1.5
       
  4508      */
       
  4509     public static int hashCode(short a[]) {
       
  4510         if (a == null)
       
  4511             return 0;
       
  4512 
       
  4513         int result = 1;
       
  4514         for (short element : a)
       
  4515             result = 31 * result + element;
       
  4516 
       
  4517         return result;
       
  4518     }
       
  4519 
       
  4520     /**
       
  4521      * Returns a hash code based on the contents of the specified array.
       
  4522      * For any two {@code char} arrays {@code a} and {@code b}
       
  4523      * such that {@code Arrays.equals(a, b)}, it is also the case that
       
  4524      * {@code Arrays.hashCode(a) == Arrays.hashCode(b)}.
       
  4525      *
       
  4526      * <p>The value returned by this method is the same value that would be
       
  4527      * obtained by invoking the {@link List#hashCode() hashCode}
       
  4528      * method on a {@link List} containing a sequence of {@link Character}
       
  4529      * instances representing the elements of {@code a} in the same order.
       
  4530      * If {@code a} is {@code null}, this method returns 0.
       
  4531      *
       
  4532      * @param a the array whose hash value to compute
       
  4533      * @return a content-based hash code for {@code a}
       
  4534      * @since 1.5
       
  4535      */
       
  4536     public static int hashCode(char a[]) {
       
  4537         if (a == null)
       
  4538             return 0;
       
  4539 
       
  4540         int result = 1;
       
  4541         for (char element : a)
       
  4542             result = 31 * result + element;
       
  4543 
       
  4544         return result;
       
  4545     }
       
  4546 
       
  4547     /**
       
  4548      * Returns a hash code based on the contents of the specified array.
       
  4549      * For any two {@code byte} arrays {@code a} and {@code b}
       
  4550      * such that {@code Arrays.equals(a, b)}, it is also the case that
       
  4551      * {@code Arrays.hashCode(a) == Arrays.hashCode(b)}.
       
  4552      *
       
  4553      * <p>The value returned by this method is the same value that would be
       
  4554      * obtained by invoking the {@link List#hashCode() hashCode}
       
  4555      * method on a {@link List} containing a sequence of {@link Byte}
       
  4556      * instances representing the elements of {@code a} in the same order.
       
  4557      * If {@code a} is {@code null}, this method returns 0.
       
  4558      *
       
  4559      * @param a the array whose hash value to compute
       
  4560      * @return a content-based hash code for {@code a}
       
  4561      * @since 1.5
       
  4562      */
       
  4563     public static int hashCode(byte a[]) {
       
  4564         if (a == null)
       
  4565             return 0;
       
  4566 
       
  4567         int result = 1;
       
  4568         for (byte element : a)
       
  4569             result = 31 * result + element;
       
  4570 
       
  4571         return result;
       
  4572     }
       
  4573 
       
  4574     /**
       
  4575      * Returns a hash code based on the contents of the specified array.
       
  4576      * For any two {@code boolean} arrays {@code a} and {@code b}
       
  4577      * such that {@code Arrays.equals(a, b)}, it is also the case that
       
  4578      * {@code Arrays.hashCode(a) == Arrays.hashCode(b)}.
       
  4579      *
       
  4580      * <p>The value returned by this method is the same value that would be
       
  4581      * obtained by invoking the {@link List#hashCode() hashCode}
       
  4582      * method on a {@link List} containing a sequence of {@link Boolean}
       
  4583      * instances representing the elements of {@code a} in the same order.
       
  4584      * If {@code a} is {@code null}, this method returns 0.
       
  4585      *
       
  4586      * @param a the array whose hash value to compute
       
  4587      * @return a content-based hash code for {@code a}
       
  4588      * @since 1.5
       
  4589      */
       
  4590     public static int hashCode(boolean a[]) {
       
  4591         if (a == null)
       
  4592             return 0;
       
  4593 
       
  4594         int result = 1;
       
  4595         for (boolean element : a)
       
  4596             result = 31 * result + (element ? 1231 : 1237);
       
  4597 
       
  4598         return result;
       
  4599     }
       
  4600 
       
  4601     /**
       
  4602      * Returns a hash code based on the contents of the specified array.
       
  4603      * For any two {@code float} arrays {@code a} and {@code b}
       
  4604      * such that {@code Arrays.equals(a, b)}, it is also the case that
       
  4605      * {@code Arrays.hashCode(a) == Arrays.hashCode(b)}.
       
  4606      *
       
  4607      * <p>The value returned by this method is the same value that would be
       
  4608      * obtained by invoking the {@link List#hashCode() hashCode}
       
  4609      * method on a {@link List} containing a sequence of {@link Float}
       
  4610      * instances representing the elements of {@code a} in the same order.
       
  4611      * If {@code a} is {@code null}, this method returns 0.
       
  4612      *
       
  4613      * @param a the array whose hash value to compute
       
  4614      * @return a content-based hash code for {@code a}
       
  4615      * @since 1.5
       
  4616      */
       
  4617     public static int hashCode(float a[]) {
       
  4618         if (a == null)
       
  4619             return 0;
       
  4620 
       
  4621         int result = 1;
       
  4622         for (float element : a)
       
  4623             result = 31 * result + Float.floatToIntBits(element);
       
  4624 
       
  4625         return result;
       
  4626     }
       
  4627 
       
  4628     /**
       
  4629      * Returns a hash code based on the contents of the specified array.
       
  4630      * For any two {@code double} arrays {@code a} and {@code b}
       
  4631      * such that {@code Arrays.equals(a, b)}, it is also the case that
       
  4632      * {@code Arrays.hashCode(a) == Arrays.hashCode(b)}.
       
  4633      *
       
  4634      * <p>The value returned by this method is the same value that would be
       
  4635      * obtained by invoking the {@link List#hashCode() hashCode}
       
  4636      * method on a {@link List} containing a sequence of {@link Double}
       
  4637      * instances representing the elements of {@code a} in the same order.
       
  4638      * If {@code a} is {@code null}, this method returns 0.
       
  4639      *
       
  4640      * @param a the array whose hash value to compute
       
  4641      * @return a content-based hash code for {@code a}
       
  4642      * @since 1.5
       
  4643      */
       
  4644     public static int hashCode(double a[]) {
       
  4645         if (a == null)
       
  4646             return 0;
       
  4647 
       
  4648         int result = 1;
       
  4649         for (double element : a) {
       
  4650             long bits = Double.doubleToLongBits(element);
       
  4651             result = 31 * result + (int)(bits ^ (bits >>> 32));
       
  4652         }
       
  4653         return result;
       
  4654     }
       
  4655 
       
  4656     /**
       
  4657      * Returns a hash code based on the contents of the specified array.  If
       
  4658      * the array contains other arrays as elements, the hash code is based on
       
  4659      * their identities rather than their contents.  It is therefore
       
  4660      * acceptable to invoke this method on an array that contains itself as an
       
  4661      * element,  either directly or indirectly through one or more levels of
       
  4662      * arrays.
       
  4663      *
       
  4664      * <p>For any two arrays {@code a} and {@code b} such that
       
  4665      * {@code Arrays.equals(a, b)}, it is also the case that
       
  4666      * {@code Arrays.hashCode(a) == Arrays.hashCode(b)}.
       
  4667      *
       
  4668      * <p>The value returned by this method is equal to the value that would
       
  4669      * be returned by {@code Arrays.asList(a).hashCode()}, unless {@code a}
       
  4670      * is {@code null}, in which case {@code 0} is returned.
       
  4671      *
       
  4672      * @param a the array whose content-based hash code to compute
       
  4673      * @return a content-based hash code for {@code a}
       
  4674      * @see #deepHashCode(Object[])
       
  4675      * @since 1.5
       
  4676      */
       
  4677     public static int hashCode(Object a[]) {
       
  4678         if (a == null)
       
  4679             return 0;
       
  4680 
       
  4681         int result = 1;
       
  4682 
       
  4683         for (Object element : a)
       
  4684             result = 31 * result + (element == null ? 0 : element.hashCode());
       
  4685 
       
  4686         return result;
       
  4687     }
       
  4688 
       
  4689     /**
       
  4690      * Returns a hash code based on the "deep contents" of the specified
       
  4691      * array.  If the array contains other arrays as elements, the
       
  4692      * hash code is based on their contents and so on, ad infinitum.
       
  4693      * It is therefore unacceptable to invoke this method on an array that
       
  4694      * contains itself as an element, either directly or indirectly through
       
  4695      * one or more levels of arrays.  The behavior of such an invocation is
       
  4696      * undefined.
       
  4697      *
       
  4698      * <p>For any two arrays {@code a} and {@code b} such that
       
  4699      * {@code Arrays.deepEquals(a, b)}, it is also the case that
       
  4700      * {@code Arrays.deepHashCode(a) == Arrays.deepHashCode(b)}.
       
  4701      *
       
  4702      * <p>The computation of the value returned by this method is similar to
       
  4703      * that of the value returned by {@link List#hashCode()} on a list
       
  4704      * containing the same elements as {@code a} in the same order, with one
       
  4705      * difference: If an element {@code e} of {@code a} is itself an array,
       
  4706      * its hash code is computed not by calling {@code e.hashCode()}, but as
       
  4707      * by calling the appropriate overloading of {@code Arrays.hashCode(e)}
       
  4708      * if {@code e} is an array of a primitive type, or as by calling
       
  4709      * {@code Arrays.deepHashCode(e)} recursively if {@code e} is an array
       
  4710      * of a reference type.  If {@code a} is {@code null}, this method
       
  4711      * returns 0.
       
  4712      *
       
  4713      * @param a the array whose deep-content-based hash code to compute
       
  4714      * @return a deep-content-based hash code for {@code a}
       
  4715      * @see #hashCode(Object[])
       
  4716      * @since 1.5
       
  4717      */
       
  4718     public static int deepHashCode(Object a[]) {
       
  4719         if (a == null)
       
  4720             return 0;
       
  4721 
       
  4722         int result = 1;
       
  4723 
       
  4724         for (Object element : a) {
       
  4725             int elementHash = 0;
       
  4726             if (element instanceof Object[])
       
  4727                 elementHash = deepHashCode((Object[]) element);
       
  4728             else if (element instanceof byte[])
       
  4729                 elementHash = hashCode((byte[]) element);
       
  4730             else if (element instanceof short[])
       
  4731                 elementHash = hashCode((short[]) element);
       
  4732             else if (element instanceof int[])
       
  4733                 elementHash = hashCode((int[]) element);
       
  4734             else if (element instanceof long[])
       
  4735                 elementHash = hashCode((long[]) element);
       
  4736             else if (element instanceof char[])
       
  4737                 elementHash = hashCode((char[]) element);
       
  4738             else if (element instanceof float[])
       
  4739                 elementHash = hashCode((float[]) element);
       
  4740             else if (element instanceof double[])
       
  4741                 elementHash = hashCode((double[]) element);
       
  4742             else if (element instanceof boolean[])
       
  4743                 elementHash = hashCode((boolean[]) element);
       
  4744             else if (element != null)
       
  4745                 elementHash = element.hashCode();
       
  4746 
       
  4747             result = 31 * result + elementHash;
       
  4748         }
       
  4749 
       
  4750         return result;
       
  4751     }
       
  4752 
       
  4753     /**
       
  4754      * Returns {@code true} if the two specified arrays are <i>deeply
       
  4755      * equal</i> to one another.  Unlike the {@link #equals(Object[],Object[])}
       
  4756      * method, this method is appropriate for use with nested arrays of
       
  4757      * arbitrary depth.
       
  4758      *
       
  4759      * <p>Two array references are considered deeply equal if both
       
  4760      * are {@code null}, or if they refer to arrays that contain the same
       
  4761      * number of elements and all corresponding pairs of elements in the two
       
  4762      * arrays are deeply equal.
       
  4763      *
       
  4764      * <p>Two possibly {@code null} elements {@code e1} and {@code e2} are
       
  4765      * deeply equal if any of the following conditions hold:
       
  4766      * <ul>
       
  4767      *    <li> {@code e1} and {@code e2} are both arrays of object reference
       
  4768      *         types, and {@code Arrays.deepEquals(e1, e2) would return true}
       
  4769      *    <li> {@code e1} and {@code e2} are arrays of the same primitive
       
  4770      *         type, and the appropriate overloading of
       
  4771      *         {@code Arrays.equals(e1, e2)} would return true.
       
  4772      *    <li> {@code e1 == e2}
       
  4773      *    <li> {@code e1.equals(e2)} would return true.
       
  4774      * </ul>
       
  4775      * Note that this definition permits {@code null} elements at any depth.
       
  4776      *
       
  4777      * <p>If either of the specified arrays contain themselves as elements
       
  4778      * either directly or indirectly through one or more levels of arrays,
       
  4779      * the behavior of this method is undefined.
       
  4780      *
       
  4781      * @param a1 one array to be tested for equality
       
  4782      * @param a2 the other array to be tested for equality
       
  4783      * @return {@code true} if the two arrays are equal
       
  4784      * @see #equals(Object[],Object[])
       
  4785      * @see Objects#deepEquals(Object, Object)
       
  4786      * @since 1.5
       
  4787      */
       
  4788     public static boolean deepEquals(Object[] a1, Object[] a2) {
       
  4789         if (a1 == a2)
       
  4790             return true;
       
  4791         if (a1 == null || a2==null)
       
  4792             return false;
       
  4793         int length = a1.length;
       
  4794         if (a2.length != length)
       
  4795             return false;
       
  4796 
       
  4797         for (int i = 0; i < length; i++) {
       
  4798             Object e1 = a1[i];
       
  4799             Object e2 = a2[i];
       
  4800 
       
  4801             if (e1 == e2)
       
  4802                 continue;
       
  4803             if (e1 == null)
       
  4804                 return false;
       
  4805 
       
  4806             // Figure out whether the two elements are equal
       
  4807             boolean eq = deepEquals0(e1, e2);
       
  4808 
       
  4809             if (!eq)
       
  4810                 return false;
       
  4811         }
       
  4812         return true;
       
  4813     }
       
  4814 
       
  4815     static boolean deepEquals0(Object e1, Object e2) {
       
  4816         assert e1 != null;
       
  4817         boolean eq;
       
  4818         if (e1 instanceof Object[] && e2 instanceof Object[])
       
  4819             eq = deepEquals ((Object[]) e1, (Object[]) e2);
       
  4820         else if (e1 instanceof byte[] && e2 instanceof byte[])
       
  4821             eq = equals((byte[]) e1, (byte[]) e2);
       
  4822         else if (e1 instanceof short[] && e2 instanceof short[])
       
  4823             eq = equals((short[]) e1, (short[]) e2);
       
  4824         else if (e1 instanceof int[] && e2 instanceof int[])
       
  4825             eq = equals((int[]) e1, (int[]) e2);
       
  4826         else if (e1 instanceof long[] && e2 instanceof long[])
       
  4827             eq = equals((long[]) e1, (long[]) e2);
       
  4828         else if (e1 instanceof char[] && e2 instanceof char[])
       
  4829             eq = equals((char[]) e1, (char[]) e2);
       
  4830         else if (e1 instanceof float[] && e2 instanceof float[])
       
  4831             eq = equals((float[]) e1, (float[]) e2);
       
  4832         else if (e1 instanceof double[] && e2 instanceof double[])
       
  4833             eq = equals((double[]) e1, (double[]) e2);
       
  4834         else if (e1 instanceof boolean[] && e2 instanceof boolean[])
       
  4835             eq = equals((boolean[]) e1, (boolean[]) e2);
       
  4836         else
       
  4837             eq = e1.equals(e2);
       
  4838         return eq;
       
  4839     }
       
  4840 
       
  4841     /**
       
  4842      * Returns a string representation of the contents of the specified array.
       
  4843      * The string representation consists of a list of the array's elements,
       
  4844      * enclosed in square brackets ({@code "[]"}).  Adjacent elements are
       
  4845      * separated by the characters {@code ", "} (a comma followed by a
       
  4846      * space).  Elements are converted to strings as by
       
  4847      * {@code String.valueOf(long)}.  Returns {@code "null"} if {@code a}
       
  4848      * is {@code null}.
       
  4849      *
       
  4850      * @param a the array whose string representation to return
       
  4851      * @return a string representation of {@code a}
       
  4852      * @since 1.5
       
  4853      */
       
  4854     public static String toString(long[] a) {
       
  4855         if (a == null)
       
  4856             return "null";
       
  4857         int iMax = a.length - 1;
       
  4858         if (iMax == -1)
       
  4859             return "[]";
       
  4860 
       
  4861         StringBuilder b = new StringBuilder();
       
  4862         b.append('[');
       
  4863         for (int i = 0; ; i++) {
       
  4864             b.append(a[i]);
       
  4865             if (i == iMax)
       
  4866                 return b.append(']').toString();
       
  4867             b.append(", ");
       
  4868         }
       
  4869     }
       
  4870 
       
  4871     /**
       
  4872      * Returns a string representation of the contents of the specified array.
       
  4873      * The string representation consists of a list of the array's elements,
       
  4874      * enclosed in square brackets ({@code "[]"}).  Adjacent elements are
       
  4875      * separated by the characters {@code ", "} (a comma followed by a
       
  4876      * space).  Elements are converted to strings as by
       
  4877      * {@code String.valueOf(int)}.  Returns {@code "null"} if {@code a} is
       
  4878      * {@code null}.
       
  4879      *
       
  4880      * @param a the array whose string representation to return
       
  4881      * @return a string representation of {@code a}
       
  4882      * @since 1.5
       
  4883      */
       
  4884     public static String toString(int[] a) {
       
  4885         if (a == null)
       
  4886             return "null";
       
  4887         int iMax = a.length - 1;
       
  4888         if (iMax == -1)
       
  4889             return "[]";
       
  4890 
       
  4891         StringBuilder b = new StringBuilder();
       
  4892         b.append('[');
       
  4893         for (int i = 0; ; i++) {
       
  4894             b.append(a[i]);
       
  4895             if (i == iMax)
       
  4896                 return b.append(']').toString();
       
  4897             b.append(", ");
       
  4898         }
       
  4899     }
       
  4900 
       
  4901     /**
       
  4902      * Returns a string representation of the contents of the specified array.
       
  4903      * The string representation consists of a list of the array's elements,
       
  4904      * enclosed in square brackets ({@code "[]"}).  Adjacent elements are
       
  4905      * separated by the characters {@code ", "} (a comma followed by a
       
  4906      * space).  Elements are converted to strings as by
       
  4907      * {@code String.valueOf(short)}.  Returns {@code "null"} if {@code a}
       
  4908      * is {@code null}.
       
  4909      *
       
  4910      * @param a the array whose string representation to return
       
  4911      * @return a string representation of {@code a}
       
  4912      * @since 1.5
       
  4913      */
       
  4914     public static String toString(short[] a) {
       
  4915         if (a == null)
       
  4916             return "null";
       
  4917         int iMax = a.length - 1;
       
  4918         if (iMax == -1)
       
  4919             return "[]";
       
  4920 
       
  4921         StringBuilder b = new StringBuilder();
       
  4922         b.append('[');
       
  4923         for (int i = 0; ; i++) {
       
  4924             b.append(a[i]);
       
  4925             if (i == iMax)
       
  4926                 return b.append(']').toString();
       
  4927             b.append(", ");
       
  4928         }
       
  4929     }
       
  4930 
       
  4931     /**
       
  4932      * Returns a string representation of the contents of the specified array.
       
  4933      * The string representation consists of a list of the array's elements,
       
  4934      * enclosed in square brackets ({@code "[]"}).  Adjacent elements are
       
  4935      * separated by the characters {@code ", "} (a comma followed by a
       
  4936      * space).  Elements are converted to strings as by
       
  4937      * {@code String.valueOf(char)}.  Returns {@code "null"} if {@code a}
       
  4938      * is {@code null}.
       
  4939      *
       
  4940      * @param a the array whose string representation to return
       
  4941      * @return a string representation of {@code a}
       
  4942      * @since 1.5
       
  4943      */
       
  4944     public static String toString(char[] a) {
       
  4945         if (a == null)
       
  4946             return "null";
       
  4947         int iMax = a.length - 1;
       
  4948         if (iMax == -1)
       
  4949             return "[]";
       
  4950 
       
  4951         StringBuilder b = new StringBuilder();
       
  4952         b.append('[');
       
  4953         for (int i = 0; ; i++) {
       
  4954             b.append(a[i]);
       
  4955             if (i == iMax)
       
  4956                 return b.append(']').toString();
       
  4957             b.append(", ");
       
  4958         }
       
  4959     }
       
  4960 
       
  4961     /**
       
  4962      * Returns a string representation of the contents of the specified array.
       
  4963      * The string representation consists of a list of the array's elements,
       
  4964      * enclosed in square brackets ({@code "[]"}).  Adjacent elements
       
  4965      * are separated by the characters {@code ", "} (a comma followed
       
  4966      * by a space).  Elements are converted to strings as by
       
  4967      * {@code String.valueOf(byte)}.  Returns {@code "null"} if
       
  4968      * {@code a} is {@code null}.
       
  4969      *
       
  4970      * @param a the array whose string representation to return
       
  4971      * @return a string representation of {@code a}
       
  4972      * @since 1.5
       
  4973      */
       
  4974     public static String toString(byte[] a) {
       
  4975         if (a == null)
       
  4976             return "null";
       
  4977         int iMax = a.length - 1;
       
  4978         if (iMax == -1)
       
  4979             return "[]";
       
  4980 
       
  4981         StringBuilder b = new StringBuilder();
       
  4982         b.append('[');
       
  4983         for (int i = 0; ; i++) {
       
  4984             b.append(a[i]);
       
  4985             if (i == iMax)
       
  4986                 return b.append(']').toString();
       
  4987             b.append(", ");
       
  4988         }
       
  4989     }
       
  4990 
       
  4991     /**
       
  4992      * Returns a string representation of the contents of the specified array.
       
  4993      * The string representation consists of a list of the array's elements,
       
  4994      * enclosed in square brackets ({@code "[]"}).  Adjacent elements are
       
  4995      * separated by the characters {@code ", "} (a comma followed by a
       
  4996      * space).  Elements are converted to strings as by
       
  4997      * {@code String.valueOf(boolean)}.  Returns {@code "null"} if
       
  4998      * {@code a} is {@code null}.
       
  4999      *
       
  5000      * @param a the array whose string representation to return
       
  5001      * @return a string representation of {@code a}
       
  5002      * @since 1.5
       
  5003      */
       
  5004     public static String toString(boolean[] a) {
       
  5005         if (a == null)
       
  5006             return "null";
       
  5007         int iMax = a.length - 1;
       
  5008         if (iMax == -1)
       
  5009             return "[]";
       
  5010 
       
  5011         StringBuilder b = new StringBuilder();
       
  5012         b.append('[');
       
  5013         for (int i = 0; ; i++) {
       
  5014             b.append(a[i]);
       
  5015             if (i == iMax)
       
  5016                 return b.append(']').toString();
       
  5017             b.append(", ");
       
  5018         }
       
  5019     }
       
  5020 
       
  5021     /**
       
  5022      * Returns a string representation of the contents of the specified array.
       
  5023      * The string representation consists of a list of the array's elements,
       
  5024      * enclosed in square brackets ({@code "[]"}).  Adjacent elements are
       
  5025      * separated by the characters {@code ", "} (a comma followed by a
       
  5026      * space).  Elements are converted to strings as by
       
  5027      * {@code String.valueOf(float)}.  Returns {@code "null"} if {@code a}
       
  5028      * is {@code null}.
       
  5029      *
       
  5030      * @param a the array whose string representation to return
       
  5031      * @return a string representation of {@code a}
       
  5032      * @since 1.5
       
  5033      */
       
  5034     public static String toString(float[] a) {
       
  5035         if (a == null)
       
  5036             return "null";
       
  5037 
       
  5038         int iMax = a.length - 1;
       
  5039         if (iMax == -1)
       
  5040             return "[]";
       
  5041 
       
  5042         StringBuilder b = new StringBuilder();
       
  5043         b.append('[');
       
  5044         for (int i = 0; ; i++) {
       
  5045             b.append(a[i]);
       
  5046             if (i == iMax)
       
  5047                 return b.append(']').toString();
       
  5048             b.append(", ");
       
  5049         }
       
  5050     }
       
  5051 
       
  5052     /**
       
  5053      * Returns a string representation of the contents of the specified array.
       
  5054      * The string representation consists of a list of the array's elements,
       
  5055      * enclosed in square brackets ({@code "[]"}).  Adjacent elements are
       
  5056      * separated by the characters {@code ", "} (a comma followed by a
       
  5057      * space).  Elements are converted to strings as by
       
  5058      * {@code String.valueOf(double)}.  Returns {@code "null"} if {@code a}
       
  5059      * is {@code null}.
       
  5060      *
       
  5061      * @param a the array whose string representation to return
       
  5062      * @return a string representation of {@code a}
       
  5063      * @since 1.5
       
  5064      */
       
  5065     public static String toString(double[] a) {
       
  5066         if (a == null)
       
  5067             return "null";
       
  5068         int iMax = a.length - 1;
       
  5069         if (iMax == -1)
       
  5070             return "[]";
       
  5071 
       
  5072         StringBuilder b = new StringBuilder();
       
  5073         b.append('[');
       
  5074         for (int i = 0; ; i++) {
       
  5075             b.append(a[i]);
       
  5076             if (i == iMax)
       
  5077                 return b.append(']').toString();
       
  5078             b.append(", ");
       
  5079         }
       
  5080     }
       
  5081 
       
  5082     /**
       
  5083      * Returns a string representation of the contents of the specified array.
       
  5084      * If the array contains other arrays as elements, they are converted to
       
  5085      * strings by the {@link Object#toString} method inherited from
       
  5086      * {@code Object}, which describes their <i>identities</i> rather than
       
  5087      * their contents.
       
  5088      *
       
  5089      * <p>The value returned by this method is equal to the value that would
       
  5090      * be returned by {@code Arrays.asList(a).toString()}, unless {@code a}
       
  5091      * is {@code null}, in which case {@code "null"} is returned.
       
  5092      *
       
  5093      * @param a the array whose string representation to return
       
  5094      * @return a string representation of {@code a}
       
  5095      * @see #deepToString(Object[])
       
  5096      * @since 1.5
       
  5097      */
       
  5098     public static String toString(Object[] a) {
       
  5099         if (a == null)
       
  5100             return "null";
       
  5101 
       
  5102         int iMax = a.length - 1;
       
  5103         if (iMax == -1)
       
  5104             return "[]";
       
  5105 
       
  5106         StringBuilder b = new StringBuilder();
       
  5107         b.append('[');
       
  5108         for (int i = 0; ; i++) {
       
  5109             b.append(String.valueOf(a[i]));
       
  5110             if (i == iMax)
       
  5111                 return b.append(']').toString();
       
  5112             b.append(", ");
       
  5113         }
       
  5114     }
       
  5115 
       
  5116     /**
       
  5117      * Returns a string representation of the "deep contents" of the specified
       
  5118      * array.  If the array contains other arrays as elements, the string
       
  5119      * representation contains their contents and so on.  This method is
       
  5120      * designed for converting multidimensional arrays to strings.
       
  5121      *
       
  5122      * <p>The string representation consists of a list of the array's
       
  5123      * elements, enclosed in square brackets ({@code "[]"}).  Adjacent
       
  5124      * elements are separated by the characters {@code ", "} (a comma
       
  5125      * followed by a space).  Elements are converted to strings as by
       
  5126      * {@code String.valueOf(Object)}, unless they are themselves
       
  5127      * arrays.
       
  5128      *
       
  5129      * <p>If an element {@code e} is an array of a primitive type, it is
       
  5130      * converted to a string as by invoking the appropriate overloading of
       
  5131      * {@code Arrays.toString(e)}.  If an element {@code e} is an array of a
       
  5132      * reference type, it is converted to a string as by invoking
       
  5133      * this method recursively.
       
  5134      *
       
  5135      * <p>To avoid infinite recursion, if the specified array contains itself
       
  5136      * as an element, or contains an indirect reference to itself through one
       
  5137      * or more levels of arrays, the self-reference is converted to the string
       
  5138      * {@code "[...]"}.  For example, an array containing only a reference
       
  5139      * to itself would be rendered as {@code "[[...]]"}.
       
  5140      *
       
  5141      * <p>This method returns {@code "null"} if the specified array
       
  5142      * is {@code null}.
       
  5143      *
       
  5144      * @param a the array whose string representation to return
       
  5145      * @return a string representation of {@code a}
       
  5146      * @see #toString(Object[])
       
  5147      * @since 1.5
       
  5148      */
       
  5149     public static String deepToString(Object[] a) {
       
  5150         if (a == null)
       
  5151             return "null";
       
  5152 
       
  5153         int bufLen = 20 * a.length;
       
  5154         if (a.length != 0 && bufLen <= 0)
       
  5155             bufLen = Integer.MAX_VALUE;
       
  5156         StringBuilder buf = new StringBuilder(bufLen);
       
  5157         deepToString(a, buf, new HashSet<>());
       
  5158         return buf.toString();
       
  5159     }
       
  5160 
       
  5161     private static void deepToString(Object[] a, StringBuilder buf,
       
  5162                                      Set<Object[]> dejaVu) {
       
  5163         if (a == null) {
       
  5164             buf.append("null");
       
  5165             return;
       
  5166         }
       
  5167         int iMax = a.length - 1;
       
  5168         if (iMax == -1) {
       
  5169             buf.append("[]");
       
  5170             return;
       
  5171         }
       
  5172 
       
  5173         dejaVu.add(a);
       
  5174         buf.append('[');
       
  5175         for (int i = 0; ; i++) {
       
  5176 
       
  5177             Object element = a[i];
       
  5178             if (element == null) {
       
  5179                 buf.append("null");
       
  5180             } else {
       
  5181                 Class<?> eClass = element.getClass();
       
  5182 
       
  5183                 if (eClass.isArray()) {
       
  5184                     if (eClass == byte[].class)
       
  5185                         buf.append(toString((byte[]) element));
       
  5186                     else if (eClass == short[].class)
       
  5187                         buf.append(toString((short[]) element));
       
  5188                     else if (eClass == int[].class)
       
  5189                         buf.append(toString((int[]) element));
       
  5190                     else if (eClass == long[].class)
       
  5191                         buf.append(toString((long[]) element));
       
  5192                     else if (eClass == char[].class)
       
  5193                         buf.append(toString((char[]) element));
       
  5194                     else if (eClass == float[].class)
       
  5195                         buf.append(toString((float[]) element));
       
  5196                     else if (eClass == double[].class)
       
  5197                         buf.append(toString((double[]) element));
       
  5198                     else if (eClass == boolean[].class)
       
  5199                         buf.append(toString((boolean[]) element));
       
  5200                     else { // element is an array of object references
       
  5201                         if (dejaVu.contains(element))
       
  5202                             buf.append("[...]");
       
  5203                         else
       
  5204                             deepToString((Object[])element, buf, dejaVu);
       
  5205                     }
       
  5206                 } else {  // element is non-null and not an array
       
  5207                     buf.append(element.toString());
       
  5208                 }
       
  5209             }
       
  5210             if (i == iMax)
       
  5211                 break;
       
  5212             buf.append(", ");
       
  5213         }
       
  5214         buf.append(']');
       
  5215         dejaVu.remove(a);
       
  5216     }
       
  5217 
       
  5218 
       
  5219     /**
       
  5220      * Set all elements of the specified array, using the provided
       
  5221      * generator function to compute each element.
       
  5222      *
       
  5223      * <p>If the generator function throws an exception, it is relayed to
       
  5224      * the caller and the array is left in an indeterminate state.
       
  5225      *
       
  5226      * @apiNote
       
  5227      * Setting a subrange of an array, using a generator function to compute
       
  5228      * each element, can be written as follows:
       
  5229      * <pre>{@code
       
  5230      * IntStream.range(startInclusive, endExclusive)
       
  5231      *          .forEach(i -> array[i] = generator.apply(i));
       
  5232      * }</pre>
       
  5233      *
       
  5234      * @param <T> type of elements of the array
       
  5235      * @param array array to be initialized
       
  5236      * @param generator a function accepting an index and producing the desired
       
  5237      *        value for that position
       
  5238      * @throws NullPointerException if the generator is null
       
  5239      * @since 1.8
       
  5240      */
       
  5241     public static <T> void setAll(T[] array, IntFunction<? extends T> generator) {
       
  5242         Objects.requireNonNull(generator);
       
  5243         for (int i = 0; i < array.length; i++)
       
  5244             array[i] = generator.apply(i);
       
  5245     }
       
  5246 
       
  5247     /**
       
  5248      * Set all elements of the specified array, in parallel, using the
       
  5249      * provided generator function to compute each element.
       
  5250      *
       
  5251      * <p>If the generator function throws an exception, an unchecked exception
       
  5252      * is thrown from {@code parallelSetAll} and the array is left in an
       
  5253      * indeterminate state.
       
  5254      *
       
  5255      * @apiNote
       
  5256      * Setting a subrange of an array, in parallel, using a generator function
       
  5257      * to compute each element, can be written as follows:
       
  5258      * <pre>{@code
       
  5259      * IntStream.range(startInclusive, endExclusive)
       
  5260      *          .parallel()
       
  5261      *          .forEach(i -> array[i] = generator.apply(i));
       
  5262      * }</pre>
       
  5263      *
       
  5264      * @param <T> type of elements of the array
       
  5265      * @param array array to be initialized
       
  5266      * @param generator a function accepting an index and producing the desired
       
  5267      *        value for that position
       
  5268      * @throws NullPointerException if the generator is null
       
  5269      * @since 1.8
       
  5270      */
       
  5271     public static <T> void parallelSetAll(T[] array, IntFunction<? extends T> generator) {
       
  5272         Objects.requireNonNull(generator);
       
  5273         IntStream.range(0, array.length).parallel().forEach(i -> { array[i] = generator.apply(i); });
       
  5274     }
       
  5275 
       
  5276     /**
       
  5277      * Set all elements of the specified array, using the provided
       
  5278      * generator function to compute each element.
       
  5279      *
       
  5280      * <p>If the generator function throws an exception, it is relayed to
       
  5281      * the caller and the array is left in an indeterminate state.
       
  5282      *
       
  5283      * @apiNote
       
  5284      * Setting a subrange of an array, using a generator function to compute
       
  5285      * each element, can be written as follows:
       
  5286      * <pre>{@code
       
  5287      * IntStream.range(startInclusive, endExclusive)
       
  5288      *          .forEach(i -> array[i] = generator.applyAsInt(i));
       
  5289      * }</pre>
       
  5290      *
       
  5291      * @param array array to be initialized
       
  5292      * @param generator a function accepting an index and producing the desired
       
  5293      *        value for that position
       
  5294      * @throws NullPointerException if the generator is null
       
  5295      * @since 1.8
       
  5296      */
       
  5297     public static void setAll(int[] array, IntUnaryOperator generator) {
       
  5298         Objects.requireNonNull(generator);
       
  5299         for (int i = 0; i < array.length; i++)
       
  5300             array[i] = generator.applyAsInt(i);
       
  5301     }
       
  5302 
       
  5303     /**
       
  5304      * Set all elements of the specified array, in parallel, using the
       
  5305      * provided generator function to compute each element.
       
  5306      *
       
  5307      * <p>If the generator function throws an exception, an unchecked exception
       
  5308      * is thrown from {@code parallelSetAll} and the array is left in an
       
  5309      * indeterminate state.
       
  5310      *
       
  5311      * @apiNote
       
  5312      * Setting a subrange of an array, in parallel, using a generator function
       
  5313      * to compute each element, can be written as follows:
       
  5314      * <pre>{@code
       
  5315      * IntStream.range(startInclusive, endExclusive)
       
  5316      *          .parallel()
       
  5317      *          .forEach(i -> array[i] = generator.applyAsInt(i));
       
  5318      * }</pre>
       
  5319      *
       
  5320      * @param array array to be initialized
       
  5321      * @param generator a function accepting an index and producing the desired
       
  5322      * value for that position
       
  5323      * @throws NullPointerException if the generator is null
       
  5324      * @since 1.8
       
  5325      */
       
  5326     public static void parallelSetAll(int[] array, IntUnaryOperator generator) {
       
  5327         Objects.requireNonNull(generator);
       
  5328         IntStream.range(0, array.length).parallel().forEach(i -> { array[i] = generator.applyAsInt(i); });
       
  5329     }
       
  5330 
       
  5331     /**
       
  5332      * Set all elements of the specified array, using the provided
       
  5333      * generator function to compute each element.
       
  5334      *
       
  5335      * <p>If the generator function throws an exception, it is relayed to
       
  5336      * the caller and the array is left in an indeterminate state.
       
  5337      *
       
  5338      * @apiNote
       
  5339      * Setting a subrange of an array, using a generator function to compute
       
  5340      * each element, can be written as follows:
       
  5341      * <pre>{@code
       
  5342      * IntStream.range(startInclusive, endExclusive)
       
  5343      *          .forEach(i -> array[i] = generator.applyAsLong(i));
       
  5344      * }</pre>
       
  5345      *
       
  5346      * @param array array to be initialized
       
  5347      * @param generator a function accepting an index and producing the desired
       
  5348      *        value for that position
       
  5349      * @throws NullPointerException if the generator is null
       
  5350      * @since 1.8
       
  5351      */
       
  5352     public static void setAll(long[] array, IntToLongFunction generator) {
       
  5353         Objects.requireNonNull(generator);
       
  5354         for (int i = 0; i < array.length; i++)
       
  5355             array[i] = generator.applyAsLong(i);
       
  5356     }
       
  5357 
       
  5358     /**
       
  5359      * Set all elements of the specified array, in parallel, using the
       
  5360      * provided generator function to compute each element.
       
  5361      *
       
  5362      * <p>If the generator function throws an exception, an unchecked exception
       
  5363      * is thrown from {@code parallelSetAll} and the array is left in an
       
  5364      * indeterminate state.
       
  5365      *
       
  5366      * @apiNote
       
  5367      * Setting a subrange of an array, in parallel, using a generator function
       
  5368      * to compute each element, can be written as follows:
       
  5369      * <pre>{@code
       
  5370      * IntStream.range(startInclusive, endExclusive)
       
  5371      *          .parallel()
       
  5372      *          .forEach(i -> array[i] = generator.applyAsLong(i));
       
  5373      * }</pre>
       
  5374      *
       
  5375      * @param array array to be initialized
       
  5376      * @param generator a function accepting an index and producing the desired
       
  5377      *        value for that position
       
  5378      * @throws NullPointerException if the generator is null
       
  5379      * @since 1.8
       
  5380      */
       
  5381     public static void parallelSetAll(long[] array, IntToLongFunction generator) {
       
  5382         Objects.requireNonNull(generator);
       
  5383         IntStream.range(0, array.length).parallel().forEach(i -> { array[i] = generator.applyAsLong(i); });
       
  5384     }
       
  5385 
       
  5386     /**
       
  5387      * Set all elements of the specified array, using the provided
       
  5388      * generator function to compute each element.
       
  5389      *
       
  5390      * <p>If the generator function throws an exception, it is relayed to
       
  5391      * the caller and the array is left in an indeterminate state.
       
  5392      *
       
  5393      * @apiNote
       
  5394      * Setting a subrange of an array, using a generator function to compute
       
  5395      * each element, can be written as follows:
       
  5396      * <pre>{@code
       
  5397      * IntStream.range(startInclusive, endExclusive)
       
  5398      *          .forEach(i -> array[i] = generator.applyAsDouble(i));
       
  5399      * }</pre>
       
  5400      *
       
  5401      * @param array array to be initialized
       
  5402      * @param generator a function accepting an index and producing the desired
       
  5403      *        value for that position
       
  5404      * @throws NullPointerException if the generator is null
       
  5405      * @since 1.8
       
  5406      */
       
  5407     public static void setAll(double[] array, IntToDoubleFunction generator) {
       
  5408         Objects.requireNonNull(generator);
       
  5409         for (int i = 0; i < array.length; i++)
       
  5410             array[i] = generator.applyAsDouble(i);
       
  5411     }
       
  5412 
       
  5413     /**
       
  5414      * Set all elements of the specified array, in parallel, using the
       
  5415      * provided generator function to compute each element.
       
  5416      *
       
  5417      * <p>If the generator function throws an exception, an unchecked exception
       
  5418      * is thrown from {@code parallelSetAll} and the array is left in an
       
  5419      * indeterminate state.
       
  5420      *
       
  5421      * @apiNote
       
  5422      * Setting a subrange of an array, in parallel, using a generator function
       
  5423      * to compute each element, can be written as follows:
       
  5424      * <pre>{@code
       
  5425      * IntStream.range(startInclusive, endExclusive)
       
  5426      *          .parallel()
       
  5427      *          .forEach(i -> array[i] = generator.applyAsDouble(i));
       
  5428      * }</pre>
       
  5429      *
       
  5430      * @param array array to be initialized
       
  5431      * @param generator a function accepting an index and producing the desired
       
  5432      *        value for that position
       
  5433      * @throws NullPointerException if the generator is null
       
  5434      * @since 1.8
       
  5435      */
       
  5436     public static void parallelSetAll(double[] array, IntToDoubleFunction generator) {
       
  5437         Objects.requireNonNull(generator);
       
  5438         IntStream.range(0, array.length).parallel().forEach(i -> { array[i] = generator.applyAsDouble(i); });
       
  5439     }
       
  5440 
       
  5441     /**
       
  5442      * Returns a {@link Spliterator} covering all of the specified array.
       
  5443      *
       
  5444      * <p>The spliterator reports {@link Spliterator#SIZED},
       
  5445      * {@link Spliterator#SUBSIZED}, {@link Spliterator#ORDERED}, and
       
  5446      * {@link Spliterator#IMMUTABLE}.
       
  5447      *
       
  5448      * @param <T> type of elements
       
  5449      * @param array the array, assumed to be unmodified during use
       
  5450      * @return a spliterator for the array elements
       
  5451      * @since 1.8
       
  5452      */
       
  5453     public static <T> Spliterator<T> spliterator(T[] array) {
       
  5454         return Spliterators.spliterator(array,
       
  5455                                         Spliterator.ORDERED | Spliterator.IMMUTABLE);
       
  5456     }
       
  5457 
       
  5458     /**
       
  5459      * Returns a {@link Spliterator} covering the specified range of the
       
  5460      * specified array.
       
  5461      *
       
  5462      * <p>The spliterator reports {@link Spliterator#SIZED},
       
  5463      * {@link Spliterator#SUBSIZED}, {@link Spliterator#ORDERED}, and
       
  5464      * {@link Spliterator#IMMUTABLE}.
       
  5465      *
       
  5466      * @param <T> type of elements
       
  5467      * @param array the array, assumed to be unmodified during use
       
  5468      * @param startInclusive the first index to cover, inclusive
       
  5469      * @param endExclusive index immediately past the last index to cover
       
  5470      * @return a spliterator for the array elements
       
  5471      * @throws ArrayIndexOutOfBoundsException if {@code startInclusive} is
       
  5472      *         negative, {@code endExclusive} is less than
       
  5473      *         {@code startInclusive}, or {@code endExclusive} is greater than
       
  5474      *         the array size
       
  5475      * @since 1.8
       
  5476      */
       
  5477     public static <T> Spliterator<T> spliterator(T[] array, int startInclusive, int endExclusive) {
       
  5478         return Spliterators.spliterator(array, startInclusive, endExclusive,
       
  5479                                         Spliterator.ORDERED | Spliterator.IMMUTABLE);
       
  5480     }
       
  5481 
       
  5482     /**
       
  5483      * Returns a {@link Spliterator.OfInt} covering all of the specified array.
       
  5484      *
       
  5485      * <p>The spliterator reports {@link Spliterator#SIZED},
       
  5486      * {@link Spliterator#SUBSIZED}, {@link Spliterator#ORDERED}, and
       
  5487      * {@link Spliterator#IMMUTABLE}.
       
  5488      *
       
  5489      * @param array the array, assumed to be unmodified during use
       
  5490      * @return a spliterator for the array elements
       
  5491      * @since 1.8
       
  5492      */
       
  5493     public static Spliterator.OfInt spliterator(int[] array) {
       
  5494         return Spliterators.spliterator(array,
       
  5495                                         Spliterator.ORDERED | Spliterator.IMMUTABLE);
       
  5496     }
       
  5497 
       
  5498     /**
       
  5499      * Returns a {@link Spliterator.OfInt} covering the specified range of the
       
  5500      * specified array.
       
  5501      *
       
  5502      * <p>The spliterator reports {@link Spliterator#SIZED},
       
  5503      * {@link Spliterator#SUBSIZED}, {@link Spliterator#ORDERED}, and
       
  5504      * {@link Spliterator#IMMUTABLE}.
       
  5505      *
       
  5506      * @param array the array, assumed to be unmodified during use
       
  5507      * @param startInclusive the first index to cover, inclusive
       
  5508      * @param endExclusive index immediately past the last index to cover
       
  5509      * @return a spliterator for the array elements
       
  5510      * @throws ArrayIndexOutOfBoundsException if {@code startInclusive} is
       
  5511      *         negative, {@code endExclusive} is less than
       
  5512      *         {@code startInclusive}, or {@code endExclusive} is greater than
       
  5513      *         the array size
       
  5514      * @since 1.8
       
  5515      */
       
  5516     public static Spliterator.OfInt spliterator(int[] array, int startInclusive, int endExclusive) {
       
  5517         return Spliterators.spliterator(array, startInclusive, endExclusive,
       
  5518                                         Spliterator.ORDERED | Spliterator.IMMUTABLE);
       
  5519     }
       
  5520 
       
  5521     /**
       
  5522      * Returns a {@link Spliterator.OfLong} covering all of the specified array.
       
  5523      *
       
  5524      * <p>The spliterator reports {@link Spliterator#SIZED},
       
  5525      * {@link Spliterator#SUBSIZED}, {@link Spliterator#ORDERED}, and
       
  5526      * {@link Spliterator#IMMUTABLE}.
       
  5527      *
       
  5528      * @param array the array, assumed to be unmodified during use
       
  5529      * @return the spliterator for the array elements
       
  5530      * @since 1.8
       
  5531      */
       
  5532     public static Spliterator.OfLong spliterator(long[] array) {
       
  5533         return Spliterators.spliterator(array,
       
  5534                                         Spliterator.ORDERED | Spliterator.IMMUTABLE);
       
  5535     }
       
  5536 
       
  5537     /**
       
  5538      * Returns a {@link Spliterator.OfLong} covering the specified range of the
       
  5539      * specified array.
       
  5540      *
       
  5541      * <p>The spliterator reports {@link Spliterator#SIZED},
       
  5542      * {@link Spliterator#SUBSIZED}, {@link Spliterator#ORDERED}, and
       
  5543      * {@link Spliterator#IMMUTABLE}.
       
  5544      *
       
  5545      * @param array the array, assumed to be unmodified during use
       
  5546      * @param startInclusive the first index to cover, inclusive
       
  5547      * @param endExclusive index immediately past the last index to cover
       
  5548      * @return a spliterator for the array elements
       
  5549      * @throws ArrayIndexOutOfBoundsException if {@code startInclusive} is
       
  5550      *         negative, {@code endExclusive} is less than
       
  5551      *         {@code startInclusive}, or {@code endExclusive} is greater than
       
  5552      *         the array size
       
  5553      * @since 1.8
       
  5554      */
       
  5555     public static Spliterator.OfLong spliterator(long[] array, int startInclusive, int endExclusive) {
       
  5556         return Spliterators.spliterator(array, startInclusive, endExclusive,
       
  5557                                         Spliterator.ORDERED | Spliterator.IMMUTABLE);
       
  5558     }
       
  5559 
       
  5560     /**
       
  5561      * Returns a {@link Spliterator.OfDouble} covering all of the specified
       
  5562      * array.
       
  5563      *
       
  5564      * <p>The spliterator reports {@link Spliterator#SIZED},
       
  5565      * {@link Spliterator#SUBSIZED}, {@link Spliterator#ORDERED}, and
       
  5566      * {@link Spliterator#IMMUTABLE}.
       
  5567      *
       
  5568      * @param array the array, assumed to be unmodified during use
       
  5569      * @return a spliterator for the array elements
       
  5570      * @since 1.8
       
  5571      */
       
  5572     public static Spliterator.OfDouble spliterator(double[] array) {
       
  5573         return Spliterators.spliterator(array,
       
  5574                                         Spliterator.ORDERED | Spliterator.IMMUTABLE);
       
  5575     }
       
  5576 
       
  5577     /**
       
  5578      * Returns a {@link Spliterator.OfDouble} covering the specified range of
       
  5579      * the specified array.
       
  5580      *
       
  5581      * <p>The spliterator reports {@link Spliterator#SIZED},
       
  5582      * {@link Spliterator#SUBSIZED}, {@link Spliterator#ORDERED}, and
       
  5583      * {@link Spliterator#IMMUTABLE}.
       
  5584      *
       
  5585      * @param array the array, assumed to be unmodified during use
       
  5586      * @param startInclusive the first index to cover, inclusive
       
  5587      * @param endExclusive index immediately past the last index to cover
       
  5588      * @return a spliterator for the array elements
       
  5589      * @throws ArrayIndexOutOfBoundsException if {@code startInclusive} is
       
  5590      *         negative, {@code endExclusive} is less than
       
  5591      *         {@code startInclusive}, or {@code endExclusive} is greater than
       
  5592      *         the array size
       
  5593      * @since 1.8
       
  5594      */
       
  5595     public static Spliterator.OfDouble spliterator(double[] array, int startInclusive, int endExclusive) {
       
  5596         return Spliterators.spliterator(array, startInclusive, endExclusive,
       
  5597                                         Spliterator.ORDERED | Spliterator.IMMUTABLE);
       
  5598     }
       
  5599 
       
  5600     /**
       
  5601      * Returns a sequential {@link Stream} with the specified array as its
       
  5602      * source.
       
  5603      *
       
  5604      * @param <T> The type of the array elements
       
  5605      * @param array The array, assumed to be unmodified during use
       
  5606      * @return a {@code Stream} for the array
       
  5607      * @since 1.8
       
  5608      */
       
  5609     public static <T> Stream<T> stream(T[] array) {
       
  5610         return stream(array, 0, array.length);
       
  5611     }
       
  5612 
       
  5613     /**
       
  5614      * Returns a sequential {@link Stream} with the specified range of the
       
  5615      * specified array as its source.
       
  5616      *
       
  5617      * @param <T> the type of the array elements
       
  5618      * @param array the array, assumed to be unmodified during use
       
  5619      * @param startInclusive the first index to cover, inclusive
       
  5620      * @param endExclusive index immediately past the last index to cover
       
  5621      * @return a {@code Stream} for the array range
       
  5622      * @throws ArrayIndexOutOfBoundsException if {@code startInclusive} is
       
  5623      *         negative, {@code endExclusive} is less than
       
  5624      *         {@code startInclusive}, or {@code endExclusive} is greater than
       
  5625      *         the array size
       
  5626      * @since 1.8
       
  5627      */
       
  5628     public static <T> Stream<T> stream(T[] array, int startInclusive, int endExclusive) {
       
  5629         return StreamSupport.stream(spliterator(array, startInclusive, endExclusive), false);
       
  5630     }
       
  5631 
       
  5632     /**
       
  5633      * Returns a sequential {@link IntStream} with the specified array as its
       
  5634      * source.
       
  5635      *
       
  5636      * @param array the array, assumed to be unmodified during use
       
  5637      * @return an {@code IntStream} for the array
       
  5638      * @since 1.8
       
  5639      */
       
  5640     public static IntStream stream(int[] array) {
       
  5641         return stream(array, 0, array.length);
       
  5642     }
       
  5643 
       
  5644     /**
       
  5645      * Returns a sequential {@link IntStream} with the specified range of the
       
  5646      * specified array as its source.
       
  5647      *
       
  5648      * @param array the array, assumed to be unmodified during use
       
  5649      * @param startInclusive the first index to cover, inclusive
       
  5650      * @param endExclusive index immediately past the last index to cover
       
  5651      * @return an {@code IntStream} for the array range
       
  5652      * @throws ArrayIndexOutOfBoundsException if {@code startInclusive} is
       
  5653      *         negative, {@code endExclusive} is less than
       
  5654      *         {@code startInclusive}, or {@code endExclusive} is greater than
       
  5655      *         the array size
       
  5656      * @since 1.8
       
  5657      */
       
  5658     public static IntStream stream(int[] array, int startInclusive, int endExclusive) {
       
  5659         return StreamSupport.intStream(spliterator(array, startInclusive, endExclusive), false);
       
  5660     }
       
  5661 
       
  5662     /**
       
  5663      * Returns a sequential {@link LongStream} with the specified array as its
       
  5664      * source.
       
  5665      *
       
  5666      * @param array the array, assumed to be unmodified during use
       
  5667      * @return a {@code LongStream} for the array
       
  5668      * @since 1.8
       
  5669      */
       
  5670     public static LongStream stream(long[] array) {
       
  5671         return stream(array, 0, array.length);
       
  5672     }
       
  5673 
       
  5674     /**
       
  5675      * Returns a sequential {@link LongStream} with the specified range of the
       
  5676      * specified array as its source.
       
  5677      *
       
  5678      * @param array the array, assumed to be unmodified during use
       
  5679      * @param startInclusive the first index to cover, inclusive
       
  5680      * @param endExclusive index immediately past the last index to cover
       
  5681      * @return a {@code LongStream} for the array range
       
  5682      * @throws ArrayIndexOutOfBoundsException if {@code startInclusive} is
       
  5683      *         negative, {@code endExclusive} is less than
       
  5684      *         {@code startInclusive}, or {@code endExclusive} is greater than
       
  5685      *         the array size
       
  5686      * @since 1.8
       
  5687      */
       
  5688     public static LongStream stream(long[] array, int startInclusive, int endExclusive) {
       
  5689         return StreamSupport.longStream(spliterator(array, startInclusive, endExclusive), false);
       
  5690     }
       
  5691 
       
  5692     /**
       
  5693      * Returns a sequential {@link DoubleStream} with the specified array as its
       
  5694      * source.
       
  5695      *
       
  5696      * @param array the array, assumed to be unmodified during use
       
  5697      * @return a {@code DoubleStream} for the array
       
  5698      * @since 1.8
       
  5699      */
       
  5700     public static DoubleStream stream(double[] array) {
       
  5701         return stream(array, 0, array.length);
       
  5702     }
       
  5703 
       
  5704     /**
       
  5705      * Returns a sequential {@link DoubleStream} with the specified range of the
       
  5706      * specified array as its source.
       
  5707      *
       
  5708      * @param array the array, assumed to be unmodified during use
       
  5709      * @param startInclusive the first index to cover, inclusive
       
  5710      * @param endExclusive index immediately past the last index to cover
       
  5711      * @return a {@code DoubleStream} for the array range
       
  5712      * @throws ArrayIndexOutOfBoundsException if {@code startInclusive} is
       
  5713      *         negative, {@code endExclusive} is less than
       
  5714      *         {@code startInclusive}, or {@code endExclusive} is greater than
       
  5715      *         the array size
       
  5716      * @since 1.8
       
  5717      */
       
  5718     public static DoubleStream stream(double[] array, int startInclusive, int endExclusive) {
       
  5719         return StreamSupport.doubleStream(spliterator(array, startInclusive, endExclusive), false);
       
  5720     }
       
  5721 
       
  5722 
       
  5723     // Comparison methods
       
  5724 
       
  5725     // Compare boolean
       
  5726 
       
  5727     /**
       
  5728      * Compares two {@code boolean} arrays lexicographically.
       
  5729      *
       
  5730      * <p>If the two arrays share a common prefix then the lexicographic
       
  5731      * comparison is the result of comparing two elements, as if by
       
  5732      * {@link Boolean#compare(boolean, boolean)}, at an index within the
       
  5733      * respective arrays that is the prefix length.
       
  5734      * Otherwise, one array is a proper prefix of the other and, lexicographic
       
  5735      * comparison is the result of comparing the two array lengths.
       
  5736      * (See {@link #mismatch(boolean[], boolean[])} for the definition of a
       
  5737      * common and proper prefix.)
       
  5738      *
       
  5739      * <p>A {@code null} array reference is considered lexicographically less
       
  5740      * than a non-{@code null} array reference.  Two {@code null} array
       
  5741      * references are considered equal.
       
  5742      *
       
  5743      * <p>The comparison is consistent with {@link #equals(boolean[], boolean[]) equals},
       
  5744      * more specifically the following holds for arrays {@code a} and {@code b}:
       
  5745      * <pre>{@code
       
  5746      *     Arrays.equals(a, b) == (Arrays.compare(a, b) == 0)
       
  5747      * }</pre>
       
  5748      *
       
  5749      * @apiNote
       
  5750      * <p>This method behaves as if (for non-{@code null} array references):
       
  5751      * <pre>{@code
       
  5752      *     int i = Arrays.mismatch(a, b);
       
  5753      *     if (i >= 0 && i < Math.min(a.length, b.length))
       
  5754      *         return Boolean.compare(a[i], b[i]);
       
  5755      *     return a.length - b.length;
       
  5756      * }</pre>
       
  5757      *
       
  5758      * @param a the first array to compare
       
  5759      * @param b the second array to compare
       
  5760      * @return the value {@code 0} if the first and second array are equal and
       
  5761      *         contain the same elements in the same order;
       
  5762      *         a value less than {@code 0} if the first array is
       
  5763      *         lexicographically less than the second array; and
       
  5764      *         a value greater than {@code 0} if the first array is
       
  5765      *         lexicographically greater than the second array
       
  5766      * @since 9
       
  5767      */
       
  5768     public static int compare(boolean[] a, boolean[] b) {
       
  5769         if (a == b)
       
  5770             return 0;
       
  5771         if (a == null || b == null)
       
  5772             return a == null ? -1 : 1;
       
  5773 
       
  5774         int i = ArraysSupport.mismatch(a, b,
       
  5775                                        Math.min(a.length, b.length));
       
  5776         if (i >= 0) {
       
  5777             return Boolean.compare(a[i], b[i]);
       
  5778         }
       
  5779 
       
  5780         return a.length - b.length;
       
  5781     }
       
  5782 
       
  5783     /**
       
  5784      * Compares two {@code boolean} arrays lexicographically over the specified
       
  5785      * ranges.
       
  5786      *
       
  5787      * <p>If the two arrays, over the specified ranges, share a common prefix
       
  5788      * then the lexicographic comparison is the result of comparing two
       
  5789      * elements, as if by {@link Boolean#compare(boolean, boolean)}, at a
       
  5790      * relative index within the respective arrays that is the length of the
       
  5791      * prefix.
       
  5792      * Otherwise, one array is a proper prefix of the other and, lexicographic
       
  5793      * comparison is the result of comparing the two range lengths.
       
  5794      * (See {@link #mismatch(boolean[], int, int, boolean[], int, int)} for the
       
  5795      * definition of a common and proper prefix.)
       
  5796      *
       
  5797      * <p>The comparison is consistent with
       
  5798      * {@link #equals(boolean[], int, int, boolean[], int, int) equals}, more
       
  5799      * specifically the following holds for arrays {@code a} and {@code b} with
       
  5800      * specified ranges [{@code aFromIndex}, {@code atoIndex}) and
       
  5801      * [{@code bFromIndex}, {@code btoIndex}) respectively:
       
  5802      * <pre>{@code
       
  5803      *     Arrays.equals(a, aFromIndex, aToIndex, b, bFromIndex, bToIndex) ==
       
  5804      *         (Arrays.compare(a, aFromIndex, aToIndex, b, bFromIndex, bToIndex) == 0)
       
  5805      * }</pre>
       
  5806      *
       
  5807      * @apiNote
       
  5808      * <p>This method behaves as if:
       
  5809      * <pre>{@code
       
  5810      *     int i = Arrays.mismatch(a, aFromIndex, aToIndex,
       
  5811      *                             b, bFromIndex, bToIndex);
       
  5812      *     if (i >= 0 && i < Math.min(aToIndex - aFromIndex, bToIndex - bFromIndex))
       
  5813      *         return Boolean.compare(a[aFromIndex + i], b[bFromIndex + i]);
       
  5814      *     return (aToIndex - aFromIndex) - (bToIndex - bFromIndex);
       
  5815      * }</pre>
       
  5816      *
       
  5817      * @param a the first array to compare
       
  5818      * @param aFromIndex the index (inclusive) of the first element in the
       
  5819      *                   first array to be compared
       
  5820      * @param aToIndex the index (exclusive) of the last element in the
       
  5821      *                 first array to be compared
       
  5822      * @param b the second array to compare
       
  5823      * @param bFromIndex the index (inclusive) of the first element in the
       
  5824      *                   second array to be compared
       
  5825      * @param bToIndex the index (exclusive) of the last element in the
       
  5826      *                 second array to be compared
       
  5827      * @return the value {@code 0} if, over the specified ranges, the first and
       
  5828      *         second array are equal and contain the same elements in the same
       
  5829      *         order;
       
  5830      *         a value less than {@code 0} if, over the specified ranges, the
       
  5831      *         first array is lexicographically less than the second array; and
       
  5832      *         a value greater than {@code 0} if, over the specified ranges, the
       
  5833      *         first array is lexicographically greater than the second array
       
  5834      * @throws IllegalArgumentException
       
  5835      *         if {@code aFromIndex > aToIndex} or
       
  5836      *         if {@code bFromIndex > bToIndex}
       
  5837      * @throws ArrayIndexOutOfBoundsException
       
  5838      *         if {@code aFromIndex < 0 or aToIndex > a.length} or
       
  5839      *         if {@code bFromIndex < 0 or bToIndex > b.length}
       
  5840      * @throws NullPointerException
       
  5841      *         if either array is {@code null}
       
  5842      * @since 9
       
  5843      */
       
  5844     public static int compare(boolean[] a, int aFromIndex, int aToIndex,
       
  5845                               boolean[] b, int bFromIndex, int bToIndex) {
       
  5846         rangeCheck(a.length, aFromIndex, aToIndex);
       
  5847         rangeCheck(b.length, bFromIndex, bToIndex);
       
  5848 
       
  5849         int aLength = aToIndex - aFromIndex;
       
  5850         int bLength = bToIndex - bFromIndex;
       
  5851         int i = ArraysSupport.mismatch(a, aFromIndex,
       
  5852                                        b, bFromIndex,
       
  5853                                        Math.min(aLength, bLength));
       
  5854         if (i >= 0) {
       
  5855             return Boolean.compare(a[aFromIndex + i], b[bFromIndex + i]);
       
  5856         }
       
  5857 
       
  5858         return aLength - bLength;
       
  5859     }
       
  5860 
       
  5861     // Compare byte
       
  5862 
       
  5863     /**
       
  5864      * Compares two {@code byte} arrays lexicographically.
       
  5865      *
       
  5866      * <p>If the two arrays share a common prefix then the lexicographic
       
  5867      * comparison is the result of comparing two elements, as if by
       
  5868      * {@link Byte#compare(byte, byte)}, at an index within the respective
       
  5869      * arrays that is the prefix length.
       
  5870      * Otherwise, one array is a proper prefix of the other and, lexicographic
       
  5871      * comparison is the result of comparing the two array lengths.
       
  5872      * (See {@link #mismatch(byte[], byte[])} for the definition of a common and
       
  5873      * proper prefix.)
       
  5874      *
       
  5875      * <p>A {@code null} array reference is considered lexicographically less
       
  5876      * than a non-{@code null} array reference.  Two {@code null} array
       
  5877      * references are considered equal.
       
  5878      *
       
  5879      * <p>The comparison is consistent with {@link #equals(byte[], byte[]) equals},
       
  5880      * more specifically the following holds for arrays {@code a} and {@code b}:
       
  5881      * <pre>{@code
       
  5882      *     Arrays.equals(a, b) == (Arrays.compare(a, b) == 0)
       
  5883      * }</pre>
       
  5884      *
       
  5885      * @apiNote
       
  5886      * <p>This method behaves as if (for non-{@code null} array references):
       
  5887      * <pre>{@code
       
  5888      *     int i = Arrays.mismatch(a, b);
       
  5889      *     if (i >= 0 && i < Math.min(a.length, b.length))
       
  5890      *         return Byte.compare(a[i], b[i]);
       
  5891      *     return a.length - b.length;
       
  5892      * }</pre>
       
  5893      *
       
  5894      * @param a the first array to compare
       
  5895      * @param b the second array to compare
       
  5896      * @return the value {@code 0} if the first and second array are equal and
       
  5897      *         contain the same elements in the same order;
       
  5898      *         a value less than {@code 0} if the first array is
       
  5899      *         lexicographically less than the second array; and
       
  5900      *         a value greater than {@code 0} if the first array is
       
  5901      *         lexicographically greater than the second array
       
  5902      * @since 9
       
  5903      */
       
  5904     public static int compare(byte[] a, byte[] b) {
       
  5905         if (a == b)
       
  5906             return 0;
       
  5907         if (a == null || b == null)
       
  5908             return a == null ? -1 : 1;
       
  5909 
       
  5910         int i = ArraysSupport.mismatch(a, b,
       
  5911                                        Math.min(a.length, b.length));
       
  5912         if (i >= 0) {
       
  5913             return Byte.compare(a[i], b[i]);
       
  5914         }
       
  5915 
       
  5916         return a.length - b.length;
       
  5917     }
       
  5918 
       
  5919     /**
       
  5920      * Compares two {@code byte} arrays lexicographically over the specified
       
  5921      * ranges.
       
  5922      *
       
  5923      * <p>If the two arrays, over the specified ranges, share a common prefix
       
  5924      * then the lexicographic comparison is the result of comparing two
       
  5925      * elements, as if by {@link Byte#compare(byte, byte)}, at a relative index
       
  5926      * within the respective arrays that is the length of the prefix.
       
  5927      * Otherwise, one array is a proper prefix of the other and, lexicographic
       
  5928      * comparison is the result of comparing the two range lengths.
       
  5929      * (See {@link #mismatch(byte[], int, int, byte[], int, int)} for the
       
  5930      * definition of a common and proper prefix.)
       
  5931      *
       
  5932      * <p>The comparison is consistent with
       
  5933      * {@link #equals(byte[], int, int, byte[], int, int) equals}, more
       
  5934      * specifically the following holds for arrays {@code a} and {@code b} with
       
  5935      * specified ranges [{@code aFromIndex}, {@code atoIndex}) and
       
  5936      * [{@code bFromIndex}, {@code btoIndex}) respectively:
       
  5937      * <pre>{@code
       
  5938      *     Arrays.equals(a, aFromIndex, aToIndex, b, bFromIndex, bToIndex) ==
       
  5939      *         (Arrays.compare(a, aFromIndex, aToIndex, b, bFromIndex, bToIndex) == 0)
       
  5940      * }</pre>
       
  5941      *
       
  5942      * @apiNote
       
  5943      * <p>This method behaves as if:
       
  5944      * <pre>{@code
       
  5945      *     int i = Arrays.mismatch(a, aFromIndex, aToIndex,
       
  5946      *                             b, bFromIndex, bToIndex);
       
  5947      *     if (i >= 0 && i < Math.min(aToIndex - aFromIndex, bToIndex - bFromIndex))
       
  5948      *         return Byte.compare(a[aFromIndex + i], b[bFromIndex + i]);
       
  5949      *     return (aToIndex - aFromIndex) - (bToIndex - bFromIndex);
       
  5950      * }</pre>
       
  5951      *
       
  5952      * @param a the first array to compare
       
  5953      * @param aFromIndex the index (inclusive) of the first element in the
       
  5954      *                   first array to be compared
       
  5955      * @param aToIndex the index (exclusive) of the last element in the
       
  5956      *                 first array to be compared
       
  5957      * @param b the second array to compare
       
  5958      * @param bFromIndex the index (inclusive) of the first element in the
       
  5959      *                   second array to be compared
       
  5960      * @param bToIndex the index (exclusive) of the last element in the
       
  5961      *                 second array to be compared
       
  5962      * @return the value {@code 0} if, over the specified ranges, the first and
       
  5963      *         second array are equal and contain the same elements in the same
       
  5964      *         order;
       
  5965      *         a value less than {@code 0} if, over the specified ranges, the
       
  5966      *         first array is lexicographically less than the second array; and
       
  5967      *         a value greater than {@code 0} if, over the specified ranges, the
       
  5968      *         first array is lexicographically greater than the second array
       
  5969      * @throws IllegalArgumentException
       
  5970      *         if {@code aFromIndex > aToIndex} or
       
  5971      *         if {@code bFromIndex > bToIndex}
       
  5972      * @throws ArrayIndexOutOfBoundsException
       
  5973      *         if {@code aFromIndex < 0 or aToIndex > a.length} or
       
  5974      *         if {@code bFromIndex < 0 or bToIndex > b.length}
       
  5975      * @throws NullPointerException
       
  5976      *         if either array is {@code null}
       
  5977      * @since 9
       
  5978      */
       
  5979     public static int compare(byte[] a, int aFromIndex, int aToIndex,
       
  5980                               byte[] b, int bFromIndex, int bToIndex) {
       
  5981         rangeCheck(a.length, aFromIndex, aToIndex);
       
  5982         rangeCheck(b.length, bFromIndex, bToIndex);
       
  5983 
       
  5984         int aLength = aToIndex - aFromIndex;
       
  5985         int bLength = bToIndex - bFromIndex;
       
  5986         int i = ArraysSupport.mismatch(a, aFromIndex,
       
  5987                                        b, bFromIndex,
       
  5988                                        Math.min(aLength, bLength));
       
  5989         if (i >= 0) {
       
  5990             return Byte.compare(a[aFromIndex + i], b[bFromIndex + i]);
       
  5991         }
       
  5992 
       
  5993         return aLength - bLength;
       
  5994     }
       
  5995 
       
  5996     /**
       
  5997      * Compares two {@code byte} arrays lexicographically, numerically treating
       
  5998      * elements as unsigned.
       
  5999      *
       
  6000      * <p>If the two arrays share a common prefix then the lexicographic
       
  6001      * comparison is the result of comparing two elements, as if by
       
  6002      * {@link Byte#compareUnsigned(byte, byte)}, at an index within the
       
  6003      * respective arrays that is the prefix length.
       
  6004      * Otherwise, one array is a proper prefix of the other and, lexicographic
       
  6005      * comparison is the result of comparing the two array lengths.
       
  6006      * (See {@link #mismatch(byte[], byte[])} for the definition of a common
       
  6007      * and proper prefix.)
       
  6008      *
       
  6009      * <p>A {@code null} array reference is considered lexicographically less
       
  6010      * than a non-{@code null} array reference.  Two {@code null} array
       
  6011      * references are considered equal.
       
  6012      *
       
  6013      * @apiNote
       
  6014      * <p>This method behaves as if (for non-{@code null} array references):
       
  6015      * <pre>{@code
       
  6016      *     int i = Arrays.mismatch(a, b);
       
  6017      *     if (i >= 0 && i < Math.min(a.length, b.length))
       
  6018      *         return Byte.compareUnsigned(a[i], b[i]);
       
  6019      *     return a.length - b.length;
       
  6020      * }</pre>
       
  6021      *
       
  6022      * @param a the first array to compare
       
  6023      * @param b the second array to compare
       
  6024      * @return the value {@code 0} if the first and second array are
       
  6025      *         equal and contain the same elements in the same order;
       
  6026      *         a value less than {@code 0} if the first array is
       
  6027      *         lexicographically less than the second array; and
       
  6028      *         a value greater than {@code 0} if the first array is
       
  6029      *         lexicographically greater than the second array
       
  6030      * @since 9
       
  6031      */
       
  6032     public static int compareUnsigned(byte[] a, byte[] b) {
       
  6033         if (a == b)
       
  6034             return 0;
       
  6035         if (a == null || b == null)
       
  6036             return a == null ? -1 : 1;
       
  6037 
       
  6038         int i = ArraysSupport.mismatch(a, b,
       
  6039                                        Math.min(a.length, b.length));
       
  6040         if (i >= 0) {
       
  6041             return Byte.compareUnsigned(a[i], b[i]);
       
  6042         }
       
  6043 
       
  6044         return a.length - b.length;
       
  6045     }
       
  6046 
       
  6047 
       
  6048     /**
       
  6049      * Compares two {@code byte} arrays lexicographically over the specified
       
  6050      * ranges, numerically treating elements as unsigned.
       
  6051      *
       
  6052      * <p>If the two arrays, over the specified ranges, share a common prefix
       
  6053      * then the lexicographic comparison is the result of comparing two
       
  6054      * elements, as if by {@link Byte#compareUnsigned(byte, byte)}, at a
       
  6055      * relative index within the respective arrays that is the length of the
       
  6056      * prefix.
       
  6057      * Otherwise, one array is a proper prefix of the other and, lexicographic
       
  6058      * comparison is the result of comparing the two range lengths.
       
  6059      * (See {@link #mismatch(byte[], int, int, byte[], int, int)} for the
       
  6060      * definition of a common and proper prefix.)
       
  6061      *
       
  6062      * @apiNote
       
  6063      * <p>This method behaves as if:
       
  6064      * <pre>{@code
       
  6065      *     int i = Arrays.mismatch(a, aFromIndex, aToIndex,
       
  6066      *                             b, bFromIndex, bToIndex);
       
  6067      *     if (i >= 0 && i < Math.min(aToIndex - aFromIndex, bToIndex - bFromIndex))
       
  6068      *         return Byte.compareUnsigned(a[aFromIndex + i], b[bFromIndex + i]);
       
  6069      *     return (aToIndex - aFromIndex) - (bToIndex - bFromIndex);
       
  6070      * }</pre>
       
  6071      *
       
  6072      * @param a the first array to compare
       
  6073      * @param aFromIndex the index (inclusive) of the first element in the
       
  6074      *                   first array to be compared
       
  6075      * @param aToIndex the index (exclusive) of the last element in the
       
  6076      *                 first array to be compared
       
  6077      * @param b the second array to compare
       
  6078      * @param bFromIndex the index (inclusive) of the first element in the
       
  6079      *                   second array to be compared
       
  6080      * @param bToIndex the index (exclusive) of the last element in the
       
  6081      *                 second array to be compared
       
  6082      * @return the value {@code 0} if, over the specified ranges, the first and
       
  6083      *         second array are equal and contain the same elements in the same
       
  6084      *         order;
       
  6085      *         a value less than {@code 0} if, over the specified ranges, the
       
  6086      *         first array is lexicographically less than the second array; and
       
  6087      *         a value greater than {@code 0} if, over the specified ranges, the
       
  6088      *         first array is lexicographically greater than the second array
       
  6089      * @throws IllegalArgumentException
       
  6090      *         if {@code aFromIndex > aToIndex} or
       
  6091      *         if {@code bFromIndex > bToIndex}
       
  6092      * @throws ArrayIndexOutOfBoundsException
       
  6093      *         if {@code aFromIndex < 0 or aToIndex > a.length} or
       
  6094      *         if {@code bFromIndex < 0 or bToIndex > b.length}
       
  6095      * @throws NullPointerException
       
  6096      *         if either array is null
       
  6097      * @since 9
       
  6098      */
       
  6099     public static int compareUnsigned(byte[] a, int aFromIndex, int aToIndex,
       
  6100                                       byte[] b, int bFromIndex, int bToIndex) {
       
  6101         rangeCheck(a.length, aFromIndex, aToIndex);
       
  6102         rangeCheck(b.length, bFromIndex, bToIndex);
       
  6103 
       
  6104         int aLength = aToIndex - aFromIndex;
       
  6105         int bLength = bToIndex - bFromIndex;
       
  6106         int i = ArraysSupport.mismatch(a, aFromIndex,
       
  6107                                        b, bFromIndex,
       
  6108                                        Math.min(aLength, bLength));
       
  6109         if (i >= 0) {
       
  6110             return Byte.compareUnsigned(a[aFromIndex + i], b[bFromIndex + i]);
       
  6111         }
       
  6112 
       
  6113         return aLength - bLength;
       
  6114     }
       
  6115 
       
  6116     // Compare short
       
  6117 
       
  6118     /**
       
  6119      * Compares two {@code short} arrays lexicographically.
       
  6120      *
       
  6121      * <p>If the two arrays share a common prefix then the lexicographic
       
  6122      * comparison is the result of comparing two elements, as if by
       
  6123      * {@link Short#compare(short, short)}, at an index within the respective
       
  6124      * arrays that is the prefix length.
       
  6125      * Otherwise, one array is a proper prefix of the other and, lexicographic
       
  6126      * comparison is the result of comparing the two array lengths.
       
  6127      * (See {@link #mismatch(short[], short[])} for the definition of a common
       
  6128      * and proper prefix.)
       
  6129      *
       
  6130      * <p>A {@code null} array reference is considered lexicographically less
       
  6131      * than a non-{@code null} array reference.  Two {@code null} array
       
  6132      * references are considered equal.
       
  6133      *
       
  6134      * <p>The comparison is consistent with {@link #equals(short[], short[]) equals},
       
  6135      * more specifically the following holds for arrays {@code a} and {@code b}:
       
  6136      * <pre>{@code
       
  6137      *     Arrays.equals(a, b) == (Arrays.compare(a, b) == 0)
       
  6138      * }</pre>
       
  6139      *
       
  6140      * @apiNote
       
  6141      * <p>This method behaves as if (for non-{@code null} array references):
       
  6142      * <pre>{@code
       
  6143      *     int i = Arrays.mismatch(a, b);
       
  6144      *     if (i >= 0 && i < Math.min(a.length, b.length))
       
  6145      *         return Short.compare(a[i], b[i]);
       
  6146      *     return a.length - b.length;
       
  6147      * }</pre>
       
  6148      *
       
  6149      * @param a the first array to compare
       
  6150      * @param b the second array to compare
       
  6151      * @return the value {@code 0} if the first and second array are equal and
       
  6152      *         contain the same elements in the same order;
       
  6153      *         a value less than {@code 0} if the first array is
       
  6154      *         lexicographically less than the second array; and
       
  6155      *         a value greater than {@code 0} if the first array is
       
  6156      *         lexicographically greater than the second array
       
  6157      * @since 9
       
  6158      */
       
  6159     public static int compare(short[] a, short[] b) {
       
  6160         if (a == b)
       
  6161             return 0;
       
  6162         if (a == null || b == null)
       
  6163             return a == null ? -1 : 1;
       
  6164 
       
  6165         int i = ArraysSupport.mismatch(a, b,
       
  6166                                        Math.min(a.length, b.length));
       
  6167         if (i >= 0) {
       
  6168             return Short.compare(a[i], b[i]);
       
  6169         }
       
  6170 
       
  6171         return a.length - b.length;
       
  6172     }
       
  6173 
       
  6174     /**
       
  6175      * Compares two {@code short} arrays lexicographically over the specified
       
  6176      * ranges.
       
  6177      *
       
  6178      * <p>If the two arrays, over the specified ranges, share a common prefix
       
  6179      * then the lexicographic comparison is the result of comparing two
       
  6180      * elements, as if by {@link Short#compare(short, short)}, at a relative
       
  6181      * index within the respective arrays that is the length of the prefix.
       
  6182      * Otherwise, one array is a proper prefix of the other and, lexicographic
       
  6183      * comparison is the result of comparing the two range lengths.
       
  6184      * (See {@link #mismatch(short[], int, int, short[], int, int)} for the
       
  6185      * definition of a common and proper prefix.)
       
  6186      *
       
  6187      * <p>The comparison is consistent with
       
  6188      * {@link #equals(short[], int, int, short[], int, int) equals}, more
       
  6189      * specifically the following holds for arrays {@code a} and {@code b} with
       
  6190      * specified ranges [{@code aFromIndex}, {@code atoIndex}) and
       
  6191      * [{@code bFromIndex}, {@code btoIndex}) respectively:
       
  6192      * <pre>{@code
       
  6193      *     Arrays.equals(a, aFromIndex, aToIndex, b, bFromIndex, bToIndex) ==
       
  6194      *         (Arrays.compare(a, aFromIndex, aToIndex, b, bFromIndex, bToIndex) == 0)
       
  6195      * }</pre>
       
  6196      *
       
  6197      * @apiNote
       
  6198      * <p>This method behaves as if:
       
  6199      * <pre>{@code
       
  6200      *     int i = Arrays.mismatch(a, aFromIndex, aToIndex,
       
  6201      *                             b, bFromIndex, bToIndex);
       
  6202      *     if (i >= 0 && i < Math.min(aToIndex - aFromIndex, bToIndex - bFromIndex))
       
  6203      *         return Short.compare(a[aFromIndex + i], b[bFromIndex + i]);
       
  6204      *     return (aToIndex - aFromIndex) - (bToIndex - bFromIndex);
       
  6205      * }</pre>
       
  6206      *
       
  6207      * @param a the first array to compare
       
  6208      * @param aFromIndex the index (inclusive) of the first element in the
       
  6209      *                   first array to be compared
       
  6210      * @param aToIndex the index (exclusive) of the last element in the
       
  6211      *                 first array to be compared
       
  6212      * @param b the second array to compare
       
  6213      * @param bFromIndex the index (inclusive) of the first element in the
       
  6214      *                   second array to be compared
       
  6215      * @param bToIndex the index (exclusive) of the last element in the
       
  6216      *                 second array to be compared
       
  6217      * @return the value {@code 0} if, over the specified ranges, the first and
       
  6218      *         second array are equal and contain the same elements in the same
       
  6219      *         order;
       
  6220      *         a value less than {@code 0} if, over the specified ranges, the
       
  6221      *         first array is lexicographically less than the second array; and
       
  6222      *         a value greater than {@code 0} if, over the specified ranges, the
       
  6223      *         first array is lexicographically greater than the second array
       
  6224      * @throws IllegalArgumentException
       
  6225      *         if {@code aFromIndex > aToIndex} or
       
  6226      *         if {@code bFromIndex > bToIndex}
       
  6227      * @throws ArrayIndexOutOfBoundsException
       
  6228      *         if {@code aFromIndex < 0 or aToIndex > a.length} or
       
  6229      *         if {@code bFromIndex < 0 or bToIndex > b.length}
       
  6230      * @throws NullPointerException
       
  6231      *         if either array is {@code null}
       
  6232      * @since 9
       
  6233      */
       
  6234     public static int compare(short[] a, int aFromIndex, int aToIndex,
       
  6235                               short[] b, int bFromIndex, int bToIndex) {
       
  6236         rangeCheck(a.length, aFromIndex, aToIndex);
       
  6237         rangeCheck(b.length, bFromIndex, bToIndex);
       
  6238 
       
  6239         int aLength = aToIndex - aFromIndex;
       
  6240         int bLength = bToIndex - bFromIndex;
       
  6241         int i = ArraysSupport.mismatch(a, aFromIndex,
       
  6242                                        b, bFromIndex,
       
  6243                                        Math.min(aLength, bLength));
       
  6244         if (i >= 0) {
       
  6245             return Short.compare(a[aFromIndex + i], b[bFromIndex + i]);
       
  6246         }
       
  6247 
       
  6248         return aLength - bLength;
       
  6249     }
       
  6250 
       
  6251     /**
       
  6252      * Compares two {@code short} arrays lexicographically, numerically treating
       
  6253      * elements as unsigned.
       
  6254      *
       
  6255      * <p>If the two arrays share a common prefix then the lexicographic
       
  6256      * comparison is the result of comparing two elements, as if by
       
  6257      * {@link Short#compareUnsigned(short, short)}, at an index within the
       
  6258      * respective arrays that is the prefix length.
       
  6259      * Otherwise, one array is a proper prefix of the other and, lexicographic
       
  6260      * comparison is the result of comparing the two array lengths.
       
  6261      * (See {@link #mismatch(short[], short[])} for the definition of a common
       
  6262      * and proper prefix.)
       
  6263      *
       
  6264      * <p>A {@code null} array reference is considered lexicographically less
       
  6265      * than a non-{@code null} array reference.  Two {@code null} array
       
  6266      * references are considered equal.
       
  6267      *
       
  6268      * @apiNote
       
  6269      * <p>This method behaves as if (for non-{@code null} array references):
       
  6270      * <pre>{@code
       
  6271      *     int i = Arrays.mismatch(a, b);
       
  6272      *     if (i >= 0 && i < Math.min(a.length, b.length))
       
  6273      *         return Short.compareUnsigned(a[i], b[i]);
       
  6274      *     return a.length - b.length;
       
  6275      * }</pre>
       
  6276      *
       
  6277      * @param a the first array to compare
       
  6278      * @param b the second array to compare
       
  6279      * @return the value {@code 0} if the first and second array are
       
  6280      *         equal and contain the same elements in the same order;
       
  6281      *         a value less than {@code 0} if the first array is
       
  6282      *         lexicographically less than the second array; and
       
  6283      *         a value greater than {@code 0} if the first array is
       
  6284      *         lexicographically greater than the second array
       
  6285      * @since 9
       
  6286      */
       
  6287     public static int compareUnsigned(short[] a, short[] b) {
       
  6288         if (a == b)
       
  6289             return 0;
       
  6290         if (a == null || b == null)
       
  6291             return a == null ? -1 : 1;
       
  6292 
       
  6293         int i = ArraysSupport.mismatch(a, b,
       
  6294                                        Math.min(a.length, b.length));
       
  6295         if (i >= 0) {
       
  6296             return Short.compareUnsigned(a[i], b[i]);
       
  6297         }
       
  6298 
       
  6299         return a.length - b.length;
       
  6300     }
       
  6301 
       
  6302     /**
       
  6303      * Compares two {@code short} arrays lexicographically over the specified
       
  6304      * ranges, numerically treating elements as unsigned.
       
  6305      *
       
  6306      * <p>If the two arrays, over the specified ranges, share a common prefix
       
  6307      * then the lexicographic comparison is the result of comparing two
       
  6308      * elements, as if by {@link Short#compareUnsigned(short, short)}, at a
       
  6309      * relative index within the respective arrays that is the length of the
       
  6310      * prefix.
       
  6311      * Otherwise, one array is a proper prefix of the other and, lexicographic
       
  6312      * comparison is the result of comparing the two range lengths.
       
  6313      * (See {@link #mismatch(short[], int, int, short[], int, int)} for the
       
  6314      * definition of a common and proper prefix.)
       
  6315      *
       
  6316      * @apiNote
       
  6317      * <p>This method behaves as if:
       
  6318      * <pre>{@code
       
  6319      *     int i = Arrays.mismatch(a, aFromIndex, aToIndex,
       
  6320      *                             b, bFromIndex, bToIndex);
       
  6321      *     if (i >= 0 && i < Math.min(aToIndex - aFromIndex, bToIndex - bFromIndex))
       
  6322      *         return Short.compareUnsigned(a[aFromIndex + i], b[bFromIndex + i]);
       
  6323      *     return (aToIndex - aFromIndex) - (bToIndex - bFromIndex);
       
  6324      * }</pre>
       
  6325      *
       
  6326      * @param a the first array to compare
       
  6327      * @param aFromIndex the index (inclusive) of the first element in the
       
  6328      *                   first array to be compared
       
  6329      * @param aToIndex the index (exclusive) of the last element in the
       
  6330      *                 first array to be compared
       
  6331      * @param b the second array to compare
       
  6332      * @param bFromIndex the index (inclusive) of the first element in the
       
  6333      *                   second array to be compared
       
  6334      * @param bToIndex the index (exclusive) of the last element in the
       
  6335      *                 second array to be compared
       
  6336      * @return the value {@code 0} if, over the specified ranges, the first and
       
  6337      *         second array are equal and contain the same elements in the same
       
  6338      *         order;
       
  6339      *         a value less than {@code 0} if, over the specified ranges, the
       
  6340      *         first array is lexicographically less than the second array; and
       
  6341      *         a value greater than {@code 0} if, over the specified ranges, the
       
  6342      *         first array is lexicographically greater than the second array
       
  6343      * @throws IllegalArgumentException
       
  6344      *         if {@code aFromIndex > aToIndex} or
       
  6345      *         if {@code bFromIndex > bToIndex}
       
  6346      * @throws ArrayIndexOutOfBoundsException
       
  6347      *         if {@code aFromIndex < 0 or aToIndex > a.length} or
       
  6348      *         if {@code bFromIndex < 0 or bToIndex > b.length}
       
  6349      * @throws NullPointerException
       
  6350      *         if either array is null
       
  6351      * @since 9
       
  6352      */
       
  6353     public static int compareUnsigned(short[] a, int aFromIndex, int aToIndex,
       
  6354                                       short[] b, int bFromIndex, int bToIndex) {
       
  6355         rangeCheck(a.length, aFromIndex, aToIndex);
       
  6356         rangeCheck(b.length, bFromIndex, bToIndex);
       
  6357 
       
  6358         int aLength = aToIndex - aFromIndex;
       
  6359         int bLength = bToIndex - bFromIndex;
       
  6360         int i = ArraysSupport.mismatch(a, aFromIndex,
       
  6361                                        b, bFromIndex,
       
  6362                                        Math.min(aLength, bLength));
       
  6363         if (i >= 0) {
       
  6364             return Short.compareUnsigned(a[aFromIndex + i], b[bFromIndex + i]);
       
  6365         }
       
  6366 
       
  6367         return aLength - bLength;
       
  6368     }
       
  6369 
       
  6370     // Compare char
       
  6371 
       
  6372     /**
       
  6373      * Compares two {@code char} arrays lexicographically.
       
  6374      *
       
  6375      * <p>If the two arrays share a common prefix then the lexicographic
       
  6376      * comparison is the result of comparing two elements, as if by
       
  6377      * {@link Character#compare(char, char)}, at an index within the respective
       
  6378      * arrays that is the prefix length.
       
  6379      * Otherwise, one array is a proper prefix of the other and, lexicographic
       
  6380      * comparison is the result of comparing the two array lengths.
       
  6381      * (See {@link #mismatch(char[], char[])} for the definition of a common and
       
  6382      * proper prefix.)
       
  6383      *
       
  6384      * <p>A {@code null} array reference is considered lexicographically less
       
  6385      * than a non-{@code null} array reference.  Two {@code null} array
       
  6386      * references are considered equal.
       
  6387      *
       
  6388      * <p>The comparison is consistent with {@link #equals(char[], char[]) equals},
       
  6389      * more specifically the following holds for arrays {@code a} and {@code b}:
       
  6390      * <pre>{@code
       
  6391      *     Arrays.equals(a, b) == (Arrays.compare(a, b) == 0)
       
  6392      * }</pre>
       
  6393      *
       
  6394      * @apiNote
       
  6395      * <p>This method behaves as if (for non-{@code null} array references):
       
  6396      * <pre>{@code
       
  6397      *     int i = Arrays.mismatch(a, b);
       
  6398      *     if (i >= 0 && i < Math.min(a.length, b.length))
       
  6399      *         return Character.compare(a[i], b[i]);
       
  6400      *     return a.length - b.length;
       
  6401      * }</pre>
       
  6402      *
       
  6403      * @param a the first array to compare
       
  6404      * @param b the second array to compare
       
  6405      * @return the value {@code 0} if the first and second array are equal and
       
  6406      *         contain the same elements in the same order;
       
  6407      *         a value less than {@code 0} if the first array is
       
  6408      *         lexicographically less than the second array; and
       
  6409      *         a value greater than {@code 0} if the first array is
       
  6410      *         lexicographically greater than the second array
       
  6411      * @since 9
       
  6412      */
       
  6413     public static int compare(char[] a, char[] b) {
       
  6414         if (a == b)
       
  6415             return 0;
       
  6416         if (a == null || b == null)
       
  6417             return a == null ? -1 : 1;
       
  6418 
       
  6419         int i = ArraysSupport.mismatch(a, b,
       
  6420                                        Math.min(a.length, b.length));
       
  6421         if (i >= 0) {
       
  6422             return Character.compare(a[i], b[i]);
       
  6423         }
       
  6424 
       
  6425         return a.length - b.length;
       
  6426     }
       
  6427 
       
  6428     /**
       
  6429      * Compares two {@code char} arrays lexicographically over the specified
       
  6430      * ranges.
       
  6431      *
       
  6432      * <p>If the two arrays, over the specified ranges, share a common prefix
       
  6433      * then the lexicographic comparison is the result of comparing two
       
  6434      * elements, as if by {@link Character#compare(char, char)}, at a relative
       
  6435      * index within the respective arrays that is the length of the prefix.
       
  6436      * Otherwise, one array is a proper prefix of the other and, lexicographic
       
  6437      * comparison is the result of comparing the two range lengths.
       
  6438      * (See {@link #mismatch(char[], int, int, char[], int, int)} for the
       
  6439      * definition of a common and proper prefix.)
       
  6440      *
       
  6441      * <p>The comparison is consistent with
       
  6442      * {@link #equals(char[], int, int, char[], int, int) equals}, more
       
  6443      * specifically the following holds for arrays {@code a} and {@code b} with
       
  6444      * specified ranges [{@code aFromIndex}, {@code atoIndex}) and
       
  6445      * [{@code bFromIndex}, {@code btoIndex}) respectively:
       
  6446      * <pre>{@code
       
  6447      *     Arrays.equals(a, aFromIndex, aToIndex, b, bFromIndex, bToIndex) ==
       
  6448      *         (Arrays.compare(a, aFromIndex, aToIndex, b, bFromIndex, bToIndex) == 0)
       
  6449      * }</pre>
       
  6450      *
       
  6451      * @apiNote
       
  6452      * <p>This method behaves as if:
       
  6453      * <pre>{@code
       
  6454      *     int i = Arrays.mismatch(a, aFromIndex, aToIndex,
       
  6455      *                             b, bFromIndex, bToIndex);
       
  6456      *     if (i >= 0 && i < Math.min(aToIndex - aFromIndex, bToIndex - bFromIndex))
       
  6457      *         return Character.compare(a[aFromIndex + i], b[bFromIndex + i]);
       
  6458      *     return (aToIndex - aFromIndex) - (bToIndex - bFromIndex);
       
  6459      * }</pre>
       
  6460      *
       
  6461      * @param a the first array to compare
       
  6462      * @param aFromIndex the index (inclusive) of the first element in the
       
  6463      *                   first array to be compared
       
  6464      * @param aToIndex the index (exclusive) of the last element in the
       
  6465      *                 first array to be compared
       
  6466      * @param b the second array to compare
       
  6467      * @param bFromIndex the index (inclusive) of the first element in the
       
  6468      *                   second array to be compared
       
  6469      * @param bToIndex the index (exclusive) of the last element in the
       
  6470      *                 second array to be compared
       
  6471      * @return the value {@code 0} if, over the specified ranges, the first and
       
  6472      *         second array are equal and contain the same elements in the same
       
  6473      *         order;
       
  6474      *         a value less than {@code 0} if, over the specified ranges, the
       
  6475      *         first array is lexicographically less than the second array; and
       
  6476      *         a value greater than {@code 0} if, over the specified ranges, the
       
  6477      *         first array is lexicographically greater than the second array
       
  6478      * @throws IllegalArgumentException
       
  6479      *         if {@code aFromIndex > aToIndex} or
       
  6480      *         if {@code bFromIndex > bToIndex}
       
  6481      * @throws ArrayIndexOutOfBoundsException
       
  6482      *         if {@code aFromIndex < 0 or aToIndex > a.length} or
       
  6483      *         if {@code bFromIndex < 0 or bToIndex > b.length}
       
  6484      * @throws NullPointerException
       
  6485      *         if either array is {@code null}
       
  6486      * @since 9
       
  6487      */
       
  6488     public static int compare(char[] a, int aFromIndex, int aToIndex,
       
  6489                               char[] b, int bFromIndex, int bToIndex) {
       
  6490         rangeCheck(a.length, aFromIndex, aToIndex);
       
  6491         rangeCheck(b.length, bFromIndex, bToIndex);
       
  6492 
       
  6493         int aLength = aToIndex - aFromIndex;
       
  6494         int bLength = bToIndex - bFromIndex;
       
  6495         int i = ArraysSupport.mismatch(a, aFromIndex,
       
  6496                                        b, bFromIndex,
       
  6497                                        Math.min(aLength, bLength));
       
  6498         if (i >= 0) {
       
  6499             return Character.compare(a[aFromIndex + i], b[bFromIndex + i]);
       
  6500         }
       
  6501 
       
  6502         return aLength - bLength;
       
  6503     }
       
  6504 
       
  6505     // Compare int
       
  6506 
       
  6507     /**
       
  6508      * Compares two {@code int} arrays lexicographically.
       
  6509      *
       
  6510      * <p>If the two arrays share a common prefix then the lexicographic
       
  6511      * comparison is the result of comparing two elements, as if by
       
  6512      * {@link Integer#compare(int, int)}, at an index within the respective
       
  6513      * arrays that is the prefix length.
       
  6514      * Otherwise, one array is a proper prefix of the other and, lexicographic
       
  6515      * comparison is the result of comparing the two array lengths.
       
  6516      * (See {@link #mismatch(int[], int[])} for the definition of a common and
       
  6517      * proper prefix.)
       
  6518      *
       
  6519      * <p>A {@code null} array reference is considered lexicographically less
       
  6520      * than a non-{@code null} array reference.  Two {@code null} array
       
  6521      * references are considered equal.
       
  6522      *
       
  6523      * <p>The comparison is consistent with {@link #equals(int[], int[]) equals},
       
  6524      * more specifically the following holds for arrays {@code a} and {@code b}:
       
  6525      * <pre>{@code
       
  6526      *     Arrays.equals(a, b) == (Arrays.compare(a, b) == 0)
       
  6527      * }</pre>
       
  6528      *
       
  6529      * @apiNote
       
  6530      * <p>This method behaves as if (for non-{@code null} array references):
       
  6531      * <pre>{@code
       
  6532      *     int i = Arrays.mismatch(a, b);
       
  6533      *     if (i >= 0 && i < Math.min(a.length, b.length))
       
  6534      *         return Integer.compare(a[i], b[i]);
       
  6535      *     return a.length - b.length;
       
  6536      * }</pre>
       
  6537      *
       
  6538      * @param a the first array to compare
       
  6539      * @param b the second array to compare
       
  6540      * @return the value {@code 0} if the first and second array are equal and
       
  6541      *         contain the same elements in the same order;
       
  6542      *         a value less than {@code 0} if the first array is
       
  6543      *         lexicographically less than the second array; and
       
  6544      *         a value greater than {@code 0} if the first array is
       
  6545      *         lexicographically greater than the second array
       
  6546      * @since 9
       
  6547      */
       
  6548     public static int compare(int[] a, int[] b) {
       
  6549         if (a == b)
       
  6550             return 0;
       
  6551         if (a == null || b == null)
       
  6552             return a == null ? -1 : 1;
       
  6553 
       
  6554         int i = ArraysSupport.mismatch(a, b,
       
  6555                                        Math.min(a.length, b.length));
       
  6556         if (i >= 0) {
       
  6557             return Integer.compare(a[i], b[i]);
       
  6558         }
       
  6559 
       
  6560         return a.length - b.length;
       
  6561     }
       
  6562 
       
  6563     /**
       
  6564      * Compares two {@code int} arrays lexicographically over the specified
       
  6565      * ranges.
       
  6566      *
       
  6567      * <p>If the two arrays, over the specified ranges, share a common prefix
       
  6568      * then the lexicographic comparison is the result of comparing two
       
  6569      * elements, as if by {@link Integer#compare(int, int)}, at a relative index
       
  6570      * within the respective arrays that is the length of the prefix.
       
  6571      * Otherwise, one array is a proper prefix of the other and, lexicographic
       
  6572      * comparison is the result of comparing the two range lengths.
       
  6573      * (See {@link #mismatch(int[], int, int, int[], int, int)} for the
       
  6574      * definition of a common and proper prefix.)
       
  6575      *
       
  6576      * <p>The comparison is consistent with
       
  6577      * {@link #equals(int[], int, int, int[], int, int) equals}, more
       
  6578      * specifically the following holds for arrays {@code a} and {@code b} with
       
  6579      * specified ranges [{@code aFromIndex}, {@code atoIndex}) and
       
  6580      * [{@code bFromIndex}, {@code btoIndex}) respectively:
       
  6581      * <pre>{@code
       
  6582      *     Arrays.equals(a, aFromIndex, aToIndex, b, bFromIndex, bToIndex) ==
       
  6583      *         (Arrays.compare(a, aFromIndex, aToIndex, b, bFromIndex, bToIndex) == 0)
       
  6584      * }</pre>
       
  6585      *
       
  6586      * @apiNote
       
  6587      * <p>This method behaves as if:
       
  6588      * <pre>{@code
       
  6589      *     int i = Arrays.mismatch(a, aFromIndex, aToIndex,
       
  6590      *                             b, bFromIndex, bToIndex);
       
  6591      *     if (i >= 0 && i < Math.min(aToIndex - aFromIndex, bToIndex - bFromIndex))
       
  6592      *         return Integer.compare(a[aFromIndex + i], b[bFromIndex + i]);
       
  6593      *     return (aToIndex - aFromIndex) - (bToIndex - bFromIndex);
       
  6594      * }</pre>
       
  6595      *
       
  6596      * @param a the first array to compare
       
  6597      * @param aFromIndex the index (inclusive) of the first element in the
       
  6598      *                   first array to be compared
       
  6599      * @param aToIndex the index (exclusive) of the last element in the
       
  6600      *                 first array to be compared
       
  6601      * @param b the second array to compare
       
  6602      * @param bFromIndex the index (inclusive) of the first element in the
       
  6603      *                   second array to be compared
       
  6604      * @param bToIndex the index (exclusive) of the last element in the
       
  6605      *                 second array to be compared
       
  6606      * @return the value {@code 0} if, over the specified ranges, the first and
       
  6607      *         second array are equal and contain the same elements in the same
       
  6608      *         order;
       
  6609      *         a value less than {@code 0} if, over the specified ranges, the
       
  6610      *         first array is lexicographically less than the second array; and
       
  6611      *         a value greater than {@code 0} if, over the specified ranges, the
       
  6612      *         first array is lexicographically greater than the second array
       
  6613      * @throws IllegalArgumentException
       
  6614      *         if {@code aFromIndex > aToIndex} or
       
  6615      *         if {@code bFromIndex > bToIndex}
       
  6616      * @throws ArrayIndexOutOfBoundsException
       
  6617      *         if {@code aFromIndex < 0 or aToIndex > a.length} or
       
  6618      *         if {@code bFromIndex < 0 or bToIndex > b.length}
       
  6619      * @throws NullPointerException
       
  6620      *         if either array is {@code null}
       
  6621      * @since 9
       
  6622      */
       
  6623     public static int compare(int[] a, int aFromIndex, int aToIndex,
       
  6624                               int[] b, int bFromIndex, int bToIndex) {
       
  6625         rangeCheck(a.length, aFromIndex, aToIndex);
       
  6626         rangeCheck(b.length, bFromIndex, bToIndex);
       
  6627 
       
  6628         int aLength = aToIndex - aFromIndex;
       
  6629         int bLength = bToIndex - bFromIndex;
       
  6630         int i = ArraysSupport.mismatch(a, aFromIndex,
       
  6631                                        b, bFromIndex,
       
  6632                                        Math.min(aLength, bLength));
       
  6633         if (i >= 0) {
       
  6634             return Integer.compare(a[aFromIndex + i], b[bFromIndex + i]);
       
  6635         }
       
  6636 
       
  6637         return aLength - bLength;
       
  6638     }
       
  6639 
       
  6640     /**
       
  6641      * Compares two {@code int} arrays lexicographically, numerically treating
       
  6642      * elements as unsigned.
       
  6643      *
       
  6644      * <p>If the two arrays share a common prefix then the lexicographic
       
  6645      * comparison is the result of comparing two elements, as if by
       
  6646      * {@link Integer#compareUnsigned(int, int)}, at an index within the
       
  6647      * respective arrays that is the prefix length.
       
  6648      * Otherwise, one array is a proper prefix of the other and, lexicographic
       
  6649      * comparison is the result of comparing the two array lengths.
       
  6650      * (See {@link #mismatch(int[], int[])} for the definition of a common
       
  6651      * and proper prefix.)
       
  6652      *
       
  6653      * <p>A {@code null} array reference is considered lexicographically less
       
  6654      * than a non-{@code null} array reference.  Two {@code null} array
       
  6655      * references are considered equal.
       
  6656      *
       
  6657      * @apiNote
       
  6658      * <p>This method behaves as if (for non-{@code null} array references):
       
  6659      * <pre>{@code
       
  6660      *     int i = Arrays.mismatch(a, b);
       
  6661      *     if (i >= 0 && i < Math.min(a.length, b.length))
       
  6662      *         return Integer.compareUnsigned(a[i], b[i]);
       
  6663      *     return a.length - b.length;
       
  6664      * }</pre>
       
  6665      *
       
  6666      * @param a the first array to compare
       
  6667      * @param b the second array to compare
       
  6668      * @return the value {@code 0} if the first and second array are
       
  6669      *         equal and contain the same elements in the same order;
       
  6670      *         a value less than {@code 0} if the first array is
       
  6671      *         lexicographically less than the second array; and
       
  6672      *         a value greater than {@code 0} if the first array is
       
  6673      *         lexicographically greater than the second array
       
  6674      * @since 9
       
  6675      */
       
  6676     public static int compareUnsigned(int[] a, int[] b) {
       
  6677         if (a == b)
       
  6678             return 0;
       
  6679         if (a == null || b == null)
       
  6680             return a == null ? -1 : 1;
       
  6681 
       
  6682         int i = ArraysSupport.mismatch(a, b,
       
  6683                                        Math.min(a.length, b.length));
       
  6684         if (i >= 0) {
       
  6685             return Integer.compareUnsigned(a[i], b[i]);
       
  6686         }
       
  6687 
       
  6688         return a.length - b.length;
       
  6689     }
       
  6690 
       
  6691     /**
       
  6692      * Compares two {@code int} arrays lexicographically over the specified
       
  6693      * ranges, numerically treating elements as unsigned.
       
  6694      *
       
  6695      * <p>If the two arrays, over the specified ranges, share a common prefix
       
  6696      * then the lexicographic comparison is the result of comparing two
       
  6697      * elements, as if by {@link Integer#compareUnsigned(int, int)}, at a
       
  6698      * relative index within the respective arrays that is the length of the
       
  6699      * prefix.
       
  6700      * Otherwise, one array is a proper prefix of the other and, lexicographic
       
  6701      * comparison is the result of comparing the two range lengths.
       
  6702      * (See {@link #mismatch(int[], int, int, int[], int, int)} for the
       
  6703      * definition of a common and proper prefix.)
       
  6704      *
       
  6705      * @apiNote
       
  6706      * <p>This method behaves as if:
       
  6707      * <pre>{@code
       
  6708      *     int i = Arrays.mismatch(a, aFromIndex, aToIndex,
       
  6709      *                             b, bFromIndex, bToIndex);
       
  6710      *     if (i >= 0 && i < Math.min(aToIndex - aFromIndex, bToIndex - bFromIndex))
       
  6711      *         return Integer.compareUnsigned(a[aFromIndex + i], b[bFromIndex + i]);
       
  6712      *     return (aToIndex - aFromIndex) - (bToIndex - bFromIndex);
       
  6713      * }</pre>
       
  6714      *
       
  6715      * @param a the first array to compare
       
  6716      * @param aFromIndex the index (inclusive) of the first element in the
       
  6717      *                   first array to be compared
       
  6718      * @param aToIndex the index (exclusive) of the last element in the
       
  6719      *                 first array to be compared
       
  6720      * @param b the second array to compare
       
  6721      * @param bFromIndex the index (inclusive) of the first element in the
       
  6722      *                   second array to be compared
       
  6723      * @param bToIndex the index (exclusive) of the last element in the
       
  6724      *                 second array to be compared
       
  6725      * @return the value {@code 0} if, over the specified ranges, the first and
       
  6726      *         second array are equal and contain the same elements in the same
       
  6727      *         order;
       
  6728      *         a value less than {@code 0} if, over the specified ranges, the
       
  6729      *         first array is lexicographically less than the second array; and
       
  6730      *         a value greater than {@code 0} if, over the specified ranges, the
       
  6731      *         first array is lexicographically greater than the second array
       
  6732      * @throws IllegalArgumentException
       
  6733      *         if {@code aFromIndex > aToIndex} or
       
  6734      *         if {@code bFromIndex > bToIndex}
       
  6735      * @throws ArrayIndexOutOfBoundsException
       
  6736      *         if {@code aFromIndex < 0 or aToIndex > a.length} or
       
  6737      *         if {@code bFromIndex < 0 or bToIndex > b.length}
       
  6738      * @throws NullPointerException
       
  6739      *         if either array is null
       
  6740      * @since 9
       
  6741      */
       
  6742     public static int compareUnsigned(int[] a, int aFromIndex, int aToIndex,
       
  6743                                       int[] b, int bFromIndex, int bToIndex) {
       
  6744         rangeCheck(a.length, aFromIndex, aToIndex);
       
  6745         rangeCheck(b.length, bFromIndex, bToIndex);
       
  6746 
       
  6747         int aLength = aToIndex - aFromIndex;
       
  6748         int bLength = bToIndex - bFromIndex;
       
  6749         int i = ArraysSupport.mismatch(a, aFromIndex,
       
  6750                                        b, bFromIndex,
       
  6751                                        Math.min(aLength, bLength));
       
  6752         if (i >= 0) {
       
  6753             return Integer.compareUnsigned(a[aFromIndex + i], b[bFromIndex + i]);
       
  6754         }
       
  6755 
       
  6756         return aLength - bLength;
       
  6757     }
       
  6758 
       
  6759     // Compare long
       
  6760 
       
  6761     /**
       
  6762      * Compares two {@code long} arrays lexicographically.
       
  6763      *
       
  6764      * <p>If the two arrays share a common prefix then the lexicographic
       
  6765      * comparison is the result of comparing two elements, as if by
       
  6766      * {@link Long#compare(long, long)}, at an index within the respective
       
  6767      * arrays that is the prefix length.
       
  6768      * Otherwise, one array is a proper prefix of the other and, lexicographic
       
  6769      * comparison is the result of comparing the two array lengths.
       
  6770      * (See {@link #mismatch(long[], long[])} for the definition of a common and
       
  6771      * proper prefix.)
       
  6772      *
       
  6773      * <p>A {@code null} array reference is considered lexicographically less
       
  6774      * than a non-{@code null} array reference.  Two {@code null} array
       
  6775      * references are considered equal.
       
  6776      *
       
  6777      * <p>The comparison is consistent with {@link #equals(long[], long[]) equals},
       
  6778      * more specifically the following holds for arrays {@code a} and {@code b}:
       
  6779      * <pre>{@code
       
  6780      *     Arrays.equals(a, b) == (Arrays.compare(a, b) == 0)
       
  6781      * }</pre>
       
  6782      *
       
  6783      * @apiNote
       
  6784      * <p>This method behaves as if (for non-{@code null} array references):
       
  6785      * <pre>{@code
       
  6786      *     int i = Arrays.mismatch(a, b);
       
  6787      *     if (i >= 0 && i < Math.min(a.length, b.length))
       
  6788      *         return Long.compare(a[i], b[i]);
       
  6789      *     return a.length - b.length;
       
  6790      * }</pre>
       
  6791      *
       
  6792      * @param a the first array to compare
       
  6793      * @param b the second array to compare
       
  6794      * @return the value {@code 0} if the first and second array are equal and
       
  6795      *         contain the same elements in the same order;
       
  6796      *         a value less than {@code 0} if the first array is
       
  6797      *         lexicographically less than the second array; and
       
  6798      *         a value greater than {@code 0} if the first array is
       
  6799      *         lexicographically greater than the second array
       
  6800      * @since 9
       
  6801      */
       
  6802     public static int compare(long[] a, long[] b) {
       
  6803         if (a == b)
       
  6804             return 0;
       
  6805         if (a == null || b == null)
       
  6806             return a == null ? -1 : 1;
       
  6807 
       
  6808         int i = ArraysSupport.mismatch(a, b,
       
  6809                                        Math.min(a.length, b.length));
       
  6810         if (i >= 0) {
       
  6811             return Long.compare(a[i], b[i]);
       
  6812         }
       
  6813 
       
  6814         return a.length - b.length;
       
  6815     }
       
  6816 
       
  6817     /**
       
  6818      * Compares two {@code long} arrays lexicographically over the specified
       
  6819      * ranges.
       
  6820      *
       
  6821      * <p>If the two arrays, over the specified ranges, share a common prefix
       
  6822      * then the lexicographic comparison is the result of comparing two
       
  6823      * elements, as if by {@link Long#compare(long, long)}, at a relative index
       
  6824      * within the respective arrays that is the length of the prefix.
       
  6825      * Otherwise, one array is a proper prefix of the other and, lexicographic
       
  6826      * comparison is the result of comparing the two range lengths.
       
  6827      * (See {@link #mismatch(long[], int, int, long[], int, int)} for the
       
  6828      * definition of a common and proper prefix.)
       
  6829      *
       
  6830      * <p>The comparison is consistent with
       
  6831      * {@link #equals(long[], int, int, long[], int, int) equals}, more
       
  6832      * specifically the following holds for arrays {@code a} and {@code b} with
       
  6833      * specified ranges [{@code aFromIndex}, {@code atoIndex}) and
       
  6834      * [{@code bFromIndex}, {@code btoIndex}) respectively:
       
  6835      * <pre>{@code
       
  6836      *     Arrays.equals(a, aFromIndex, aToIndex, b, bFromIndex, bToIndex) ==
       
  6837      *         (Arrays.compare(a, aFromIndex, aToIndex, b, bFromIndex, bToIndex) == 0)
       
  6838      * }</pre>
       
  6839      *
       
  6840      * @apiNote
       
  6841      * <p>This method behaves as if:
       
  6842      * <pre>{@code
       
  6843      *     int i = Arrays.mismatch(a, aFromIndex, aToIndex,
       
  6844      *                             b, bFromIndex, bToIndex);
       
  6845      *     if (i >= 0 && i < Math.min(aToIndex - aFromIndex, bToIndex - bFromIndex))
       
  6846      *         return Long.compare(a[aFromIndex + i], b[bFromIndex + i]);
       
  6847      *     return (aToIndex - aFromIndex) - (bToIndex - bFromIndex);
       
  6848      * }</pre>
       
  6849      *
       
  6850      * @param a the first array to compare
       
  6851      * @param aFromIndex the index (inclusive) of the first element in the
       
  6852      *                   first array to be compared
       
  6853      * @param aToIndex the index (exclusive) of the last element in the
       
  6854      *                 first array to be compared
       
  6855      * @param b the second array to compare
       
  6856      * @param bFromIndex the index (inclusive) of the first element in the
       
  6857      *                   second array to be compared
       
  6858      * @param bToIndex the index (exclusive) of the last element in the
       
  6859      *                 second array to be compared
       
  6860      * @return the value {@code 0} if, over the specified ranges, the first and
       
  6861      *         second array are equal and contain the same elements in the same
       
  6862      *         order;
       
  6863      *         a value less than {@code 0} if, over the specified ranges, the
       
  6864      *         first array is lexicographically less than the second array; and
       
  6865      *         a value greater than {@code 0} if, over the specified ranges, the
       
  6866      *         first array is lexicographically greater than the second array
       
  6867      * @throws IllegalArgumentException
       
  6868      *         if {@code aFromIndex > aToIndex} or
       
  6869      *         if {@code bFromIndex > bToIndex}
       
  6870      * @throws ArrayIndexOutOfBoundsException
       
  6871      *         if {@code aFromIndex < 0 or aToIndex > a.length} or
       
  6872      *         if {@code bFromIndex < 0 or bToIndex > b.length}
       
  6873      * @throws NullPointerException
       
  6874      *         if either array is {@code null}
       
  6875      * @since 9
       
  6876      */
       
  6877     public static int compare(long[] a, int aFromIndex, int aToIndex,
       
  6878                               long[] b, int bFromIndex, int bToIndex) {
       
  6879         rangeCheck(a.length, aFromIndex, aToIndex);
       
  6880         rangeCheck(b.length, bFromIndex, bToIndex);
       
  6881 
       
  6882         int aLength = aToIndex - aFromIndex;
       
  6883         int bLength = bToIndex - bFromIndex;
       
  6884         int i = ArraysSupport.mismatch(a, aFromIndex,
       
  6885                                        b, bFromIndex,
       
  6886                                        Math.min(aLength, bLength));
       
  6887         if (i >= 0) {
       
  6888             return Long.compare(a[aFromIndex + i], b[bFromIndex + i]);
       
  6889         }
       
  6890 
       
  6891         return aLength - bLength;
       
  6892     }
       
  6893 
       
  6894     /**
       
  6895      * Compares two {@code long} arrays lexicographically, numerically treating
       
  6896      * elements as unsigned.
       
  6897      *
       
  6898      * <p>If the two arrays share a common prefix then the lexicographic
       
  6899      * comparison is the result of comparing two elements, as if by
       
  6900      * {@link Long#compareUnsigned(long, long)}, at an index within the
       
  6901      * respective arrays that is the prefix length.
       
  6902      * Otherwise, one array is a proper prefix of the other and, lexicographic
       
  6903      * comparison is the result of comparing the two array lengths.
       
  6904      * (See {@link #mismatch(long[], long[])} for the definition of a common
       
  6905      * and proper prefix.)
       
  6906      *
       
  6907      * <p>A {@code null} array reference is considered lexicographically less
       
  6908      * than a non-{@code null} array reference.  Two {@code null} array
       
  6909      * references are considered equal.
       
  6910      *
       
  6911      * @apiNote
       
  6912      * <p>This method behaves as if (for non-{@code null} array references):
       
  6913      * <pre>{@code
       
  6914      *     int i = Arrays.mismatch(a, b);
       
  6915      *     if (i >= 0 && i < Math.min(a.length, b.length))
       
  6916      *         return Long.compareUnsigned(a[i], b[i]);
       
  6917      *     return a.length - b.length;
       
  6918      * }</pre>
       
  6919      *
       
  6920      * @param a the first array to compare
       
  6921      * @param b the second array to compare
       
  6922      * @return the value {@code 0} if the first and second array are
       
  6923      *         equal and contain the same elements in the same order;
       
  6924      *         a value less than {@code 0} if the first array is
       
  6925      *         lexicographically less than the second array; and
       
  6926      *         a value greater than {@code 0} if the first array is
       
  6927      *         lexicographically greater than the second array
       
  6928      * @since 9
       
  6929      */
       
  6930     public static int compareUnsigned(long[] a, long[] b) {
       
  6931         if (a == b)
       
  6932             return 0;
       
  6933         if (a == null || b == null)
       
  6934             return a == null ? -1 : 1;
       
  6935 
       
  6936         int i = ArraysSupport.mismatch(a, b,
       
  6937                                        Math.min(a.length, b.length));
       
  6938         if (i >= 0) {
       
  6939             return Long.compareUnsigned(a[i], b[i]);
       
  6940         }
       
  6941 
       
  6942         return a.length - b.length;
       
  6943     }
       
  6944 
       
  6945     /**
       
  6946      * Compares two {@code long} arrays lexicographically over the specified
       
  6947      * ranges, numerically treating elements as unsigned.
       
  6948      *
       
  6949      * <p>If the two arrays, over the specified ranges, share a common prefix
       
  6950      * then the lexicographic comparison is the result of comparing two
       
  6951      * elements, as if by {@link Long#compareUnsigned(long, long)}, at a
       
  6952      * relative index within the respective arrays that is the length of the
       
  6953      * prefix.
       
  6954      * Otherwise, one array is a proper prefix of the other and, lexicographic
       
  6955      * comparison is the result of comparing the two range lengths.
       
  6956      * (See {@link #mismatch(long[], int, int, long[], int, int)} for the
       
  6957      * definition of a common and proper prefix.)
       
  6958      *
       
  6959      * @apiNote
       
  6960      * <p>This method behaves as if:
       
  6961      * <pre>{@code
       
  6962      *     int i = Arrays.mismatch(a, aFromIndex, aToIndex,
       
  6963      *                             b, bFromIndex, bToIndex);
       
  6964      *     if (i >= 0 && i < Math.min(aToIndex - aFromIndex, bToIndex - bFromIndex))
       
  6965      *         return Long.compareUnsigned(a[aFromIndex + i], b[bFromIndex + i]);
       
  6966      *     return (aToIndex - aFromIndex) - (bToIndex - bFromIndex);
       
  6967      * }</pre>
       
  6968      *
       
  6969      * @param a the first array to compare
       
  6970      * @param aFromIndex the index (inclusive) of the first element in the
       
  6971      *                   first array to be compared
       
  6972      * @param aToIndex the index (exclusive) of the last element in the
       
  6973      *                 first array to be compared
       
  6974      * @param b the second array to compare
       
  6975      * @param bFromIndex the index (inclusive) of the first element in the
       
  6976      *                   second array to be compared
       
  6977      * @param bToIndex the index (exclusive) of the last element in the
       
  6978      *                 second array to be compared
       
  6979      * @return the value {@code 0} if, over the specified ranges, the first and
       
  6980      *         second array are equal and contain the same elements in the same
       
  6981      *         order;
       
  6982      *         a value less than {@code 0} if, over the specified ranges, the
       
  6983      *         first array is lexicographically less than the second array; and
       
  6984      *         a value greater than {@code 0} if, over the specified ranges, the
       
  6985      *         first array is lexicographically greater than the second array
       
  6986      * @throws IllegalArgumentException
       
  6987      *         if {@code aFromIndex > aToIndex} or
       
  6988      *         if {@code bFromIndex > bToIndex}
       
  6989      * @throws ArrayIndexOutOfBoundsException
       
  6990      *         if {@code aFromIndex < 0 or aToIndex > a.length} or
       
  6991      *         if {@code bFromIndex < 0 or bToIndex > b.length}
       
  6992      * @throws NullPointerException
       
  6993      *         if either array is null
       
  6994      * @since 9
       
  6995      */
       
  6996     public static int compareUnsigned(long[] a, int aFromIndex, int aToIndex,
       
  6997                                       long[] b, int bFromIndex, int bToIndex) {
       
  6998         rangeCheck(a.length, aFromIndex, aToIndex);
       
  6999         rangeCheck(b.length, bFromIndex, bToIndex);
       
  7000 
       
  7001         int aLength = aToIndex - aFromIndex;
       
  7002         int bLength = bToIndex - bFromIndex;
       
  7003         int i = ArraysSupport.mismatch(a, aFromIndex,
       
  7004                                        b, bFromIndex,
       
  7005                                        Math.min(aLength, bLength));
       
  7006         if (i >= 0) {
       
  7007             return Long.compareUnsigned(a[aFromIndex + i], b[bFromIndex + i]);
       
  7008         }
       
  7009 
       
  7010         return aLength - bLength;
       
  7011     }
       
  7012 
       
  7013     // Compare float
       
  7014 
       
  7015     /**
       
  7016      * Compares two {@code float} arrays lexicographically.
       
  7017      *
       
  7018      * <p>If the two arrays share a common prefix then the lexicographic
       
  7019      * comparison is the result of comparing two elements, as if by
       
  7020      * {@link Float#compare(float, float)}, at an index within the respective
       
  7021      * arrays that is the prefix length.
       
  7022      * Otherwise, one array is a proper prefix of the other and, lexicographic
       
  7023      * comparison is the result of comparing the two array lengths.
       
  7024      * (See {@link #mismatch(float[], float[])} for the definition of a common
       
  7025      * and proper prefix.)
       
  7026      *
       
  7027      * <p>A {@code null} array reference is considered lexicographically less
       
  7028      * than a non-{@code null} array reference.  Two {@code null} array
       
  7029      * references are considered equal.
       
  7030      *
       
  7031      * <p>The comparison is consistent with {@link #equals(float[], float[]) equals},
       
  7032      * more specifically the following holds for arrays {@code a} and {@code b}:
       
  7033      * <pre>{@code
       
  7034      *     Arrays.equals(a, b) == (Arrays.compare(a, b) == 0)
       
  7035      * }</pre>
       
  7036      *
       
  7037      * @apiNote
       
  7038      * <p>This method behaves as if (for non-{@code null} array references):
       
  7039      * <pre>{@code
       
  7040      *     int i = Arrays.mismatch(a, b);
       
  7041      *     if (i >= 0 && i < Math.min(a.length, b.length))
       
  7042      *         return Float.compare(a[i], b[i]);
       
  7043      *     return a.length - b.length;
       
  7044      * }</pre>
       
  7045      *
       
  7046      * @param a the first array to compare
       
  7047      * @param b the second array to compare
       
  7048      * @return the value {@code 0} if the first and second array are equal and
       
  7049      *         contain the same elements in the same order;
       
  7050      *         a value less than {@code 0} if the first array is
       
  7051      *         lexicographically less than the second array; and
       
  7052      *         a value greater than {@code 0} if the first array is
       
  7053      *         lexicographically greater than the second array
       
  7054      * @since 9
       
  7055      */
       
  7056     public static int compare(float[] a, float[] b) {
       
  7057         if (a == b)
       
  7058             return 0;
       
  7059         if (a == null || b == null)
       
  7060             return a == null ? -1 : 1;
       
  7061 
       
  7062         int i = ArraysSupport.mismatch(a, b,
       
  7063                                        Math.min(a.length, b.length));
       
  7064         if (i >= 0) {
       
  7065             return Float.compare(a[i], b[i]);
       
  7066         }
       
  7067 
       
  7068         return a.length - b.length;
       
  7069     }
       
  7070 
       
  7071     /**
       
  7072      * Compares two {@code float} arrays lexicographically over the specified
       
  7073      * ranges.
       
  7074      *
       
  7075      * <p>If the two arrays, over the specified ranges, share a common prefix
       
  7076      * then the lexicographic comparison is the result of comparing two
       
  7077      * elements, as if by {@link Float#compare(float, float)}, at a relative
       
  7078      * index within the respective arrays that is the length of the prefix.
       
  7079      * Otherwise, one array is a proper prefix of the other and, lexicographic
       
  7080      * comparison is the result of comparing the two range lengths.
       
  7081      * (See {@link #mismatch(float[], int, int, float[], int, int)} for the
       
  7082      * definition of a common and proper prefix.)
       
  7083      *
       
  7084      * <p>The comparison is consistent with
       
  7085      * {@link #equals(float[], int, int, float[], int, int) equals}, more
       
  7086      * specifically the following holds for arrays {@code a} and {@code b} with
       
  7087      * specified ranges [{@code aFromIndex}, {@code atoIndex}) and
       
  7088      * [{@code bFromIndex}, {@code btoIndex}) respectively:
       
  7089      * <pre>{@code
       
  7090      *     Arrays.equals(a, aFromIndex, aToIndex, b, bFromIndex, bToIndex) ==
       
  7091      *         (Arrays.compare(a, aFromIndex, aToIndex, b, bFromIndex, bToIndex) == 0)
       
  7092      * }</pre>
       
  7093      *
       
  7094      * @apiNote
       
  7095      * <p>This method behaves as if:
       
  7096      * <pre>{@code
       
  7097      *     int i = Arrays.mismatch(a, aFromIndex, aToIndex,
       
  7098      *                             b, bFromIndex, bToIndex);
       
  7099      *     if (i >= 0 && i < Math.min(aToIndex - aFromIndex, bToIndex - bFromIndex))
       
  7100      *         return Float.compare(a[aFromIndex + i], b[bFromIndex + i]);
       
  7101      *     return (aToIndex - aFromIndex) - (bToIndex - bFromIndex);
       
  7102      * }</pre>
       
  7103      *
       
  7104      * @param a the first array to compare
       
  7105      * @param aFromIndex the index (inclusive) of the first element in the
       
  7106      *                   first array to be compared
       
  7107      * @param aToIndex the index (exclusive) of the last element in the
       
  7108      *                 first array to be compared
       
  7109      * @param b the second array to compare
       
  7110      * @param bFromIndex the index (inclusive) of the first element in the
       
  7111      *                   second array to be compared
       
  7112      * @param bToIndex the index (exclusive) of the last element in the
       
  7113      *                 second array to be compared
       
  7114      * @return the value {@code 0} if, over the specified ranges, the first and
       
  7115      *         second array are equal and contain the same elements in the same
       
  7116      *         order;
       
  7117      *         a value less than {@code 0} if, over the specified ranges, the
       
  7118      *         first array is lexicographically less than the second array; and
       
  7119      *         a value greater than {@code 0} if, over the specified ranges, the
       
  7120      *         first array is lexicographically greater than the second array
       
  7121      * @throws IllegalArgumentException
       
  7122      *         if {@code aFromIndex > aToIndex} or
       
  7123      *         if {@code bFromIndex > bToIndex}
       
  7124      * @throws ArrayIndexOutOfBoundsException
       
  7125      *         if {@code aFromIndex < 0 or aToIndex > a.length} or
       
  7126      *         if {@code bFromIndex < 0 or bToIndex > b.length}
       
  7127      * @throws NullPointerException
       
  7128      *         if either array is {@code null}
       
  7129      * @since 9
       
  7130      */
       
  7131     public static int compare(float[] a, int aFromIndex, int aToIndex,
       
  7132                               float[] b, int bFromIndex, int bToIndex) {
       
  7133         rangeCheck(a.length, aFromIndex, aToIndex);
       
  7134         rangeCheck(b.length, bFromIndex, bToIndex);
       
  7135 
       
  7136         int aLength = aToIndex - aFromIndex;
       
  7137         int bLength = bToIndex - bFromIndex;
       
  7138         int i = ArraysSupport.mismatch(a, aFromIndex,
       
  7139                                        b, bFromIndex,
       
  7140                                        Math.min(aLength, bLength));
       
  7141         if (i >= 0) {
       
  7142             return Float.compare(a[aFromIndex + i], b[bFromIndex + i]);
       
  7143         }
       
  7144 
       
  7145         return aLength - bLength;
       
  7146     }
       
  7147 
       
  7148     // Compare double
       
  7149 
       
  7150     /**
       
  7151      * Compares two {@code double} arrays lexicographically.
       
  7152      *
       
  7153      * <p>If the two arrays share a common prefix then the lexicographic
       
  7154      * comparison is the result of comparing two elements, as if by
       
  7155      * {@link Double#compare(double, double)}, at an index within the respective
       
  7156      * arrays that is the prefix length.
       
  7157      * Otherwise, one array is a proper prefix of the other and, lexicographic
       
  7158      * comparison is the result of comparing the two array lengths.
       
  7159      * (See {@link #mismatch(double[], double[])} for the definition of a common
       
  7160      * and proper prefix.)
       
  7161      *
       
  7162      * <p>A {@code null} array reference is considered lexicographically less
       
  7163      * than a non-{@code null} array reference.  Two {@code null} array
       
  7164      * references are considered equal.
       
  7165      *
       
  7166      * <p>The comparison is consistent with {@link #equals(double[], double[]) equals},
       
  7167      * more specifically the following holds for arrays {@code a} and {@code b}:
       
  7168      * <pre>{@code
       
  7169      *     Arrays.equals(a, b) == (Arrays.compare(a, b) == 0)
       
  7170      * }</pre>
       
  7171      *
       
  7172      * @apiNote
       
  7173      * <p>This method behaves as if (for non-{@code null} array references):
       
  7174      * <pre>{@code
       
  7175      *     int i = Arrays.mismatch(a, b);
       
  7176      *     if (i >= 0 && i < Math.min(a.length, b.length))
       
  7177      *         return Double.compare(a[i], b[i]);
       
  7178      *     return a.length - b.length;
       
  7179      * }</pre>
       
  7180      *
       
  7181      * @param a the first array to compare
       
  7182      * @param b the second array to compare
       
  7183      * @return the value {@code 0} if the first and second array are equal and
       
  7184      *         contain the same elements in the same order;
       
  7185      *         a value less than {@code 0} if the first array is
       
  7186      *         lexicographically less than the second array; and
       
  7187      *         a value greater than {@code 0} if the first array is
       
  7188      *         lexicographically greater than the second array
       
  7189      * @since 9
       
  7190      */
       
  7191     public static int compare(double[] a, double[] b) {
       
  7192         if (a == b)
       
  7193             return 0;
       
  7194         if (a == null || b == null)
       
  7195             return a == null ? -1 : 1;
       
  7196 
       
  7197         int i = ArraysSupport.mismatch(a, b,
       
  7198                                        Math.min(a.length, b.length));
       
  7199         if (i >= 0) {
       
  7200             return Double.compare(a[i], b[i]);
       
  7201         }
       
  7202 
       
  7203         return a.length - b.length;
       
  7204     }
       
  7205 
       
  7206     /**
       
  7207      * Compares two {@code double} arrays lexicographically over the specified
       
  7208      * ranges.
       
  7209      *
       
  7210      * <p>If the two arrays, over the specified ranges, share a common prefix
       
  7211      * then the lexicographic comparison is the result of comparing two
       
  7212      * elements, as if by {@link Double#compare(double, double)}, at a relative
       
  7213      * index within the respective arrays that is the length of the prefix.
       
  7214      * Otherwise, one array is a proper prefix of the other and, lexicographic
       
  7215      * comparison is the result of comparing the two range lengths.
       
  7216      * (See {@link #mismatch(double[], int, int, double[], int, int)} for the
       
  7217      * definition of a common and proper prefix.)
       
  7218      *
       
  7219      * <p>The comparison is consistent with
       
  7220      * {@link #equals(double[], int, int, double[], int, int) equals}, more
       
  7221      * specifically the following holds for arrays {@code a} and {@code b} with
       
  7222      * specified ranges [{@code aFromIndex}, {@code atoIndex}) and
       
  7223      * [{@code bFromIndex}, {@code btoIndex}) respectively:
       
  7224      * <pre>{@code
       
  7225      *     Arrays.equals(a, aFromIndex, aToIndex, b, bFromIndex, bToIndex) ==
       
  7226      *         (Arrays.compare(a, aFromIndex, aToIndex, b, bFromIndex, bToIndex) == 0)
       
  7227      * }</pre>
       
  7228      *
       
  7229      * @apiNote
       
  7230      * <p>This method behaves as if:
       
  7231      * <pre>{@code
       
  7232      *     int i = Arrays.mismatch(a, aFromIndex, aToIndex,
       
  7233      *                             b, bFromIndex, bToIndex);
       
  7234      *     if (i >= 0 && i < Math.min(aToIndex - aFromIndex, bToIndex - bFromIndex))
       
  7235      *         return Double.compare(a[aFromIndex + i], b[bFromIndex + i]);
       
  7236      *     return (aToIndex - aFromIndex) - (bToIndex - bFromIndex);
       
  7237      * }</pre>
       
  7238      *
       
  7239      * @param a the first array to compare
       
  7240      * @param aFromIndex the index (inclusive) of the first element in the
       
  7241      *                   first array to be compared
       
  7242      * @param aToIndex the index (exclusive) of the last element in the
       
  7243      *                 first array to be compared
       
  7244      * @param b the second array to compare
       
  7245      * @param bFromIndex the index (inclusive) of the first element in the
       
  7246      *                   second array to be compared
       
  7247      * @param bToIndex the index (exclusive) of the last element in the
       
  7248      *                 second array to be compared
       
  7249      * @return the value {@code 0} if, over the specified ranges, the first and
       
  7250      *         second array are equal and contain the same elements in the same
       
  7251      *         order;
       
  7252      *         a value less than {@code 0} if, over the specified ranges, the
       
  7253      *         first array is lexicographically less than the second array; and
       
  7254      *         a value greater than {@code 0} if, over the specified ranges, the
       
  7255      *         first array is lexicographically greater than the second array
       
  7256      * @throws IllegalArgumentException
       
  7257      *         if {@code aFromIndex > aToIndex} or
       
  7258      *         if {@code bFromIndex > bToIndex}
       
  7259      * @throws ArrayIndexOutOfBoundsException
       
  7260      *         if {@code aFromIndex < 0 or aToIndex > a.length} or
       
  7261      *         if {@code bFromIndex < 0 or bToIndex > b.length}
       
  7262      * @throws NullPointerException
       
  7263      *         if either array is {@code null}
       
  7264      * @since 9
       
  7265      */
       
  7266     public static int compare(double[] a, int aFromIndex, int aToIndex,
       
  7267                               double[] b, int bFromIndex, int bToIndex) {
       
  7268         rangeCheck(a.length, aFromIndex, aToIndex);
       
  7269         rangeCheck(b.length, bFromIndex, bToIndex);
       
  7270 
       
  7271         int aLength = aToIndex - aFromIndex;
       
  7272         int bLength = bToIndex - bFromIndex;
       
  7273         int i = ArraysSupport.mismatch(a, aFromIndex,
       
  7274                                        b, bFromIndex,
       
  7275                                        Math.min(aLength, bLength));
       
  7276         if (i >= 0) {
       
  7277             return Double.compare(a[aFromIndex + i], b[bFromIndex + i]);
       
  7278         }
       
  7279 
       
  7280         return aLength - bLength;
       
  7281     }
       
  7282 
       
  7283     // Compare objects
       
  7284 
       
  7285     /**
       
  7286      * Compares two {@code Object} arrays, within comparable elements,
       
  7287      * lexicographically.
       
  7288      *
       
  7289      * <p>If the two arrays share a common prefix then the lexicographic
       
  7290      * comparison is the result of comparing two elements of type {@code T} at
       
  7291      * an index {@code i} within the respective arrays that is the prefix
       
  7292      * length, as if by:
       
  7293      * <pre>{@code
       
  7294      *     Comparator.nullsFirst(Comparator.<T>naturalOrder()).
       
  7295      *         compare(a[i], b[i])
       
  7296      * }</pre>
       
  7297      * Otherwise, one array is a proper prefix of the other and, lexicographic
       
  7298      * comparison is the result of comparing the two array lengths.
       
  7299      * (See {@link #mismatch(Object[], Object[])} for the definition of a common
       
  7300      * and proper prefix.)
       
  7301      *
       
  7302      * <p>A {@code null} array reference is considered lexicographically less
       
  7303      * than a non-{@code null} array reference.  Two {@code null} array
       
  7304      * references are considered equal.
       
  7305      * A {@code null} array element is considered lexicographically than a
       
  7306      * non-{@code null} array element.  Two {@code null} array elements are
       
  7307      * considered equal.
       
  7308      *
       
  7309      * <p>The comparison is consistent with {@link #equals(Object[], Object[]) equals},
       
  7310      * more specifically the following holds for arrays {@code a} and {@code b}:
       
  7311      * <pre>{@code
       
  7312      *     Arrays.equals(a, b) == (Arrays.compare(a, b) == 0)
       
  7313      * }</pre>
       
  7314      *
       
  7315      * @apiNote
       
  7316      * <p>This method behaves as if (for non-{@code null} array references
       
  7317      * and elements):
       
  7318      * <pre>{@code
       
  7319      *     int i = Arrays.mismatch(a, b);
       
  7320      *     if (i >= 0 && i < Math.min(a.length, b.length))
       
  7321      *         return a[i].compareTo(b[i]);
       
  7322      *     return a.length - b.length;
       
  7323      * }</pre>
       
  7324      *
       
  7325      * @param a the first array to compare
       
  7326      * @param b the second array to compare
       
  7327      * @param <T> the type of comparable array elements
       
  7328      * @return the value {@code 0} if the first and second array are equal and
       
  7329      *         contain the same elements in the same order;
       
  7330      *         a value less than {@code 0} if the first array is
       
  7331      *         lexicographically less than the second array; and
       
  7332      *         a value greater than {@code 0} if the first array is
       
  7333      *         lexicographically greater than the second array
       
  7334      * @since 9
       
  7335      */
       
  7336     public static <T extends Comparable<? super T>> int compare(T[] a, T[] b) {
       
  7337         if (a == b)
       
  7338             return 0;
       
  7339         // A null array is less than a non-null array
       
  7340         if (a == null || b == null)
       
  7341             return a == null ? -1 : 1;
       
  7342 
       
  7343         int length = Math.min(a.length, b.length);
       
  7344         for (int i = 0; i < length; i++) {
       
  7345             T oa = a[i];
       
  7346             T ob = b[i];
       
  7347             if (oa != ob) {
       
  7348                 // A null element is less than a non-null element
       
  7349                 if (oa == null || ob == null)
       
  7350                     return oa == null ? -1 : 1;
       
  7351                 int v = oa.compareTo(ob);
       
  7352                 if (v != 0) {
       
  7353                     return v;
       
  7354                 }
       
  7355             }
       
  7356         }
       
  7357 
       
  7358         return a.length - b.length;
       
  7359     }
       
  7360 
       
  7361     /**
       
  7362      * Compares two {@code Object} arrays lexicographically over the specified
       
  7363      * ranges.
       
  7364      *
       
  7365      * <p>If the two arrays, over the specified ranges, share a common prefix
       
  7366      * then the lexicographic comparison is the result of comparing two
       
  7367      * elements of type {@code T} at a relative index {@code i} within the
       
  7368      * respective arrays that is the prefix length, as if by:
       
  7369      * <pre>{@code
       
  7370      *     Comparator.nullsFirst(Comparator.<T>naturalOrder()).
       
  7371      *         compare(a[aFromIndex + i, b[bFromIndex + i])
       
  7372      * }</pre>
       
  7373      * Otherwise, one array is a proper prefix of the other and, lexicographic
       
  7374      * comparison is the result of comparing the two range lengths.
       
  7375      * (See {@link #mismatch(Object[], int, int, Object[], int, int)} for the
       
  7376      * definition of a common and proper prefix.)
       
  7377      *
       
  7378      * <p>The comparison is consistent with
       
  7379      * {@link #equals(Object[], int, int, Object[], int, int) equals}, more
       
  7380      * specifically the following holds for arrays {@code a} and {@code b} with
       
  7381      * specified ranges [{@code aFromIndex}, {@code atoIndex}) and
       
  7382      * [{@code bFromIndex}, {@code btoIndex}) respectively:
       
  7383      * <pre>{@code
       
  7384      *     Arrays.equals(a, aFromIndex, aToIndex, b, bFromIndex, bToIndex) ==
       
  7385      *         (Arrays.compare(a, aFromIndex, aToIndex, b, bFromIndex, bToIndex) == 0)
       
  7386      * }</pre>
       
  7387      *
       
  7388      * @apiNote
       
  7389      * <p>This method behaves as if (for non-{@code null} array elements):
       
  7390      * <pre>{@code
       
  7391      *     int i = Arrays.mismatch(a, aFromIndex, aToIndex,
       
  7392      *                             b, bFromIndex, bToIndex);
       
  7393      *     if (i >= 0 && i < Math.min(aToIndex - aFromIndex, bToIndex - bFromIndex))
       
  7394      *         return a[aFromIndex + i].compareTo(b[bFromIndex + i]);
       
  7395      *     return (aToIndex - aFromIndex) - (bToIndex - bFromIndex);
       
  7396      * }</pre>
       
  7397      *
       
  7398      * @param a the first array to compare
       
  7399      * @param aFromIndex the index (inclusive) of the first element in the
       
  7400      *                   first array to be compared
       
  7401      * @param aToIndex the index (exclusive) of the last element in the
       
  7402      *                 first array to be compared
       
  7403      * @param b the second array to compare
       
  7404      * @param bFromIndex the index (inclusive) of the first element in the
       
  7405      *                   second array to be compared
       
  7406      * @param bToIndex the index (exclusive) of the last element in the
       
  7407      *                 second array to be compared
       
  7408      * @param <T> the type of comparable array elements
       
  7409      * @return the value {@code 0} if, over the specified ranges, the first and
       
  7410      *         second array are equal and contain the same elements in the same
       
  7411      *         order;
       
  7412      *         a value less than {@code 0} if, over the specified ranges, the
       
  7413      *         first array is lexicographically less than the second array; and
       
  7414      *         a value greater than {@code 0} if, over the specified ranges, the
       
  7415      *         first array is lexicographically greater than the second array
       
  7416      * @throws IllegalArgumentException
       
  7417      *         if {@code aFromIndex > aToIndex} or
       
  7418      *         if {@code bFromIndex > bToIndex}
       
  7419      * @throws ArrayIndexOutOfBoundsException
       
  7420      *         if {@code aFromIndex < 0 or aToIndex > a.length} or
       
  7421      *         if {@code bFromIndex < 0 or bToIndex > b.length}
       
  7422      * @throws NullPointerException
       
  7423      *         if either array is {@code null}
       
  7424      * @since 9
       
  7425      */
       
  7426     public static <T extends Comparable<? super T>> int compare(
       
  7427             T[] a, int aFromIndex, int aToIndex,
       
  7428             T[] b, int bFromIndex, int bToIndex) {
       
  7429         rangeCheck(a.length, aFromIndex, aToIndex);
       
  7430         rangeCheck(b.length, bFromIndex, bToIndex);
       
  7431 
       
  7432         int aLength = aToIndex - aFromIndex;
       
  7433         int bLength = bToIndex - bFromIndex;
       
  7434         int length = Math.min(aLength, bLength);
       
  7435         for (int i = 0; i < length; i++) {
       
  7436             T oa = a[aFromIndex++];
       
  7437             T ob = b[bFromIndex++];
       
  7438             if (oa != ob) {
       
  7439                 if (oa == null || ob == null)
       
  7440                     return oa == null ? -1 : 1;
       
  7441                 int v = oa.compareTo(ob);
       
  7442                 if (v != 0) {
       
  7443                     return v;
       
  7444                 }
       
  7445             }
       
  7446         }
       
  7447 
       
  7448         return aLength - bLength;
       
  7449     }
       
  7450 
       
  7451     /**
       
  7452      * Compares two {@code Object} arrays lexicographically using a specified
       
  7453      * comparator.
       
  7454      *
       
  7455      * <p>If the two arrays share a common prefix then the lexicographic
       
  7456      * comparison is the result of comparing with the specified comparator two
       
  7457      * elements at an index within the respective arrays that is the prefix
       
  7458      * length.
       
  7459      * Otherwise, one array is a proper prefix of the other and, lexicographic
       
  7460      * comparison is the result of comparing the two array lengths.
       
  7461      * (See {@link #mismatch(Object[], Object[])} for the definition of a common
       
  7462      * and proper prefix.)
       
  7463      *
       
  7464      * <p>A {@code null} array reference is considered lexicographically less
       
  7465      * than a non-{@code null} array reference.  Two {@code null} array
       
  7466      * references are considered equal.
       
  7467      *
       
  7468      * @apiNote
       
  7469      * <p>This method behaves as if (for non-{@code null} array references):
       
  7470      * <pre>{@code
       
  7471      *     int i = Arrays.mismatch(a, b, cmp);
       
  7472      *     if (i >= 0 && i < Math.min(a.length, b.length))
       
  7473      *         return cmp.compare(a[i], b[i]);
       
  7474      *     return a.length - b.length;
       
  7475      * }</pre>
       
  7476      *
       
  7477      * @param a the first array to compare
       
  7478      * @param b the second array to compare
       
  7479      * @param cmp the comparator to compare array elements
       
  7480      * @param <T> the type of array elements
       
  7481      * @return the value {@code 0} if the first and second array are equal and
       
  7482      *         contain the same elements in the same order;
       
  7483      *         a value less than {@code 0} if the first array is
       
  7484      *         lexicographically less than the second array; and
       
  7485      *         a value greater than {@code 0} if the first array is
       
  7486      *         lexicographically greater than the second array
       
  7487      * @throws NullPointerException if the comparator is {@code null}
       
  7488      * @since 9
       
  7489      */
       
  7490     public static <T> int compare(T[] a, T[] b,
       
  7491                                   Comparator<? super T> cmp) {
       
  7492         Objects.requireNonNull(cmp);
       
  7493         if (a == b)
       
  7494             return 0;
       
  7495         if (a == null || b == null)
       
  7496             return a == null ? -1 : 1;
       
  7497 
       
  7498         int length = Math.min(a.length, b.length);
       
  7499         for (int i = 0; i < length; i++) {
       
  7500             T oa = a[i];
       
  7501             T ob = b[i];
       
  7502             if (oa != ob) {
       
  7503                 // Null-value comparison is deferred to the comparator
       
  7504                 int v = cmp.compare(oa, ob);
       
  7505                 if (v != 0) {
       
  7506                     return v;
       
  7507                 }
       
  7508             }
       
  7509         }
       
  7510 
       
  7511         return a.length - b.length;
       
  7512     }
       
  7513 
       
  7514     /**
       
  7515      * Compares two {@code Object} arrays lexicographically over the specified
       
  7516      * ranges.
       
  7517      *
       
  7518      * <p>If the two arrays, over the specified ranges, share a common prefix
       
  7519      * then the lexicographic comparison is the result of comparing with the
       
  7520      * specified comparator two elements at a relative index within the
       
  7521      * respective arrays that is the prefix length.
       
  7522      * Otherwise, one array is a proper prefix of the other and, lexicographic
       
  7523      * comparison is the result of comparing the two range lengths.
       
  7524      * (See {@link #mismatch(Object[], int, int, Object[], int, int)} for the
       
  7525      * definition of a common and proper prefix.)
       
  7526      *
       
  7527      * @apiNote
       
  7528      * <p>This method behaves as if (for non-{@code null} array elements):
       
  7529      * <pre>{@code
       
  7530      *     int i = Arrays.mismatch(a, aFromIndex, aToIndex,
       
  7531      *                             b, bFromIndex, bToIndex, cmp);
       
  7532      *     if (i >= 0 && i < Math.min(aToIndex - aFromIndex, bToIndex - bFromIndex))
       
  7533      *         return cmp.compare(a[aFromIndex + i], b[bFromIndex + i]);
       
  7534      *     return (aToIndex - aFromIndex) - (bToIndex - bFromIndex);
       
  7535      * }</pre>
       
  7536      *
       
  7537      * @param a the first array to compare
       
  7538      * @param aFromIndex the index (inclusive) of the first element in the
       
  7539      *                   first array to be compared
       
  7540      * @param aToIndex the index (exclusive) of the last element in the
       
  7541      *                 first array to be compared
       
  7542      * @param b the second array to compare
       
  7543      * @param bFromIndex the index (inclusive) of the first element in the
       
  7544      *                   second array to be compared
       
  7545      * @param bToIndex the index (exclusive) of the last element in the
       
  7546      *                 second array to be compared
       
  7547      * @param cmp the comparator to compare array elements
       
  7548      * @param <T> the type of array elements
       
  7549      * @return the value {@code 0} if, over the specified ranges, the first and
       
  7550      *         second array are equal and contain the same elements in the same
       
  7551      *         order;
       
  7552      *         a value less than {@code 0} if, over the specified ranges, the
       
  7553      *         first array is lexicographically less than the second array; and
       
  7554      *         a value greater than {@code 0} if, over the specified ranges, the
       
  7555      *         first array is lexicographically greater than the second array
       
  7556      * @throws IllegalArgumentException
       
  7557      *         if {@code aFromIndex > aToIndex} or
       
  7558      *         if {@code bFromIndex > bToIndex}
       
  7559      * @throws ArrayIndexOutOfBoundsException
       
  7560      *         if {@code aFromIndex < 0 or aToIndex > a.length} or
       
  7561      *         if {@code bFromIndex < 0 or bToIndex > b.length}
       
  7562      * @throws NullPointerException
       
  7563      *         if either array or the comparator is {@code null}
       
  7564      * @since 9
       
  7565      */
       
  7566     public static <T> int compare(
       
  7567             T[] a, int aFromIndex, int aToIndex,
       
  7568             T[] b, int bFromIndex, int bToIndex,
       
  7569             Comparator<? super T> cmp) {
       
  7570         Objects.requireNonNull(cmp);
       
  7571         rangeCheck(a.length, aFromIndex, aToIndex);
       
  7572         rangeCheck(b.length, bFromIndex, bToIndex);
       
  7573 
       
  7574         int aLength = aToIndex - aFromIndex;
       
  7575         int bLength = bToIndex - bFromIndex;
       
  7576         int length = Math.min(aLength, bLength);
       
  7577         for (int i = 0; i < length; i++) {
       
  7578             T oa = a[aFromIndex++];
       
  7579             T ob = b[bFromIndex++];
       
  7580             if (oa != ob) {
       
  7581                 // Null-value comparison is deferred to the comparator
       
  7582                 int v = cmp.compare(oa, ob);
       
  7583                 if (v != 0) {
       
  7584                     return v;
       
  7585                 }
       
  7586             }
       
  7587         }
       
  7588 
       
  7589         return aLength - bLength;
       
  7590     }
       
  7591 
       
  7592 
       
  7593     // Mismatch methods
       
  7594 
       
  7595     // Mismatch boolean
       
  7596 
       
  7597     /**
       
  7598      * Finds and returns the index of the first mismatch between two
       
  7599      * {@code boolean} arrays, otherwise return -1 if no mismatch is found.  The
       
  7600      * index will be in the range of 0 (inclusive) up to the length (inclusive)
       
  7601      * of the smaller array.
       
  7602      *
       
  7603      * <p>If the two arrays share a common prefix then the returned index is the
       
  7604      * length of the common prefix and it follows that there is a mismatch
       
  7605      * between the two elements at that index within the respective arrays.
       
  7606      * If one array is a proper prefix of the other then the returned index is
       
  7607      * the length of the smaller array and it follows that the index is only
       
  7608      * valid for the larger array.
       
  7609      * Otherwise, there is no mismatch.
       
  7610      *
       
  7611      * <p>Two non-{@code null} arrays, {@code a} and {@code b}, share a common
       
  7612      * prefix of length {@code pl} if the following expression is true:
       
  7613      * <pre>{@code
       
  7614      *     pl >= 0 &&
       
  7615      *     pl < Math.min(a.length, b.length) &&
       
  7616      *     Arrays.equals(a, 0, pl, b, 0, pl) &&
       
  7617      *     a[pl] != b[pl]
       
  7618      * }</pre>
       
  7619      * Note that a common prefix length of {@code 0} indicates that the first
       
  7620      * elements from each array mismatch.
       
  7621      *
       
  7622      * <p>Two non-{@code null} arrays, {@code a} and {@code b}, share a proper
       
  7623      * prefix if the following expression is true:
       
  7624      * <pre>{@code
       
  7625      *     a.length != b.length &&
       
  7626      *     Arrays.equals(a, 0, Math.min(a.length, b.length),
       
  7627      *                   b, 0, Math.min(a.length, b.length))
       
  7628      * }</pre>
       
  7629      *
       
  7630      * @param a the first array to be tested for a mismatch
       
  7631      * @param b the second array to be tested for a mismatch
       
  7632      * @return the index of the first mismatch between the two arrays,
       
  7633      *         otherwise {@code -1}.
       
  7634      * @throws NullPointerException
       
  7635      *         if either array is {@code null}
       
  7636      * @since 9
       
  7637      */
       
  7638     public static int mismatch(boolean[] a, boolean[] b) {
       
  7639         int length = Math.min(a.length, b.length); // Check null array refs
       
  7640         if (a == b)
       
  7641             return -1;
       
  7642 
       
  7643         int i = ArraysSupport.mismatch(a, b, length);
       
  7644         return (i < 0 && a.length != b.length) ? length : i;
       
  7645     }
       
  7646 
       
  7647     /**
       
  7648      * Finds and returns the relative index of the first mismatch between two
       
  7649      * {@code boolean} arrays over the specified ranges, otherwise return -1 if
       
  7650      * no mismatch is found.  The index will be in the range of 0 (inclusive) up
       
  7651      * to the length (inclusive) of the smaller range.
       
  7652      *
       
  7653      * <p>If the two arrays, over the specified ranges, share a common prefix
       
  7654      * then the returned relative index is the length of the common prefix and
       
  7655      * it follows that there is a mismatch between the two elements at that
       
  7656      * relative index within the respective arrays.
       
  7657      * If one array is a proper prefix of the other, over the specified ranges,
       
  7658      * then the returned relative index is the length of the smaller range and
       
  7659      * it follows that the relative index is only valid for the array with the
       
  7660      * larger range.
       
  7661      * Otherwise, there is no mismatch.
       
  7662      *
       
  7663      * <p>Two non-{@code null} arrays, {@code a} and {@code b} with specified
       
  7664      * ranges [{@code aFromIndex}, {@code atoIndex}) and
       
  7665      * [{@code bFromIndex}, {@code btoIndex}) respectively, share a common
       
  7666      * prefix of length {@code pl} if the following expression is true:
       
  7667      * <pre>{@code
       
  7668      *     pl >= 0 &&
       
  7669      *     pl < Math.min(aToIndex - aFromIndex, bToIndex - bFromIndex) &&
       
  7670      *     Arrays.equals(a, aFromIndex, aFromIndex + pl, b, bFromIndex, bFromIndex + pl) &&
       
  7671      *     a[aFromIndex + pl] != b[bFromIndex + pl]
       
  7672      * }</pre>
       
  7673      * Note that a common prefix length of {@code 0} indicates that the first
       
  7674      * elements from each array mismatch.
       
  7675      *
       
  7676      * <p>Two non-{@code null} arrays, {@code a} and {@code b} with specified
       
  7677      * ranges [{@code aFromIndex}, {@code atoIndex}) and
       
  7678      * [{@code bFromIndex}, {@code btoIndex}) respectively, share a proper
       
  7679      * if the following expression is true:
       
  7680      * <pre>{@code
       
  7681      *     (aToIndex - aFromIndex) != (bToIndex - bFromIndex) &&
       
  7682      *     Arrays.equals(a, 0, Math.min(aToIndex - aFromIndex, bToIndex - bFromIndex),
       
  7683      *                   b, 0, Math.min(aToIndex - aFromIndex, bToIndex - bFromIndex))
       
  7684      * }</pre>
       
  7685      *
       
  7686      * @param a the first array to be tested for a mismatch
       
  7687      * @param aFromIndex the index (inclusive) of the first element in the
       
  7688      *                   first array to be tested
       
  7689      * @param aToIndex the index (exclusive) of the last element in the
       
  7690      *                 first array to be tested
       
  7691      * @param b the second array to be tested for a mismatch
       
  7692      * @param bFromIndex the index (inclusive) of the first element in the
       
  7693      *                   second array to be tested
       
  7694      * @param bToIndex the index (exclusive) of the last element in the
       
  7695      *                 second array to be tested
       
  7696      * @return the relative index of the first mismatch between the two arrays
       
  7697      *         over the specified ranges, otherwise {@code -1}.
       
  7698      * @throws IllegalArgumentException
       
  7699      *         if {@code aFromIndex > aToIndex} or
       
  7700      *         if {@code bFromIndex > bToIndex}
       
  7701      * @throws ArrayIndexOutOfBoundsException
       
  7702      *         if {@code aFromIndex < 0 or aToIndex > a.length} or
       
  7703      *         if {@code bFromIndex < 0 or bToIndex > b.length}
       
  7704      * @throws NullPointerException
       
  7705      *         if either array is {@code null}
       
  7706      * @since 9
       
  7707      */
       
  7708     public static int mismatch(boolean[] a, int aFromIndex, int aToIndex,
       
  7709                                boolean[] b, int bFromIndex, int bToIndex) {
       
  7710         rangeCheck(a.length, aFromIndex, aToIndex);
       
  7711         rangeCheck(b.length, bFromIndex, bToIndex);
       
  7712 
       
  7713         int aLength = aToIndex - aFromIndex;
       
  7714         int bLength = bToIndex - bFromIndex;
       
  7715         int length = Math.min(aLength, bLength);
       
  7716         int i = ArraysSupport.mismatch(a, aFromIndex,
       
  7717                                        b, bFromIndex,
       
  7718                                        length);
       
  7719         return (i < 0 && aLength != bLength) ? length : i;
       
  7720     }
       
  7721 
       
  7722     // Mismatch byte
       
  7723 
       
  7724     /**
       
  7725      * Finds and returns the index of the first mismatch between two {@code byte}
       
  7726      * arrays, otherwise return -1 if no mismatch is found.  The index will be
       
  7727      * in the range of 0 (inclusive) up to the length (inclusive) of the smaller
       
  7728      * array.
       
  7729      *
       
  7730      * <p>If the two arrays share a common prefix then the returned index is the
       
  7731      * length of the common prefix and it follows that there is a mismatch
       
  7732      * between the two elements at that index within the respective arrays.
       
  7733      * If one array is a proper prefix of the other then the returned index is
       
  7734      * the length of the smaller array and it follows that the index is only
       
  7735      * valid for the larger array.
       
  7736      * Otherwise, there is no mismatch.
       
  7737      *
       
  7738      * <p>Two non-{@code null} arrays, {@code a} and {@code b}, share a common
       
  7739      * prefix of length {@code pl} if the following expression is true:
       
  7740      * <pre>{@code
       
  7741      *     pl >= 0 &&
       
  7742      *     pl < Math.min(a.length, b.length) &&
       
  7743      *     Arrays.equals(a, 0, pl, b, 0, pl) &&
       
  7744      *     a[pl] != b[pl]
       
  7745      * }</pre>
       
  7746      * Note that a common prefix length of {@code 0} indicates that the first
       
  7747      * elements from each array mismatch.
       
  7748      *
       
  7749      * <p>Two non-{@code null} arrays, {@code a} and {@code b}, share a proper
       
  7750      * prefix if the following expression is true:
       
  7751      * <pre>{@code
       
  7752      *     a.length != b.length &&
       
  7753      *     Arrays.equals(a, 0, Math.min(a.length, b.length),
       
  7754      *                   b, 0, Math.min(a.length, b.length))
       
  7755      * }</pre>
       
  7756      *
       
  7757      * @param a the first array to be tested for a mismatch
       
  7758      * @param b the second array to be tested for a mismatch
       
  7759      * @return the index of the first mismatch between the two arrays,
       
  7760      *         otherwise {@code -1}.
       
  7761      * @throws NullPointerException
       
  7762      *         if either array is {@code null}
       
  7763      * @since 9
       
  7764      */
       
  7765     public static int mismatch(byte[] a, byte[] b) {
       
  7766         int length = Math.min(a.length, b.length); // Check null array refs
       
  7767         if (a == b)
       
  7768             return -1;
       
  7769 
       
  7770         int i = ArraysSupport.mismatch(a, b, length);
       
  7771         return (i < 0 && a.length != b.length) ? length : i;
       
  7772     }
       
  7773 
       
  7774     /**
       
  7775      * Finds and returns the relative index of the first mismatch between two
       
  7776      * {@code byte} arrays over the specified ranges, otherwise return -1 if no
       
  7777      * mismatch is found.  The index will be in the range of 0 (inclusive) up to
       
  7778      * the length (inclusive) of the smaller range.
       
  7779      *
       
  7780      * <p>If the two arrays, over the specified ranges, share a common prefix
       
  7781      * then the returned relative index is the length of the common prefix and
       
  7782      * it follows that there is a mismatch between the two elements at that
       
  7783      * relative index within the respective arrays.
       
  7784      * If one array is a proper prefix of the other, over the specified ranges,
       
  7785      * then the returned relative index is the length of the smaller range and
       
  7786      * it follows that the relative index is only valid for the array with the
       
  7787      * larger range.
       
  7788      * Otherwise, there is no mismatch.
       
  7789      *
       
  7790      * <p>Two non-{@code null} arrays, {@code a} and {@code b} with specified
       
  7791      * ranges [{@code aFromIndex}, {@code atoIndex}) and
       
  7792      * [{@code bFromIndex}, {@code btoIndex}) respectively, share a common
       
  7793      * prefix of length {@code pl} if the following expression is true:
       
  7794      * <pre>{@code
       
  7795      *     pl >= 0 &&
       
  7796      *     pl < Math.min(aToIndex - aFromIndex, bToIndex - bFromIndex) &&
       
  7797      *     Arrays.equals(a, aFromIndex, aFromIndex + pl, b, bFromIndex, bFromIndex + pl) &&
       
  7798      *     a[aFromIndex + pl] != b[bFromIndex + pl]
       
  7799      * }</pre>
       
  7800      * Note that a common prefix length of {@code 0} indicates that the first
       
  7801      * elements from each array mismatch.
       
  7802      *
       
  7803      * <p>Two non-{@code null} arrays, {@code a} and {@code b} with specified
       
  7804      * ranges [{@code aFromIndex}, {@code atoIndex}) and
       
  7805      * [{@code bFromIndex}, {@code btoIndex}) respectively, share a proper
       
  7806      * if the following expression is true:
       
  7807      * <pre>{@code
       
  7808      *     (aToIndex - aFromIndex) != (bToIndex - bFromIndex) &&
       
  7809      *     Arrays.equals(a, 0, Math.min(aToIndex - aFromIndex, bToIndex - bFromIndex),
       
  7810      *                   b, 0, Math.min(aToIndex - aFromIndex, bToIndex - bFromIndex))
       
  7811      * }</pre>
       
  7812      *
       
  7813      * @param a the first array to be tested for a mismatch
       
  7814      * @param aFromIndex the index (inclusive) of the first element in the
       
  7815      *                   first array to be tested
       
  7816      * @param aToIndex the index (exclusive) of the last element in the
       
  7817      *                 first array to be tested
       
  7818      * @param b the second array to be tested for a mismatch
       
  7819      * @param bFromIndex the index (inclusive) of the first element in the
       
  7820      *                   second array to be tested
       
  7821      * @param bToIndex the index (exclusive) of the last element in the
       
  7822      *                 second array to be tested
       
  7823      * @return the relative index of the first mismatch between the two arrays
       
  7824      *         over the specified ranges, otherwise {@code -1}.
       
  7825      * @throws IllegalArgumentException
       
  7826      *         if {@code aFromIndex > aToIndex} or
       
  7827      *         if {@code bFromIndex > bToIndex}
       
  7828      * @throws ArrayIndexOutOfBoundsException
       
  7829      *         if {@code aFromIndex < 0 or aToIndex > a.length} or
       
  7830      *         if {@code bFromIndex < 0 or bToIndex > b.length}
       
  7831      * @throws NullPointerException
       
  7832      *         if either array is {@code null}
       
  7833      * @since 9
       
  7834      */
       
  7835     public static int mismatch(byte[] a, int aFromIndex, int aToIndex,
       
  7836                                byte[] b, int bFromIndex, int bToIndex) {
       
  7837         rangeCheck(a.length, aFromIndex, aToIndex);
       
  7838         rangeCheck(b.length, bFromIndex, bToIndex);
       
  7839 
       
  7840         int aLength = aToIndex - aFromIndex;
       
  7841         int bLength = bToIndex - bFromIndex;
       
  7842         int length = Math.min(aLength, bLength);
       
  7843         int i = ArraysSupport.mismatch(a, aFromIndex,
       
  7844                                        b, bFromIndex,
       
  7845                                        length);
       
  7846         return (i < 0 && aLength != bLength) ? length : i;
       
  7847     }
       
  7848 
       
  7849     // Mismatch char
       
  7850 
       
  7851     /**
       
  7852      * Finds and returns the index of the first mismatch between two {@code char}
       
  7853      * arrays, otherwise return -1 if no mismatch is found.  The index will be
       
  7854      * in the range of 0 (inclusive) up to the length (inclusive) of the smaller
       
  7855      * array.
       
  7856      *
       
  7857      * <p>If the two arrays share a common prefix then the returned index is the
       
  7858      * length of the common prefix and it follows that there is a mismatch
       
  7859      * between the two elements at that index within the respective arrays.
       
  7860      * If one array is a proper prefix of the other then the returned index is
       
  7861      * the length of the smaller array and it follows that the index is only
       
  7862      * valid for the larger array.
       
  7863      * Otherwise, there is no mismatch.
       
  7864      *
       
  7865      * <p>Two non-{@code null} arrays, {@code a} and {@code b}, share a common
       
  7866      * prefix of length {@code pl} if the following expression is true:
       
  7867      * <pre>{@code
       
  7868      *     pl >= 0 &&
       
  7869      *     pl < Math.min(a.length, b.length) &&
       
  7870      *     Arrays.equals(a, 0, pl, b, 0, pl) &&
       
  7871      *     a[pl] != b[pl]
       
  7872      * }</pre>
       
  7873      * Note that a common prefix length of {@code 0} indicates that the first
       
  7874      * elements from each array mismatch.
       
  7875      *
       
  7876      * <p>Two non-{@code null} arrays, {@code a} and {@code b}, share a proper
       
  7877      * prefix if the following expression is true:
       
  7878      * <pre>{@code
       
  7879      *     a.length != b.length &&
       
  7880      *     Arrays.equals(a, 0, Math.min(a.length, b.length),
       
  7881      *                   b, 0, Math.min(a.length, b.length))
       
  7882      * }</pre>
       
  7883      *
       
  7884      * @param a the first array to be tested for a mismatch
       
  7885      * @param b the second array to be tested for a mismatch
       
  7886      * @return the index of the first mismatch between the two arrays,
       
  7887      *         otherwise {@code -1}.
       
  7888      * @throws NullPointerException
       
  7889      *         if either array is {@code null}
       
  7890      * @since 9
       
  7891      */
       
  7892     public static int mismatch(char[] a, char[] b) {
       
  7893         int length = Math.min(a.length, b.length); // Check null array refs
       
  7894         if (a == b)
       
  7895             return -1;
       
  7896 
       
  7897         int i = ArraysSupport.mismatch(a, b, length);
       
  7898         return (i < 0 && a.length != b.length) ? length : i;
       
  7899     }
       
  7900 
       
  7901     /**
       
  7902      * Finds and returns the relative index of the first mismatch between two
       
  7903      * {@code char} arrays over the specified ranges, otherwise return -1 if no
       
  7904      * mismatch is found.  The index will be in the range of 0 (inclusive) up to
       
  7905      * the length (inclusive) of the smaller range.
       
  7906      *
       
  7907      * <p>If the two arrays, over the specified ranges, share a common prefix
       
  7908      * then the returned relative index is the length of the common prefix and
       
  7909      * it follows that there is a mismatch between the two elements at that
       
  7910      * relative index within the respective arrays.
       
  7911      * If one array is a proper prefix of the other, over the specified ranges,
       
  7912      * then the returned relative index is the length of the smaller range and
       
  7913      * it follows that the relative index is only valid for the array with the
       
  7914      * larger range.
       
  7915      * Otherwise, there is no mismatch.
       
  7916      *
       
  7917      * <p>Two non-{@code null} arrays, {@code a} and {@code b} with specified
       
  7918      * ranges [{@code aFromIndex}, {@code atoIndex}) and
       
  7919      * [{@code bFromIndex}, {@code btoIndex}) respectively, share a common
       
  7920      * prefix of length {@code pl} if the following expression is true:
       
  7921      * <pre>{@code
       
  7922      *     pl >= 0 &&
       
  7923      *     pl < Math.min(aToIndex - aFromIndex, bToIndex - bFromIndex) &&
       
  7924      *     Arrays.equals(a, aFromIndex, aFromIndex + pl, b, bFromIndex, bFromIndex + pl) &&
       
  7925      *     a[aFromIndex + pl] != b[bFromIndex + pl]
       
  7926      * }</pre>
       
  7927      * Note that a common prefix length of {@code 0} indicates that the first
       
  7928      * elements from each array mismatch.
       
  7929      *
       
  7930      * <p>Two non-{@code null} arrays, {@code a} and {@code b} with specified
       
  7931      * ranges [{@code aFromIndex}, {@code atoIndex}) and
       
  7932      * [{@code bFromIndex}, {@code btoIndex}) respectively, share a proper
       
  7933      * if the following expression is true:
       
  7934      * <pre>{@code
       
  7935      *     (aToIndex - aFromIndex) != (bToIndex - bFromIndex) &&
       
  7936      *     Arrays.equals(a, 0, Math.min(aToIndex - aFromIndex, bToIndex - bFromIndex),
       
  7937      *                   b, 0, Math.min(aToIndex - aFromIndex, bToIndex - bFromIndex))
       
  7938      * }</pre>
       
  7939      *
       
  7940      * @param a the first array to be tested for a mismatch
       
  7941      * @param aFromIndex the index (inclusive) of the first element in the
       
  7942      *                   first array to be tested
       
  7943      * @param aToIndex the index (exclusive) of the last element in the
       
  7944      *                 first array to be tested
       
  7945      * @param b the second array to be tested for a mismatch
       
  7946      * @param bFromIndex the index (inclusive) of the first element in the
       
  7947      *                   second array to be tested
       
  7948      * @param bToIndex the index (exclusive) of the last element in the
       
  7949      *                 second array to be tested
       
  7950      * @return the relative index of the first mismatch between the two arrays
       
  7951      *         over the specified ranges, otherwise {@code -1}.
       
  7952      * @throws IllegalArgumentException
       
  7953      *         if {@code aFromIndex > aToIndex} or
       
  7954      *         if {@code bFromIndex > bToIndex}
       
  7955      * @throws ArrayIndexOutOfBoundsException
       
  7956      *         if {@code aFromIndex < 0 or aToIndex > a.length} or
       
  7957      *         if {@code bFromIndex < 0 or bToIndex > b.length}
       
  7958      * @throws NullPointerException
       
  7959      *         if either array is {@code null}
       
  7960      * @since 9
       
  7961      */
       
  7962     public static int mismatch(char[] a, int aFromIndex, int aToIndex,
       
  7963                                char[] b, int bFromIndex, int bToIndex) {
       
  7964         rangeCheck(a.length, aFromIndex, aToIndex);
       
  7965         rangeCheck(b.length, bFromIndex, bToIndex);
       
  7966 
       
  7967         int aLength = aToIndex - aFromIndex;
       
  7968         int bLength = bToIndex - bFromIndex;
       
  7969         int length = Math.min(aLength, bLength);
       
  7970         int i = ArraysSupport.mismatch(a, aFromIndex,
       
  7971                                        b, bFromIndex,
       
  7972                                        length);
       
  7973         return (i < 0 && aLength != bLength) ? length : i;
       
  7974     }
       
  7975 
       
  7976     // Mismatch short
       
  7977 
       
  7978     /**
       
  7979      * Finds and returns the index of the first mismatch between two {@code short}
       
  7980      * arrays, otherwise return -1 if no mismatch is found.  The index will be
       
  7981      * in the range of 0 (inclusive) up to the length (inclusive) of the smaller
       
  7982      * array.
       
  7983      *
       
  7984      * <p>If the two arrays share a common prefix then the returned index is the
       
  7985      * length of the common prefix and it follows that there is a mismatch
       
  7986      * between the two elements at that index within the respective arrays.
       
  7987      * If one array is a proper prefix of the other then the returned index is
       
  7988      * the length of the smaller array and it follows that the index is only
       
  7989      * valid for the larger array.
       
  7990      * Otherwise, there is no mismatch.
       
  7991      *
       
  7992      * <p>Two non-{@code null} arrays, {@code a} and {@code b}, share a common
       
  7993      * prefix of length {@code pl} if the following expression is true:
       
  7994      * <pre>{@code
       
  7995      *     pl >= 0 &&
       
  7996      *     pl < Math.min(a.length, b.length) &&
       
  7997      *     Arrays.equals(a, 0, pl, b, 0, pl) &&
       
  7998      *     a[pl] != b[pl]
       
  7999      * }</pre>
       
  8000      * Note that a common prefix length of {@code 0} indicates that the first
       
  8001      * elements from each array mismatch.
       
  8002      *
       
  8003      * <p>Two non-{@code null} arrays, {@code a} and {@code b}, share a proper
       
  8004      * prefix if the following expression is true:
       
  8005      * <pre>{@code
       
  8006      *     a.length != b.length &&
       
  8007      *     Arrays.equals(a, 0, Math.min(a.length, b.length),
       
  8008      *                   b, 0, Math.min(a.length, b.length))
       
  8009      * }</pre>
       
  8010      *
       
  8011      * @param a the first array to be tested for a mismatch
       
  8012      * @param b the second array to be tested for a mismatch
       
  8013      * @return the index of the first mismatch between the two arrays,
       
  8014      *         otherwise {@code -1}.
       
  8015      * @throws NullPointerException
       
  8016      *         if either array is {@code null}
       
  8017      * @since 9
       
  8018      */
       
  8019     public static int mismatch(short[] a, short[] b) {
       
  8020         int length = Math.min(a.length, b.length); // Check null array refs
       
  8021         if (a == b)
       
  8022             return -1;
       
  8023 
       
  8024         int i = ArraysSupport.mismatch(a, b, length);
       
  8025         return (i < 0 && a.length != b.length) ? length : i;
       
  8026     }
       
  8027 
       
  8028     /**
       
  8029      * Finds and returns the relative index of the first mismatch between two
       
  8030      * {@code short} arrays over the specified ranges, otherwise return -1 if no
       
  8031      * mismatch is found.  The index will be in the range of 0 (inclusive) up to
       
  8032      * the length (inclusive) of the smaller range.
       
  8033      *
       
  8034      * <p>If the two arrays, over the specified ranges, share a common prefix
       
  8035      * then the returned relative index is the length of the common prefix and
       
  8036      * it follows that there is a mismatch between the two elements at that
       
  8037      * relative index within the respective arrays.
       
  8038      * If one array is a proper prefix of the other, over the specified ranges,
       
  8039      * then the returned relative index is the length of the smaller range and
       
  8040      * it follows that the relative index is only valid for the array with the
       
  8041      * larger range.
       
  8042      * Otherwise, there is no mismatch.
       
  8043      *
       
  8044      * <p>Two non-{@code null} arrays, {@code a} and {@code b} with specified
       
  8045      * ranges [{@code aFromIndex}, {@code atoIndex}) and
       
  8046      * [{@code bFromIndex}, {@code btoIndex}) respectively, share a common
       
  8047      * prefix of length {@code pl} if the following expression is true:
       
  8048      * <pre>{@code
       
  8049      *     pl >= 0 &&
       
  8050      *     pl < Math.min(aToIndex - aFromIndex, bToIndex - bFromIndex) &&
       
  8051      *     Arrays.equals(a, aFromIndex, aFromIndex + pl, b, bFromIndex, bFromIndex + pl) &&
       
  8052      *     a[aFromIndex + pl] != b[bFromIndex + pl]
       
  8053      * }</pre>
       
  8054      * Note that a common prefix length of {@code 0} indicates that the first
       
  8055      * elements from each array mismatch.
       
  8056      *
       
  8057      * <p>Two non-{@code null} arrays, {@code a} and {@code b} with specified
       
  8058      * ranges [{@code aFromIndex}, {@code atoIndex}) and
       
  8059      * [{@code bFromIndex}, {@code btoIndex}) respectively, share a proper
       
  8060      * if the following expression is true:
       
  8061      * <pre>{@code
       
  8062      *     (aToIndex - aFromIndex) != (bToIndex - bFromIndex) &&
       
  8063      *     Arrays.equals(a, 0, Math.min(aToIndex - aFromIndex, bToIndex - bFromIndex),
       
  8064      *                   b, 0, Math.min(aToIndex - aFromIndex, bToIndex - bFromIndex))
       
  8065      * }</pre>
       
  8066      *
       
  8067      * @param a the first array to be tested for a mismatch
       
  8068      * @param aFromIndex the index (inclusive) of the first element in the
       
  8069      *                   first array to be tested
       
  8070      * @param aToIndex the index (exclusive) of the last element in the
       
  8071      *                 first array to be tested
       
  8072      * @param b the second array to be tested for a mismatch
       
  8073      * @param bFromIndex the index (inclusive) of the first element in the
       
  8074      *                   second array to be tested
       
  8075      * @param bToIndex the index (exclusive) of the last element in the
       
  8076      *                 second array to be tested
       
  8077      * @return the relative index of the first mismatch between the two arrays
       
  8078      *         over the specified ranges, otherwise {@code -1}.
       
  8079      * @throws IllegalArgumentException
       
  8080      *         if {@code aFromIndex > aToIndex} or
       
  8081      *         if {@code bFromIndex > bToIndex}
       
  8082      * @throws ArrayIndexOutOfBoundsException
       
  8083      *         if {@code aFromIndex < 0 or aToIndex > a.length} or
       
  8084      *         if {@code bFromIndex < 0 or bToIndex > b.length}
       
  8085      * @throws NullPointerException
       
  8086      *         if either array is {@code null}
       
  8087      * @since 9
       
  8088      */
       
  8089     public static int mismatch(short[] a, int aFromIndex, int aToIndex,
       
  8090                                short[] b, int bFromIndex, int bToIndex) {
       
  8091         rangeCheck(a.length, aFromIndex, aToIndex);
       
  8092         rangeCheck(b.length, bFromIndex, bToIndex);
       
  8093 
       
  8094         int aLength = aToIndex - aFromIndex;
       
  8095         int bLength = bToIndex - bFromIndex;
       
  8096         int length = Math.min(aLength, bLength);
       
  8097         int i = ArraysSupport.mismatch(a, aFromIndex,
       
  8098                                        b, bFromIndex,
       
  8099                                        length);
       
  8100         return (i < 0 && aLength != bLength) ? length : i;
       
  8101     }
       
  8102 
       
  8103     // Mismatch int
       
  8104 
       
  8105     /**
       
  8106      * Finds and returns the index of the first mismatch between two {@code int}
       
  8107      * arrays, otherwise return -1 if no mismatch is found.  The index will be
       
  8108      * in the range of 0 (inclusive) up to the length (inclusive) of the smaller
       
  8109      * array.
       
  8110      *
       
  8111      * <p>If the two arrays share a common prefix then the returned index is the
       
  8112      * length of the common prefix and it follows that there is a mismatch
       
  8113      * between the two elements at that index within the respective arrays.
       
  8114      * If one array is a proper prefix of the other then the returned index is
       
  8115      * the length of the smaller array and it follows that the index is only
       
  8116      * valid for the larger array.
       
  8117      * Otherwise, there is no mismatch.
       
  8118      *
       
  8119      * <p>Two non-{@code null} arrays, {@code a} and {@code b}, share a common
       
  8120      * prefix of length {@code pl} if the following expression is true:
       
  8121      * <pre>{@code
       
  8122      *     pl >= 0 &&
       
  8123      *     pl < Math.min(a.length, b.length) &&
       
  8124      *     Arrays.equals(a, 0, pl, b, 0, pl) &&
       
  8125      *     a[pl] != b[pl]
       
  8126      * }</pre>
       
  8127      * Note that a common prefix length of {@code 0} indicates that the first
       
  8128      * elements from each array mismatch.
       
  8129      *
       
  8130      * <p>Two non-{@code null} arrays, {@code a} and {@code b}, share a proper
       
  8131      * prefix if the following expression is true:
       
  8132      * <pre>{@code
       
  8133      *     a.length != b.length &&
       
  8134      *     Arrays.equals(a, 0, Math.min(a.length, b.length),
       
  8135      *                   b, 0, Math.min(a.length, b.length))
       
  8136      * }</pre>
       
  8137      *
       
  8138      * @param a the first array to be tested for a mismatch
       
  8139      * @param b the second array to be tested for a mismatch
       
  8140      * @return the index of the first mismatch between the two arrays,
       
  8141      *         otherwise {@code -1}.
       
  8142      * @throws NullPointerException
       
  8143      *         if either array is {@code null}
       
  8144      * @since 9
       
  8145      */
       
  8146     public static int mismatch(int[] a, int[] b) {
       
  8147         int length = Math.min(a.length, b.length); // Check null array refs
       
  8148         if (a == b)
       
  8149             return -1;
       
  8150 
       
  8151         int i = ArraysSupport.mismatch(a, b, length);
       
  8152         return (i < 0 && a.length != b.length) ? length : i;
       
  8153     }
       
  8154 
       
  8155     /**
       
  8156      * Finds and returns the relative index of the first mismatch between two
       
  8157      * {@code int} arrays over the specified ranges, otherwise return -1 if no
       
  8158      * mismatch is found.  The index will be in the range of 0 (inclusive) up to
       
  8159      * the length (inclusive) of the smaller range.
       
  8160      *
       
  8161      * <p>If the two arrays, over the specified ranges, share a common prefix
       
  8162      * then the returned relative index is the length of the common prefix and
       
  8163      * it follows that there is a mismatch between the two elements at that
       
  8164      * relative index within the respective arrays.
       
  8165      * If one array is a proper prefix of the other, over the specified ranges,
       
  8166      * then the returned relative index is the length of the smaller range and
       
  8167      * it follows that the relative index is only valid for the array with the
       
  8168      * larger range.
       
  8169      * Otherwise, there is no mismatch.
       
  8170      *
       
  8171      * <p>Two non-{@code null} arrays, {@code a} and {@code b} with specified
       
  8172      * ranges [{@code aFromIndex}, {@code atoIndex}) and
       
  8173      * [{@code bFromIndex}, {@code btoIndex}) respectively, share a common
       
  8174      * prefix of length {@code pl} if the following expression is true:
       
  8175      * <pre>{@code
       
  8176      *     pl >= 0 &&
       
  8177      *     pl < Math.min(aToIndex - aFromIndex, bToIndex - bFromIndex) &&
       
  8178      *     Arrays.equals(a, aFromIndex, aFromIndex + pl, b, bFromIndex, bFromIndex + pl) &&
       
  8179      *     a[aFromIndex + pl] != b[bFromIndex + pl]
       
  8180      * }</pre>
       
  8181      * Note that a common prefix length of {@code 0} indicates that the first
       
  8182      * elements from each array mismatch.
       
  8183      *
       
  8184      * <p>Two non-{@code null} arrays, {@code a} and {@code b} with specified
       
  8185      * ranges [{@code aFromIndex}, {@code atoIndex}) and
       
  8186      * [{@code bFromIndex}, {@code btoIndex}) respectively, share a proper
       
  8187      * if the following expression is true:
       
  8188      * <pre>{@code
       
  8189      *     (aToIndex - aFromIndex) != (bToIndex - bFromIndex) &&
       
  8190      *     Arrays.equals(a, 0, Math.min(aToIndex - aFromIndex, bToIndex - bFromIndex),
       
  8191      *                   b, 0, Math.min(aToIndex - aFromIndex, bToIndex - bFromIndex))
       
  8192      * }</pre>
       
  8193      *
       
  8194      * @param a the first array to be tested for a mismatch
       
  8195      * @param aFromIndex the index (inclusive) of the first element in the
       
  8196      *                   first array to be tested
       
  8197      * @param aToIndex the index (exclusive) of the last element in the
       
  8198      *                 first array to be tested
       
  8199      * @param b the second array to be tested for a mismatch
       
  8200      * @param bFromIndex the index (inclusive) of the first element in the
       
  8201      *                   second array to be tested
       
  8202      * @param bToIndex the index (exclusive) of the last element in the
       
  8203      *                 second array to be tested
       
  8204      * @return the relative index of the first mismatch between the two arrays
       
  8205      *         over the specified ranges, otherwise {@code -1}.
       
  8206      * @throws IllegalArgumentException
       
  8207      *         if {@code aFromIndex > aToIndex} or
       
  8208      *         if {@code bFromIndex > bToIndex}
       
  8209      * @throws ArrayIndexOutOfBoundsException
       
  8210      *         if {@code aFromIndex < 0 or aToIndex > a.length} or
       
  8211      *         if {@code bFromIndex < 0 or bToIndex > b.length}
       
  8212      * @throws NullPointerException
       
  8213      *         if either array is {@code null}
       
  8214      * @since 9
       
  8215      */
       
  8216     public static int mismatch(int[] a, int aFromIndex, int aToIndex,
       
  8217                                int[] b, int bFromIndex, int bToIndex) {
       
  8218         rangeCheck(a.length, aFromIndex, aToIndex);
       
  8219         rangeCheck(b.length, bFromIndex, bToIndex);
       
  8220 
       
  8221         int aLength = aToIndex - aFromIndex;
       
  8222         int bLength = bToIndex - bFromIndex;
       
  8223         int length = Math.min(aLength, bLength);
       
  8224         int i = ArraysSupport.mismatch(a, aFromIndex,
       
  8225                                        b, bFromIndex,
       
  8226                                        length);
       
  8227         return (i < 0 && aLength != bLength) ? length : i;
       
  8228     }
       
  8229 
       
  8230     // Mismatch long
       
  8231 
       
  8232     /**
       
  8233      * Finds and returns the index of the first mismatch between two {@code long}
       
  8234      * arrays, otherwise return -1 if no mismatch is found.  The index will be
       
  8235      * in the range of 0 (inclusive) up to the length (inclusive) of the smaller
       
  8236      * array.
       
  8237      *
       
  8238      * <p>If the two arrays share a common prefix then the returned index is the
       
  8239      * length of the common prefix and it follows that there is a mismatch
       
  8240      * between the two elements at that index within the respective arrays.
       
  8241      * If one array is a proper prefix of the other then the returned index is
       
  8242      * the length of the smaller array and it follows that the index is only
       
  8243      * valid for the larger array.
       
  8244      * Otherwise, there is no mismatch.
       
  8245      *
       
  8246      * <p>Two non-{@code null} arrays, {@code a} and {@code b}, share a common
       
  8247      * prefix of length {@code pl} if the following expression is true:
       
  8248      * <pre>{@code
       
  8249      *     pl >= 0 &&
       
  8250      *     pl < Math.min(a.length, b.length) &&
       
  8251      *     Arrays.equals(a, 0, pl, b, 0, pl) &&
       
  8252      *     a[pl] != b[pl]
       
  8253      * }</pre>
       
  8254      * Note that a common prefix length of {@code 0} indicates that the first
       
  8255      * elements from each array mismatch.
       
  8256      *
       
  8257      * <p>Two non-{@code null} arrays, {@code a} and {@code b}, share a proper
       
  8258      * prefix if the following expression is true:
       
  8259      * <pre>{@code
       
  8260      *     a.length != b.length &&
       
  8261      *     Arrays.equals(a, 0, Math.min(a.length, b.length),
       
  8262      *                   b, 0, Math.min(a.length, b.length))
       
  8263      * }</pre>
       
  8264      *
       
  8265      * @param a the first array to be tested for a mismatch
       
  8266      * @param b the second array to be tested for a mismatch
       
  8267      * @return the index of the first mismatch between the two arrays,
       
  8268      *         otherwise {@code -1}.
       
  8269      * @throws NullPointerException
       
  8270      *         if either array is {@code null}
       
  8271      * @since 9
       
  8272      */
       
  8273     public static int mismatch(long[] a, long[] b) {
       
  8274         int length = Math.min(a.length, b.length); // Check null array refs
       
  8275         if (a == b)
       
  8276             return -1;
       
  8277 
       
  8278         int i = ArraysSupport.mismatch(a, b, length);
       
  8279         return (i < 0 && a.length != b.length) ? length : i;
       
  8280     }
       
  8281 
       
  8282     /**
       
  8283      * Finds and returns the relative index of the first mismatch between two
       
  8284      * {@code long} arrays over the specified ranges, otherwise return -1 if no
       
  8285      * mismatch is found.  The index will be in the range of 0 (inclusive) up to
       
  8286      * the length (inclusive) of the smaller range.
       
  8287      *
       
  8288      * <p>If the two arrays, over the specified ranges, share a common prefix
       
  8289      * then the returned relative index is the length of the common prefix and
       
  8290      * it follows that there is a mismatch between the two elements at that
       
  8291      * relative index within the respective arrays.
       
  8292      * If one array is a proper prefix of the other, over the specified ranges,
       
  8293      * then the returned relative index is the length of the smaller range and
       
  8294      * it follows that the relative index is only valid for the array with the
       
  8295      * larger range.
       
  8296      * Otherwise, there is no mismatch.
       
  8297      *
       
  8298      * <p>Two non-{@code null} arrays, {@code a} and {@code b} with specified
       
  8299      * ranges [{@code aFromIndex}, {@code atoIndex}) and
       
  8300      * [{@code bFromIndex}, {@code btoIndex}) respectively, share a common
       
  8301      * prefix of length {@code pl} if the following expression is true:
       
  8302      * <pre>{@code
       
  8303      *     pl >= 0 &&
       
  8304      *     pl < Math.min(aToIndex - aFromIndex, bToIndex - bFromIndex) &&
       
  8305      *     Arrays.equals(a, aFromIndex, aFromIndex + pl, b, bFromIndex, bFromIndex + pl) &&
       
  8306      *     a[aFromIndex + pl] != b[bFromIndex + pl]
       
  8307      * }</pre>
       
  8308      * Note that a common prefix length of {@code 0} indicates that the first
       
  8309      * elements from each array mismatch.
       
  8310      *
       
  8311      * <p>Two non-{@code null} arrays, {@code a} and {@code b} with specified
       
  8312      * ranges [{@code aFromIndex}, {@code atoIndex}) and
       
  8313      * [{@code bFromIndex}, {@code btoIndex}) respectively, share a proper
       
  8314      * if the following expression is true:
       
  8315      * <pre>{@code
       
  8316      *     (aToIndex - aFromIndex) != (bToIndex - bFromIndex) &&
       
  8317      *     Arrays.equals(a, 0, Math.min(aToIndex - aFromIndex, bToIndex - bFromIndex),
       
  8318      *                   b, 0, Math.min(aToIndex - aFromIndex, bToIndex - bFromIndex))
       
  8319      * }</pre>
       
  8320      *
       
  8321      * @param a the first array to be tested for a mismatch
       
  8322      * @param aFromIndex the index (inclusive) of the first element in the
       
  8323      *                   first array to be tested
       
  8324      * @param aToIndex the index (exclusive) of the last element in the
       
  8325      *                 first array to be tested
       
  8326      * @param b the second array to be tested for a mismatch
       
  8327      * @param bFromIndex the index (inclusive) of the first element in the
       
  8328      *                   second array to be tested
       
  8329      * @param bToIndex the index (exclusive) of the last element in the
       
  8330      *                 second array to be tested
       
  8331      * @return the relative index of the first mismatch between the two arrays
       
  8332      *         over the specified ranges, otherwise {@code -1}.
       
  8333      * @throws IllegalArgumentException
       
  8334      *         if {@code aFromIndex > aToIndex} or
       
  8335      *         if {@code bFromIndex > bToIndex}
       
  8336      * @throws ArrayIndexOutOfBoundsException
       
  8337      *         if {@code aFromIndex < 0 or aToIndex > a.length} or
       
  8338      *         if {@code bFromIndex < 0 or bToIndex > b.length}
       
  8339      * @throws NullPointerException
       
  8340      *         if either array is {@code null}
       
  8341      * @since 9
       
  8342      */
       
  8343     public static int mismatch(long[] a, int aFromIndex, int aToIndex,
       
  8344                                long[] b, int bFromIndex, int bToIndex) {
       
  8345         rangeCheck(a.length, aFromIndex, aToIndex);
       
  8346         rangeCheck(b.length, bFromIndex, bToIndex);
       
  8347 
       
  8348         int aLength = aToIndex - aFromIndex;
       
  8349         int bLength = bToIndex - bFromIndex;
       
  8350         int length = Math.min(aLength, bLength);
       
  8351         int i = ArraysSupport.mismatch(a, aFromIndex,
       
  8352                                        b, bFromIndex,
       
  8353                                        length);
       
  8354         return (i < 0 && aLength != bLength) ? length : i;
       
  8355     }
       
  8356 
       
  8357     // Mismatch float
       
  8358 
       
  8359     /**
       
  8360      * Finds and returns the index of the first mismatch between two {@code float}
       
  8361      * arrays, otherwise return -1 if no mismatch is found.  The index will be
       
  8362      * in the range of 0 (inclusive) up to the length (inclusive) of the smaller
       
  8363      * array.
       
  8364      *
       
  8365      * <p>If the two arrays share a common prefix then the returned index is the
       
  8366      * length of the common prefix and it follows that there is a mismatch
       
  8367      * between the two elements at that index within the respective arrays.
       
  8368      * If one array is a proper prefix of the other then the returned index is
       
  8369      * the length of the smaller array and it follows that the index is only
       
  8370      * valid for the larger array.
       
  8371      * Otherwise, there is no mismatch.
       
  8372      *
       
  8373      * <p>Two non-{@code null} arrays, {@code a} and {@code b}, share a common
       
  8374      * prefix of length {@code pl} if the following expression is true:
       
  8375      * <pre>{@code
       
  8376      *     pl >= 0 &&
       
  8377      *     pl < Math.min(a.length, b.length) &&
       
  8378      *     Arrays.equals(a, 0, pl, b, 0, pl) &&
       
  8379      *     Float.compare(a[pl], b[pl]) != 0
       
  8380      * }</pre>
       
  8381      * Note that a common prefix length of {@code 0} indicates that the first
       
  8382      * elements from each array mismatch.
       
  8383      *
       
  8384      * <p>Two non-{@code null} arrays, {@code a} and {@code b}, share a proper
       
  8385      * prefix if the following expression is true:
       
  8386      * <pre>{@code
       
  8387      *     a.length != b.length &&
       
  8388      *     Arrays.equals(a, 0, Math.min(a.length, b.length),
       
  8389      *                   b, 0, Math.min(a.length, b.length))
       
  8390      * }</pre>
       
  8391      *
       
  8392      * @param a the first array to be tested for a mismatch
       
  8393      * @param b the second array to be tested for a mismatch
       
  8394      * @return the index of the first mismatch between the two arrays,
       
  8395      *         otherwise {@code -1}.
       
  8396      * @throws NullPointerException
       
  8397      *         if either array is {@code null}
       
  8398      * @since 9
       
  8399      */
       
  8400     public static int mismatch(float[] a, float[] b) {
       
  8401         int length = Math.min(a.length, b.length); // Check null array refs
       
  8402         if (a == b)
       
  8403             return -1;
       
  8404 
       
  8405         int i = ArraysSupport.mismatch(a, b, length);
       
  8406         return (i < 0 && a.length != b.length) ? length : i;
       
  8407     }
       
  8408 
       
  8409     /**
       
  8410      * Finds and returns the relative index of the first mismatch between two
       
  8411      * {@code float} arrays over the specified ranges, otherwise return -1 if no
       
  8412      * mismatch is found.  The index will be in the range of 0 (inclusive) up to
       
  8413      * the length (inclusive) of the smaller range.
       
  8414      *
       
  8415      * <p>If the two arrays, over the specified ranges, share a common prefix
       
  8416      * then the returned relative index is the length of the common prefix and
       
  8417      * it follows that there is a mismatch between the two elements at that
       
  8418      * relative index within the respective arrays.
       
  8419      * If one array is a proper prefix of the other, over the specified ranges,
       
  8420      * then the returned relative index is the length of the smaller range and
       
  8421      * it follows that the relative index is only valid for the array with the
       
  8422      * larger range.
       
  8423      * Otherwise, there is no mismatch.
       
  8424      *
       
  8425      * <p>Two non-{@code null} arrays, {@code a} and {@code b} with specified
       
  8426      * ranges [{@code aFromIndex}, {@code atoIndex}) and
       
  8427      * [{@code bFromIndex}, {@code btoIndex}) respectively, share a common
       
  8428      * prefix of length {@code pl} if the following expression is true:
       
  8429      * <pre>{@code
       
  8430      *     pl >= 0 &&
       
  8431      *     pl < Math.min(aToIndex - aFromIndex, bToIndex - bFromIndex) &&
       
  8432      *     Arrays.equals(a, aFromIndex, aFromIndex + pl, b, bFromIndex, bFromIndex + pl) &&
       
  8433      *     Float.compare(a[aFromIndex + pl], b[bFromIndex + pl]) != 0
       
  8434      * }</pre>
       
  8435      * Note that a common prefix length of {@code 0} indicates that the first
       
  8436      * elements from each array mismatch.
       
  8437      *
       
  8438      * <p>Two non-{@code null} arrays, {@code a} and {@code b} with specified
       
  8439      * ranges [{@code aFromIndex}, {@code atoIndex}) and
       
  8440      * [{@code bFromIndex}, {@code btoIndex}) respectively, share a proper
       
  8441      * if the following expression is true:
       
  8442      * <pre>{@code
       
  8443      *     (aToIndex - aFromIndex) != (bToIndex - bFromIndex) &&
       
  8444      *     Arrays.equals(a, 0, Math.min(aToIndex - aFromIndex, bToIndex - bFromIndex),
       
  8445      *                   b, 0, Math.min(aToIndex - aFromIndex, bToIndex - bFromIndex))
       
  8446      * }</pre>
       
  8447      *
       
  8448      * @param a the first array to be tested for a mismatch
       
  8449      * @param aFromIndex the index (inclusive) of the first element in the
       
  8450      *                   first array to be tested
       
  8451      * @param aToIndex the index (exclusive) of the last element in the
       
  8452      *                 first array to be tested
       
  8453      * @param b the second array to be tested for a mismatch
       
  8454      * @param bFromIndex the index (inclusive) of the first element in the
       
  8455      *                   second array to be tested
       
  8456      * @param bToIndex the index (exclusive) of the last element in the
       
  8457      *                 second array to be tested
       
  8458      * @return the relative index of the first mismatch between the two arrays
       
  8459      *         over the specified ranges, otherwise {@code -1}.
       
  8460      * @throws IllegalArgumentException
       
  8461      *         if {@code aFromIndex > aToIndex} or
       
  8462      *         if {@code bFromIndex > bToIndex}
       
  8463      * @throws ArrayIndexOutOfBoundsException
       
  8464      *         if {@code aFromIndex < 0 or aToIndex > a.length} or
       
  8465      *         if {@code bFromIndex < 0 or bToIndex > b.length}
       
  8466      * @throws NullPointerException
       
  8467      *         if either array is {@code null}
       
  8468      * @since 9
       
  8469      */
       
  8470     public static int mismatch(float[] a, int aFromIndex, int aToIndex,
       
  8471                                float[] b, int bFromIndex, int bToIndex) {
       
  8472         rangeCheck(a.length, aFromIndex, aToIndex);
       
  8473         rangeCheck(b.length, bFromIndex, bToIndex);
       
  8474 
       
  8475         int aLength = aToIndex - aFromIndex;
       
  8476         int bLength = bToIndex - bFromIndex;
       
  8477         int length = Math.min(aLength, bLength);
       
  8478         int i = ArraysSupport.mismatch(a, aFromIndex,
       
  8479                                        b, bFromIndex,
       
  8480                                        length);
       
  8481         return (i < 0 && aLength != bLength) ? length : i;
       
  8482     }
       
  8483 
       
  8484     // Mismatch double
       
  8485 
       
  8486     /**
       
  8487      * Finds and returns the index of the first mismatch between two
       
  8488      * {@code double} arrays, otherwise return -1 if no mismatch is found.  The
       
  8489      * index will be in the range of 0 (inclusive) up to the length (inclusive)
       
  8490      * of the smaller array.
       
  8491      *
       
  8492      * <p>If the two arrays share a common prefix then the returned index is the
       
  8493      * length of the common prefix and it follows that there is a mismatch
       
  8494      * between the two elements at that index within the respective arrays.
       
  8495      * If one array is a proper prefix of the other then the returned index is
       
  8496      * the length of the smaller array and it follows that the index is only
       
  8497      * valid for the larger array.
       
  8498      * Otherwise, there is no mismatch.
       
  8499      *
       
  8500      * <p>Two non-{@code null} arrays, {@code a} and {@code b}, share a common
       
  8501      * prefix of length {@code pl} if the following expression is true:
       
  8502      * <pre>{@code
       
  8503      *     pl >= 0 &&
       
  8504      *     pl < Math.min(a.length, b.length) &&
       
  8505      *     Arrays.equals(a, 0, pl, b, 0, pl) &&
       
  8506      *     Double.compare(a[pl], b[pl]) != 0
       
  8507      * }</pre>
       
  8508      * Note that a common prefix length of {@code 0} indicates that the first
       
  8509      * elements from each array mismatch.
       
  8510      *
       
  8511      * <p>Two non-{@code null} arrays, {@code a} and {@code b}, share a proper
       
  8512      * prefix if the following expression is true:
       
  8513      * <pre>{@code
       
  8514      *     a.length != b.length &&
       
  8515      *     Arrays.equals(a, 0, Math.min(a.length, b.length),
       
  8516      *                   b, 0, Math.min(a.length, b.length))
       
  8517      * }</pre>
       
  8518      *
       
  8519      * @param a the first array to be tested for a mismatch
       
  8520      * @param b the second array to be tested for a mismatch
       
  8521      * @return the index of the first mismatch between the two arrays,
       
  8522      *         otherwise {@code -1}.
       
  8523      * @throws NullPointerException
       
  8524      *         if either array is {@code null}
       
  8525      * @since 9
       
  8526      */
       
  8527     public static int mismatch(double[] a, double[] b) {
       
  8528         int length = Math.min(a.length, b.length); // Check null array refs
       
  8529         if (a == b)
       
  8530             return -1;
       
  8531 
       
  8532         int i = ArraysSupport.mismatch(a, b, length);
       
  8533         return (i < 0 && a.length != b.length) ? length : i;
       
  8534     }
       
  8535 
       
  8536     /**
       
  8537      * Finds and returns the relative index of the first mismatch between two
       
  8538      * {@code double} arrays over the specified ranges, otherwise return -1 if
       
  8539      * no mismatch is found.  The index will be in the range of 0 (inclusive) up
       
  8540      * to the length (inclusive) of the smaller range.
       
  8541      *
       
  8542      * <p>If the two arrays, over the specified ranges, share a common prefix
       
  8543      * then the returned relative index is the length of the common prefix and
       
  8544      * it follows that there is a mismatch between the two elements at that
       
  8545      * relative index within the respective arrays.
       
  8546      * If one array is a proper prefix of the other, over the specified ranges,
       
  8547      * then the returned relative index is the length of the smaller range and
       
  8548      * it follows that the relative index is only valid for the array with the
       
  8549      * larger range.
       
  8550      * Otherwise, there is no mismatch.
       
  8551      *
       
  8552      * <p>Two non-{@code null} arrays, {@code a} and {@code b} with specified
       
  8553      * ranges [{@code aFromIndex}, {@code atoIndex}) and
       
  8554      * [{@code bFromIndex}, {@code btoIndex}) respectively, share a common
       
  8555      * prefix of length {@code pl} if the following expression is true:
       
  8556      * <pre>{@code
       
  8557      *     pl >= 0 &&
       
  8558      *     pl < Math.min(aToIndex - aFromIndex, bToIndex - bFromIndex) &&
       
  8559      *     Arrays.equals(a, aFromIndex, aFromIndex + pl, b, bFromIndex, bFromIndex + pl) &&
       
  8560      *     Double.compare(a[aFromIndex + pl], b[bFromIndex + pl]) != 0
       
  8561      * }</pre>
       
  8562      * Note that a common prefix length of {@code 0} indicates that the first
       
  8563      * elements from each array mismatch.
       
  8564      *
       
  8565      * <p>Two non-{@code null} arrays, {@code a} and {@code b} with specified
       
  8566      * ranges [{@code aFromIndex}, {@code atoIndex}) and
       
  8567      * [{@code bFromIndex}, {@code btoIndex}) respectively, share a proper
       
  8568      * if the following expression is true:
       
  8569      * <pre>{@code
       
  8570      *     (aToIndex - aFromIndex) != (bToIndex - bFromIndex) &&
       
  8571      *     Arrays.equals(a, 0, Math.min(aToIndex - aFromIndex, bToIndex - bFromIndex),
       
  8572      *                   b, 0, Math.min(aToIndex - aFromIndex, bToIndex - bFromIndex))
       
  8573      * }</pre>
       
  8574      *
       
  8575      * @param a the first array to be tested for a mismatch
       
  8576      * @param aFromIndex the index (inclusive) of the first element in the
       
  8577      *                   first array to be tested
       
  8578      * @param aToIndex the index (exclusive) of the last element in the
       
  8579      *                 first array to be tested
       
  8580      * @param b the second array to be tested for a mismatch
       
  8581      * @param bFromIndex the index (inclusive) of the first element in the
       
  8582      *                   second array to be tested
       
  8583      * @param bToIndex the index (exclusive) of the last element in the
       
  8584      *                 second array to be tested
       
  8585      * @return the relative index of the first mismatch between the two arrays
       
  8586      *         over the specified ranges, otherwise {@code -1}.
       
  8587      * @throws IllegalArgumentException
       
  8588      *         if {@code aFromIndex > aToIndex} or
       
  8589      *         if {@code bFromIndex > bToIndex}
       
  8590      * @throws ArrayIndexOutOfBoundsException
       
  8591      *         if {@code aFromIndex < 0 or aToIndex > a.length} or
       
  8592      *         if {@code bFromIndex < 0 or bToIndex > b.length}
       
  8593      * @throws NullPointerException
       
  8594      *         if either array is {@code null}
       
  8595      * @since 9
       
  8596      */
       
  8597     public static int mismatch(double[] a, int aFromIndex, int aToIndex,
       
  8598                                double[] b, int bFromIndex, int bToIndex) {
       
  8599         rangeCheck(a.length, aFromIndex, aToIndex);
       
  8600         rangeCheck(b.length, bFromIndex, bToIndex);
       
  8601 
       
  8602         int aLength = aToIndex - aFromIndex;
       
  8603         int bLength = bToIndex - bFromIndex;
       
  8604         int length = Math.min(aLength, bLength);
       
  8605         int i = ArraysSupport.mismatch(a, aFromIndex,
       
  8606                                        b, bFromIndex,
       
  8607                                        length);
       
  8608         return (i < 0 && aLength != bLength) ? length : i;
       
  8609     }
       
  8610 
       
  8611     // Mismatch objects
       
  8612 
       
  8613     /**
       
  8614      * Finds and returns the index of the first mismatch between two
       
  8615      * {@code Object} arrays, otherwise return -1 if no mismatch is found.  The
       
  8616      * index will be in the range of 0 (inclusive) up to the length (inclusive)
       
  8617      * of the smaller array.
       
  8618      *
       
  8619      * <p>If the two arrays share a common prefix then the returned index is the
       
  8620      * length of the common prefix and it follows that there is a mismatch
       
  8621      * between the two elements at that index within the respective arrays.
       
  8622      * If one array is a proper prefix of the other then the returned index is
       
  8623      * the length of the smaller array and it follows that the index is only
       
  8624      * valid for the larger array.
       
  8625      * Otherwise, there is no mismatch.
       
  8626      *
       
  8627      * <p>Two non-{@code null} arrays, {@code a} and {@code b}, share a common
       
  8628      * prefix of length {@code pl} if the following expression is true:
       
  8629      * <pre>{@code
       
  8630      *     pl >= 0 &&
       
  8631      *     pl < Math.min(a.length, b.length) &&
       
  8632      *     Arrays.equals(a, 0, pl, b, 0, pl) &&
       
  8633      *     !Objects.equals(a[pl], b[pl])
       
  8634      * }</pre>
       
  8635      * Note that a common prefix length of {@code 0} indicates that the first
       
  8636      * elements from each array mismatch.
       
  8637      *
       
  8638      * <p>Two non-{@code null} arrays, {@code a} and {@code b}, share a proper
       
  8639      * prefix if the following expression is true:
       
  8640      * <pre>{@code
       
  8641      *     a.length != b.length &&
       
  8642      *     Arrays.equals(a, 0, Math.min(a.length, b.length),
       
  8643      *                   b, 0, Math.min(a.length, b.length))
       
  8644      * }</pre>
       
  8645      *
       
  8646      * @param a the first array to be tested for a mismatch
       
  8647      * @param b the second array to be tested for a mismatch
       
  8648      * @return the index of the first mismatch between the two arrays,
       
  8649      *         otherwise {@code -1}.
       
  8650      * @throws NullPointerException
       
  8651      *         if either array is {@code null}
       
  8652      * @since 9
       
  8653      */
       
  8654     public static int mismatch(Object[] a, Object[] b) {
       
  8655         int length = Math.min(a.length, b.length); // Check null array refs
       
  8656         if (a == b)
       
  8657             return -1;
       
  8658 
       
  8659         for (int i = 0; i < length; i++) {
       
  8660             if (!Objects.equals(a[i], b[i]))
       
  8661                 return i;
       
  8662         }
       
  8663 
       
  8664         return a.length != b.length ? length : -1;
       
  8665     }
       
  8666 
       
  8667     /**
       
  8668      * Finds and returns the relative index of the first mismatch between two
       
  8669      * {@code Object} arrays over the specified ranges, otherwise return -1 if
       
  8670      * no mismatch is found.  The index will be in the range of 0 (inclusive) up
       
  8671      * to the length (inclusive) of the smaller range.
       
  8672      *
       
  8673      * <p>If the two arrays, over the specified ranges, share a common prefix
       
  8674      * then the returned relative index is the length of the common prefix and
       
  8675      * it follows that there is a mismatch between the two elements at that
       
  8676      * relative index within the respective arrays.
       
  8677      * If one array is a proper prefix of the other, over the specified ranges,
       
  8678      * then the returned relative index is the length of the smaller range and
       
  8679      * it follows that the relative index is only valid for the array with the
       
  8680      * larger range.
       
  8681      * Otherwise, there is no mismatch.
       
  8682      *
       
  8683      * <p>Two non-{@code null} arrays, {@code a} and {@code b} with specified
       
  8684      * ranges [{@code aFromIndex}, {@code atoIndex}) and
       
  8685      * [{@code bFromIndex}, {@code btoIndex}) respectively, share a common
       
  8686      * prefix of length {@code pl} if the following expression is true:
       
  8687      * <pre>{@code
       
  8688      *     pl >= 0 &&
       
  8689      *     pl < Math.min(aToIndex - aFromIndex, bToIndex - bFromIndex) &&
       
  8690      *     Arrays.equals(a, aFromIndex, aFromIndex + pl, b, bFromIndex, bFromIndex + pl) &&
       
  8691      *     !Objects.equals(a[aFromIndex + pl], b[bFromIndex + pl])
       
  8692      * }</pre>
       
  8693      * Note that a common prefix length of {@code 0} indicates that the first
       
  8694      * elements from each array mismatch.
       
  8695      *
       
  8696      * <p>Two non-{@code null} arrays, {@code a} and {@code b} with specified
       
  8697      * ranges [{@code aFromIndex}, {@code atoIndex}) and
       
  8698      * [{@code bFromIndex}, {@code btoIndex}) respectively, share a proper
       
  8699      * if the following expression is true:
       
  8700      * <pre>{@code
       
  8701      *     (aToIndex - aFromIndex) != (bToIndex - bFromIndex) &&
       
  8702      *     Arrays.equals(a, 0, Math.min(aToIndex - aFromIndex, bToIndex - bFromIndex),
       
  8703      *                   b, 0, Math.min(aToIndex - aFromIndex, bToIndex - bFromIndex))
       
  8704      * }</pre>
       
  8705      *
       
  8706      * @param a the first array to be tested for a mismatch
       
  8707      * @param aFromIndex the index (inclusive) of the first element in the
       
  8708      *                   first array to be tested
       
  8709      * @param aToIndex the index (exclusive) of the last element in the
       
  8710      *                 first array to be tested
       
  8711      * @param b the second array to be tested for a mismatch
       
  8712      * @param bFromIndex the index (inclusive) of the first element in the
       
  8713      *                   second array to be tested
       
  8714      * @param bToIndex the index (exclusive) of the last element in the
       
  8715      *                 second array to be tested
       
  8716      * @return the relative index of the first mismatch between the two arrays
       
  8717      *         over the specified ranges, otherwise {@code -1}.
       
  8718      * @throws IllegalArgumentException
       
  8719      *         if {@code aFromIndex > aToIndex} or
       
  8720      *         if {@code bFromIndex > bToIndex}
       
  8721      * @throws ArrayIndexOutOfBoundsException
       
  8722      *         if {@code aFromIndex < 0 or aToIndex > a.length} or
       
  8723      *         if {@code bFromIndex < 0 or bToIndex > b.length}
       
  8724      * @throws NullPointerException
       
  8725      *         if either array is {@code null}
       
  8726      * @since 9
       
  8727      */
       
  8728     public static int mismatch(
       
  8729             Object[] a, int aFromIndex, int aToIndex,
       
  8730             Object[] b, int bFromIndex, int bToIndex) {
       
  8731         rangeCheck(a.length, aFromIndex, aToIndex);
       
  8732         rangeCheck(b.length, bFromIndex, bToIndex);
       
  8733 
       
  8734         int aLength = aToIndex - aFromIndex;
       
  8735         int bLength = bToIndex - bFromIndex;
       
  8736         int length = Math.min(aLength, bLength);
       
  8737         for (int i = 0; i < length; i++) {
       
  8738             if (!Objects.equals(a[aFromIndex++], b[bFromIndex++]))
       
  8739                 return i;
       
  8740         }
       
  8741 
       
  8742         return aLength != bLength ? length : -1;
       
  8743     }
       
  8744 
       
  8745     /**
       
  8746      * Finds and returns the index of the first mismatch between two
       
  8747      * {@code Object} arrays, otherwise return -1 if no mismatch is found.
       
  8748      * The index will be in the range of 0 (inclusive) up to the length
       
  8749      * (inclusive) of the smaller array.
       
  8750      *
       
  8751      * <p>The specified comparator is used to determine if two array elements
       
  8752      * from the each array are not equal.
       
  8753      *
       
  8754      * <p>If the two arrays share a common prefix then the returned index is the
       
  8755      * length of the common prefix and it follows that there is a mismatch
       
  8756      * between the two elements at that index within the respective arrays.
       
  8757      * If one array is a proper prefix of the other then the returned index is
       
  8758      * the length of the smaller array and it follows that the index is only
       
  8759      * valid for the larger array.
       
  8760      * Otherwise, there is no mismatch.
       
  8761      *
       
  8762      * <p>Two non-{@code null} arrays, {@code a} and {@code b}, share a common
       
  8763      * prefix of length {@code pl} if the following expression is true:
       
  8764      * <pre>{@code
       
  8765      *     pl >= 0 &&
       
  8766      *     pl < Math.min(a.length, b.length) &&
       
  8767      *     Arrays.equals(a, 0, pl, b, 0, pl, cmp)
       
  8768      *     cmp.compare(a[pl], b[pl]) != 0
       
  8769      * }</pre>
       
  8770      * Note that a common prefix length of {@code 0} indicates that the first
       
  8771      * elements from each array mismatch.
       
  8772      *
       
  8773      * <p>Two non-{@code null} arrays, {@code a} and {@code b}, share a proper
       
  8774      * prefix if the following expression is true:
       
  8775      * <pre>{@code
       
  8776      *     a.length != b.length &&
       
  8777      *     Arrays.equals(a, 0, Math.min(a.length, b.length),
       
  8778      *                   b, 0, Math.min(a.length, b.length),
       
  8779      *                   cmp)
       
  8780      * }</pre>
       
  8781      *
       
  8782      * @param a the first array to be tested for a mismatch
       
  8783      * @param b the second array to be tested for a mismatch
       
  8784      * @param cmp the comparator to compare array elements
       
  8785      * @param <T> the type of array elements
       
  8786      * @return the index of the first mismatch between the two arrays,
       
  8787      *         otherwise {@code -1}.
       
  8788      * @throws NullPointerException
       
  8789      *         if either array or the comparator is {@code null}
       
  8790      * @since 9
       
  8791      */
       
  8792     public static <T> int mismatch(T[] a, T[] b, Comparator<? super T> cmp) {
       
  8793         Objects.requireNonNull(cmp);
       
  8794         int length = Math.min(a.length, b.length); // Check null array refs
       
  8795         if (a == b)
       
  8796             return -1;
       
  8797 
       
  8798         for (int i = 0; i < length; i++) {
       
  8799             T oa = a[i];
       
  8800             T ob = b[i];
       
  8801             if (oa != ob) {
       
  8802                 // Null-value comparison is deferred to the comparator
       
  8803                 int v = cmp.compare(oa, ob);
       
  8804                 if (v != 0) {
       
  8805                     return i;
       
  8806                 }
       
  8807             }
       
  8808         }
       
  8809 
       
  8810         return a.length != b.length ? length : -1;
       
  8811     }
       
  8812 
       
  8813     /**
       
  8814      * Finds and returns the relative index of the first mismatch between two
       
  8815      * {@code Object} arrays over the specified ranges, otherwise return -1 if
       
  8816      * no mismatch is found.  The index will be in the range of 0 (inclusive) up
       
  8817      * to the length (inclusive) of the smaller range.
       
  8818      *
       
  8819      * <p>If the two arrays, over the specified ranges, share a common prefix
       
  8820      * then the returned relative index is the length of the common prefix and
       
  8821      * it follows that there is a mismatch between the two elements at that
       
  8822      * relative index within the respective arrays.
       
  8823      * If one array is a proper prefix of the other, over the specified ranges,
       
  8824      * then the returned relative index is the length of the smaller range and
       
  8825      * it follows that the relative index is only valid for the array with the
       
  8826      * larger range.
       
  8827      * Otherwise, there is no mismatch.
       
  8828      *
       
  8829      * <p>Two non-{@code null} arrays, {@code a} and {@code b} with specified
       
  8830      * ranges [{@code aFromIndex}, {@code atoIndex}) and
       
  8831      * [{@code bFromIndex}, {@code btoIndex}) respectively, share a common
       
  8832      * prefix of length {@code pl} if the following expression is true:
       
  8833      * <pre>{@code
       
  8834      *     pl >= 0 &&
       
  8835      *     pl < Math.min(aToIndex - aFromIndex, bToIndex - bFromIndex) &&
       
  8836      *     Arrays.equals(a, aFromIndex, aFromIndex + pl, b, bFromIndex, bFromIndex + pl, cmp) &&
       
  8837      *     cmp.compare(a[aFromIndex + pl], b[bFromIndex + pl]) != 0
       
  8838      * }</pre>
       
  8839      * Note that a common prefix length of {@code 0} indicates that the first
       
  8840      * elements from each array mismatch.
       
  8841      *
       
  8842      * <p>Two non-{@code null} arrays, {@code a} and {@code b} with specified
       
  8843      * ranges [{@code aFromIndex}, {@code atoIndex}) and
       
  8844      * [{@code bFromIndex}, {@code btoIndex}) respectively, share a proper
       
  8845      * if the following expression is true:
       
  8846      * <pre>{@code
       
  8847      *     (aToIndex - aFromIndex) != (bToIndex - bFromIndex) &&
       
  8848      *     Arrays.equals(a, 0, Math.min(aToIndex - aFromIndex, bToIndex - bFromIndex),
       
  8849      *                   b, 0, Math.min(aToIndex - aFromIndex, bToIndex - bFromIndex),
       
  8850      *                   cmp)
       
  8851      * }</pre>
       
  8852      *
       
  8853      * @param a the first array to be tested for a mismatch
       
  8854      * @param aFromIndex the index (inclusive) of the first element in the
       
  8855      *                   first array to be tested
       
  8856      * @param aToIndex the index (exclusive) of the last element in the
       
  8857      *                 first array to be tested
       
  8858      * @param b the second array to be tested for a mismatch
       
  8859      * @param bFromIndex the index (inclusive) of the first element in the
       
  8860      *                   second array to be tested
       
  8861      * @param bToIndex the index (exclusive) of the last element in the
       
  8862      *                 second array to be tested
       
  8863      * @param cmp the comparator to compare array elements
       
  8864      * @param <T> the type of array elements
       
  8865      * @return the relative index of the first mismatch between the two arrays
       
  8866      *         over the specified ranges, otherwise {@code -1}.
       
  8867      * @throws IllegalArgumentException
       
  8868      *         if {@code aFromIndex > aToIndex} or
       
  8869      *         if {@code bFromIndex > bToIndex}
       
  8870      * @throws ArrayIndexOutOfBoundsException
       
  8871      *         if {@code aFromIndex < 0 or aToIndex > a.length} or
       
  8872      *         if {@code bFromIndex < 0 or bToIndex > b.length}
       
  8873      * @throws NullPointerException
       
  8874      *         if either array or the comparator is {@code null}
       
  8875      * @since 9
       
  8876      */
       
  8877     public static <T> int mismatch(
       
  8878             T[] a, int aFromIndex, int aToIndex,
       
  8879             T[] b, int bFromIndex, int bToIndex,
       
  8880             Comparator<? super T> cmp) {
       
  8881         Objects.requireNonNull(cmp);
       
  8882         rangeCheck(a.length, aFromIndex, aToIndex);
       
  8883         rangeCheck(b.length, bFromIndex, bToIndex);
       
  8884 
       
  8885         int aLength = aToIndex - aFromIndex;
       
  8886         int bLength = bToIndex - bFromIndex;
       
  8887         int length = Math.min(aLength, bLength);
       
  8888         for (int i = 0; i < length; i++) {
       
  8889             T oa = a[aFromIndex++];
       
  8890             T ob = b[bFromIndex++];
       
  8891             if (oa != ob) {
       
  8892                 // Null-value comparison is deferred to the comparator
       
  8893                 int v = cmp.compare(oa, ob);
       
  8894                 if (v != 0) {
       
  8895                     return i;
       
  8896                 }
       
  8897             }
       
  8898         }
       
  8899 
       
  8900         return aLength != bLength ? length : -1;
       
  8901     }
       
  8902 }