1 /*
   2  * Copyright (c) 1997, 2014, 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}/../technotes/guides/collections/index.html">
  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     private 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         for (int i=0; i<length; i++)
2583             if (a[i] != a2[i])
2584                 return false;
2585 
2586         return true;
2587     }
2588 
2589     /**
2590      * Returns true if the two specified arrays of longs, over the specified
2591      * ranges, are <i>equal</i> to one another.
2592      *
2593      * <p>Two arrays are considered equal if the number of elements covered by
2594      * each range is the same, and all corresponding pairs of elements over the
2595      * specified ranges in the two arrays are equal.  In other words, two arrays
2596      * are equal if they contain, over the specified ranges, the same elements
2597      * in the same order.
2598      *
2599      * @param a the first array to be tested for equality
2600      * @param aFromIndex the index (inclusive) of the first element in the
2601      *                   first array to be tested
2602      * @param aToIndex the index (exclusive) of the last element in the
2603      *                 first array to be tested
2604      * @param b the second array to be tested fro equality
2605      * @param bFromIndex the index (inclusive) of the first element in the
2606      *                   second array to be tested
2607      * @param bToIndex the index (exclusive) of the last element in the
2608      *                 second array to be tested
2609      * @return {@code true} if the two arrays, over the specified ranges, are
2610      *         equal
2611      * @throws IllegalArgumentException
2612      *         if {@code aFromIndex > aToIndex} or
2613      *         if {@code bFromIndex > bToIndex}
2614      * @throws ArrayIndexOutOfBoundsException
2615      *         if {@code aFromIndex < 0 or aToIndex > a.length} or
2616      *         if {@code bFromIndex < 0 or bToIndex > b.length}
2617      * @throws NullPointerException
2618      *         if either array is {@code null}
2619      * @since 9
2620      */
2621     public static boolean equals(long[] a, int aFromIndex, int aToIndex,
2622                                  long[] b, int bFromIndex, int bToIndex) {
2623         rangeCheck(a.length, aFromIndex, aToIndex);
2624         rangeCheck(b.length, bFromIndex, bToIndex);
2625 
2626         int aLength = aToIndex - aFromIndex;
2627         int bLength = bToIndex - bFromIndex;
2628         if (aLength != bLength)
2629             return false;
2630 
2631         for (int i = 0; i < aLength; i++)
2632             if (a[aFromIndex++] != b[bFromIndex++])
2633                 return false;
2634 
2635         return true;
2636     }
2637 
2638     /**
2639      * Returns {@code true} if the two specified arrays of ints are
2640      * <i>equal</i> to one another.  Two arrays are considered equal if both
2641      * arrays contain the same number of elements, and all corresponding pairs
2642      * of elements in the two arrays are equal.  In other words, two arrays
2643      * are equal if they contain the same elements in the same order.  Also,
2644      * two array references are considered equal if both are {@code null}.
2645      *
2646      * @param a one array to be tested for equality
2647      * @param a2 the other array to be tested for equality
2648      * @return {@code true} if the two arrays are equal
2649      */
2650     public static boolean equals(int[] a, int[] a2) {
2651         if (a==a2)
2652             return true;
2653         if (a==null || a2==null)
2654             return false;
2655 
2656         int length = a.length;
2657         if (a2.length != length)
2658             return false;
2659 
2660         for (int i=0; i<length; i++)
2661             if (a[i] != a2[i])
2662                 return false;
2663 
2664         return true;
2665     }
2666 
2667     /**
2668      * Returns true if the two specified arrays of ints, over the specified
2669      * ranges, are <i>equal</i> to one another.
2670      *
2671      * <p>Two arrays are considered equal if the number of elements covered by
2672      * each range is the same, and all corresponding pairs of elements over the
2673      * specified ranges in the two arrays are equal.  In other words, two arrays
2674      * are equal if they contain, over the specified ranges, the same elements
2675      * in the same order.
2676      *
2677      * @param a the first array to be tested for equality
2678      * @param aFromIndex the index (inclusive) of the first element in the
2679      *                   first array to be tested
2680      * @param aToIndex the index (exclusive) of the last element in the
2681      *                 first array to be tested
2682      * @param b the second array to be tested fro equality
2683      * @param bFromIndex the index (inclusive) of the first element in the
2684      *                   second array to be tested
2685      * @param bToIndex the index (exclusive) of the last element in the
2686      *                 second array to be tested
2687      * @return {@code true} if the two arrays, over the specified ranges, are
2688      *         equal
2689      * @throws IllegalArgumentException
2690      *         if {@code aFromIndex > aToIndex} or
2691      *         if {@code bFromIndex > bToIndex}
2692      * @throws ArrayIndexOutOfBoundsException
2693      *         if {@code aFromIndex < 0 or aToIndex > a.length} or
2694      *         if {@code bFromIndex < 0 or bToIndex > b.length}
2695      * @throws NullPointerException
2696      *         if either array is {@code null}
2697      * @since 9
2698      */
2699     public static boolean equals(int[] a, int aFromIndex, int aToIndex,
2700                                  int[] b, int bFromIndex, int bToIndex) {
2701         rangeCheck(a.length, aFromIndex, aToIndex);
2702         rangeCheck(b.length, bFromIndex, bToIndex);
2703 
2704         int aLength = aToIndex - aFromIndex;
2705         int bLength = bToIndex - bFromIndex;
2706         if (aLength != bLength)
2707             return false;
2708 
2709         for (int i = 0; i < aLength; i++)
2710             if (a[aFromIndex++] != b[bFromIndex++])
2711                 return false;
2712 
2713         return true;
2714     }
2715 
2716     /**
2717      * Returns {@code true} if the two specified arrays of shorts are
2718      * <i>equal</i> to one another.  Two arrays are considered equal if both
2719      * arrays contain the same number of elements, and all corresponding pairs
2720      * of elements in the two arrays are equal.  In other words, two arrays
2721      * are equal if they contain the same elements in the same order.  Also,
2722      * two array references are considered equal if both are {@code null}.
2723      *
2724      * @param a one array to be tested for equality
2725      * @param a2 the other array to be tested for equality
2726      * @return {@code true} if the two arrays are equal
2727      */
2728     public static boolean equals(short[] a, short a2[]) {
2729         if (a==a2)
2730             return true;
2731         if (a==null || a2==null)
2732             return false;
2733 
2734         int length = a.length;
2735         if (a2.length != length)
2736             return false;
2737 
2738         for (int i=0; i<length; i++)
2739             if (a[i] != a2[i])
2740                 return false;
2741 
2742         return true;
2743     }
2744 
2745     /**
2746      * Returns true if the two specified arrays of shorts, over the specified
2747      * ranges, are <i>equal</i> to one another.
2748      *
2749      * <p>Two arrays are considered equal if the number of elements covered by
2750      * each range is the same, and all corresponding pairs of elements over the
2751      * specified ranges in the two arrays are equal.  In other words, two arrays
2752      * are equal if they contain, over the specified ranges, the same elements
2753      * in the same order.
2754      *
2755      * @param a the first array to be tested for equality
2756      * @param aFromIndex the index (inclusive) of the first element in the
2757      *                   first array to be tested
2758      * @param aToIndex the index (exclusive) of the last element in the
2759      *                 first array to be tested
2760      * @param b the second array to be tested fro equality
2761      * @param bFromIndex the index (inclusive) of the first element in the
2762      *                   second array to be tested
2763      * @param bToIndex the index (exclusive) of the last element in the
2764      *                 second array to be tested
2765      * @return {@code true} if the two arrays, over the specified ranges, are
2766      *         equal
2767      * @throws IllegalArgumentException
2768      *         if {@code aFromIndex > aToIndex} or
2769      *         if {@code bFromIndex > bToIndex}
2770      * @throws ArrayIndexOutOfBoundsException
2771      *         if {@code aFromIndex < 0 or aToIndex > a.length} or
2772      *         if {@code bFromIndex < 0 or bToIndex > b.length}
2773      * @throws NullPointerException
2774      *         if either array is {@code null}
2775      * @since 9
2776      */
2777     public static boolean equals(short[] a, int aFromIndex, int aToIndex,
2778                                  short[] b, int bFromIndex, int bToIndex) {
2779         rangeCheck(a.length, aFromIndex, aToIndex);
2780         rangeCheck(b.length, bFromIndex, bToIndex);
2781 
2782         int aLength = aToIndex - aFromIndex;
2783         int bLength = bToIndex - bFromIndex;
2784         if (aLength != bLength)
2785             return false;
2786 
2787         for (int i = 0; i < aLength; i++)
2788             if (a[aFromIndex++] != b[bFromIndex++])
2789                 return false;
2790 
2791         return true;
2792     }
2793 
2794     /**
2795      * Returns {@code true} if the two specified arrays of chars are
2796      * <i>equal</i> to one another.  Two arrays are considered equal if both
2797      * arrays contain the same number of elements, and all corresponding pairs
2798      * of elements in the two arrays are equal.  In other words, two arrays
2799      * are equal if they contain the same elements in the same order.  Also,
2800      * two array references are considered equal if both are {@code null}.
2801      *
2802      * @param a one array to be tested for equality
2803      * @param a2 the other array to be tested for equality
2804      * @return {@code true} if the two arrays are equal
2805      */
2806     @HotSpotIntrinsicCandidate
2807     public static boolean equals(char[] a, char[] a2) {
2808         if (a==a2)
2809             return true;
2810         if (a==null || a2==null)
2811             return false;
2812 
2813         int length = a.length;
2814         if (a2.length != length)
2815             return false;
2816 
2817         for (int i=0; i<length; i++)
2818             if (a[i] != a2[i])
2819                 return false;
2820 
2821         return true;
2822     }
2823 
2824     /**
2825      * Returns true if the two specified arrays of chars, over the specified
2826      * ranges, are <i>equal</i> to one another.
2827      *
2828      * <p>Two arrays are considered equal if the number of elements covered by
2829      * each range is the same, and all corresponding pairs of elements over the
2830      * specified ranges in the two arrays are equal.  In other words, two arrays
2831      * are equal if they contain, over the specified ranges, the same elements
2832      * in the same order.
2833      *
2834      * @param a the first array to be tested for equality
2835      * @param aFromIndex the index (inclusive) of the first element in the
2836      *                   first array to be tested
2837      * @param aToIndex the index (exclusive) of the last element in the
2838      *                 first array to be tested
2839      * @param b the second array to be tested fro equality
2840      * @param bFromIndex the index (inclusive) of the first element in the
2841      *                   second array to be tested
2842      * @param bToIndex the index (exclusive) of the last element in the
2843      *                 second array to be tested
2844      * @return {@code true} if the two arrays, over the specified ranges, are
2845      *         equal
2846      * @throws IllegalArgumentException
2847      *         if {@code aFromIndex > aToIndex} or
2848      *         if {@code bFromIndex > bToIndex}
2849      * @throws ArrayIndexOutOfBoundsException
2850      *         if {@code aFromIndex < 0 or aToIndex > a.length} or
2851      *         if {@code bFromIndex < 0 or bToIndex > b.length}
2852      * @throws NullPointerException
2853      *         if either array is {@code null}
2854      * @since 9
2855      */
2856     public static boolean equals(char[] a, int aFromIndex, int aToIndex,
2857                                  char[] b, int bFromIndex, int bToIndex) {
2858         rangeCheck(a.length, aFromIndex, aToIndex);
2859         rangeCheck(b.length, bFromIndex, bToIndex);
2860 
2861         int aLength = aToIndex - aFromIndex;
2862         int bLength = bToIndex - bFromIndex;
2863         if (aLength != bLength)
2864             return false;
2865 
2866         for (int i = 0; i < aLength; i++)
2867             if (a[aFromIndex++] != b[bFromIndex++])
2868                 return false;
2869 
2870         return true;
2871     }
2872 
2873     /**
2874      * Returns {@code true} if the two specified arrays of bytes are
2875      * <i>equal</i> to one another.  Two arrays are considered equal if both
2876      * arrays contain the same number of elements, and all corresponding pairs
2877      * of elements in the two arrays are equal.  In other words, two arrays
2878      * are equal if they contain the same elements in the same order.  Also,
2879      * two array references are considered equal if both are {@code null}.
2880      *
2881      * @param a one array to be tested for equality
2882      * @param a2 the other array to be tested for equality
2883      * @return {@code true} if the two arrays are equal
2884      */
2885     public static boolean equals(byte[] a, byte[] a2) {
2886         if (a==a2)
2887             return true;
2888         if (a==null || a2==null)
2889             return false;
2890 
2891         int length = a.length;
2892         if (a2.length != length)
2893             return false;
2894 
2895         for (int i=0; i<length; i++)
2896             if (a[i] != a2[i])
2897                 return false;
2898 
2899         return true;
2900     }
2901 
2902     /**
2903      * Returns true if the two specified arrays of bytes, over the specified
2904      * ranges, are <i>equal</i> to one another.
2905      *
2906      * <p>Two arrays are considered equal if the number of elements covered by
2907      * each range is the same, and all corresponding pairs of elements over the
2908      * specified ranges in the two arrays are equal.  In other words, two arrays
2909      * are equal if they contain, over the specified ranges, the same elements
2910      * in the same order.
2911      *
2912      * @param a the first array to be tested for equality
2913      * @param aFromIndex the index (inclusive) of the first element in the
2914      *                   first array to be tested
2915      * @param aToIndex the index (exclusive) of the last element in the
2916      *                 first array to be tested
2917      * @param b the second array to be tested fro equality
2918      * @param bFromIndex the index (inclusive) of the first element in the
2919      *                   second array to be tested
2920      * @param bToIndex the index (exclusive) of the last element in the
2921      *                 second array to be tested
2922      * @return {@code true} if the two arrays, over the specified ranges, are
2923      *         equal
2924      * @throws IllegalArgumentException
2925      *         if {@code aFromIndex > aToIndex} or
2926      *         if {@code bFromIndex > bToIndex}
2927      * @throws ArrayIndexOutOfBoundsException
2928      *         if {@code aFromIndex < 0 or aToIndex > a.length} or
2929      *         if {@code bFromIndex < 0 or bToIndex > b.length}
2930      * @throws NullPointerException
2931      *         if either array is {@code null}
2932      * @since 9
2933      */
2934     public static boolean equals(byte[] a, int aFromIndex, int aToIndex,
2935                                  byte[] b, int bFromIndex, int bToIndex) {
2936         rangeCheck(a.length, aFromIndex, aToIndex);
2937         rangeCheck(b.length, bFromIndex, bToIndex);
2938 
2939         int aLength = aToIndex - aFromIndex;
2940         int bLength = bToIndex - bFromIndex;
2941         if (aLength != bLength)
2942             return false;
2943 
2944         for (int i = 0; i < aLength; i++)
2945             if (a[aFromIndex++] != b[bFromIndex++])
2946                 return false;
2947 
2948         return true;
2949     }
2950 
2951     /**
2952      * Returns {@code true} if the two specified arrays of booleans are
2953      * <i>equal</i> to one another.  Two arrays are considered equal if both
2954      * arrays contain the same number of elements, and all corresponding pairs
2955      * of elements in the two arrays are equal.  In other words, two arrays
2956      * are equal if they contain the same elements in the same order.  Also,
2957      * two array references are considered equal if both are {@code null}.
2958      *
2959      * @param a one array to be tested for equality
2960      * @param a2 the other array to be tested for equality
2961      * @return {@code true} if the two arrays are equal
2962      */
2963     public static boolean equals(boolean[] a, boolean[] a2) {
2964         if (a==a2)
2965             return true;
2966         if (a==null || a2==null)
2967             return false;
2968 
2969         int length = a.length;
2970         if (a2.length != length)
2971             return false;
2972 
2973         for (int i=0; i<length; i++)
2974             if (a[i] != a2[i])
2975                 return false;
2976 
2977         return true;
2978     }
2979 
2980     /**
2981      * Returns true if the two specified arrays of booleans, over the specified
2982      * ranges, are <i>equal</i> to one another.
2983      *
2984      * <p>Two arrays are considered equal if the number of elements covered by
2985      * each range is the same, and all corresponding pairs of elements over the
2986      * specified ranges in the two arrays are equal.  In other words, two arrays
2987      * are equal if they contain, over the specified ranges, the same elements
2988      * in the same order.
2989      *
2990      * @param a the first array to be tested for equality
2991      * @param aFromIndex the index (inclusive) of the first element in the
2992      *                   first array to be tested
2993      * @param aToIndex the index (exclusive) of the last element in the
2994      *                 first array to be tested
2995      * @param b the second array to be tested fro equality
2996      * @param bFromIndex the index (inclusive) of the first element in the
2997      *                   second array to be tested
2998      * @param bToIndex the index (exclusive) of the last element in the
2999      *                 second array to be tested
3000      * @return {@code true} if the two arrays, over the specified ranges, are
3001      *         equal
3002      * @throws IllegalArgumentException
3003      *         if {@code aFromIndex > aToIndex} or
3004      *         if {@code bFromIndex > bToIndex}
3005      * @throws ArrayIndexOutOfBoundsException
3006      *         if {@code aFromIndex < 0 or aToIndex > a.length} or
3007      *         if {@code bFromIndex < 0 or bToIndex > b.length}
3008      * @throws NullPointerException
3009      *         if either array is {@code null}
3010      * @since 9
3011      */
3012     public static boolean equals(boolean[] a, int aFromIndex, int aToIndex,
3013                                  boolean[] b, int bFromIndex, int bToIndex) {
3014         rangeCheck(a.length, aFromIndex, aToIndex);
3015         rangeCheck(b.length, bFromIndex, bToIndex);
3016 
3017         int aLength = aToIndex - aFromIndex;
3018         int bLength = bToIndex - bFromIndex;
3019         if (aLength != bLength)
3020             return false;
3021 
3022         for (int i = 0; i < aLength; i++)
3023             if (a[aFromIndex++] != b[bFromIndex++])
3024                 return false;
3025 
3026         return true;
3027     }
3028 
3029     /**
3030      * Returns {@code true} if the two specified arrays of doubles are
3031      * <i>equal</i> to one another.  Two arrays are considered equal if both
3032      * arrays contain the same number of elements, and all corresponding pairs
3033      * of elements in the two arrays are equal.  In other words, two arrays
3034      * are equal if they contain the same elements in the same order.  Also,
3035      * two array references are considered equal if both are {@code null}.
3036      *
3037      * Two doubles {@code d1} and {@code d2} are considered equal if:
3038      * <pre>    {@code new Double(d1).equals(new Double(d2))}</pre>
3039      * (Unlike the {@code ==} operator, this method considers
3040      * {@code NaN} equals to itself, and 0.0d unequal to -0.0d.)
3041      *
3042      * @param a one array to be tested for equality
3043      * @param a2 the other array to be tested for equality
3044      * @return {@code true} if the two arrays are equal
3045      * @see Double#equals(Object)
3046      */
3047     public static boolean equals(double[] a, double[] a2) {
3048         if (a==a2)
3049             return true;
3050         if (a==null || a2==null)
3051             return false;
3052 
3053         int length = a.length;
3054         if (a2.length != length)
3055             return false;
3056 
3057         for (int i=0; i<length; i++) {
3058             double v1 = a[i], v2 = a2[i];
3059             if (Double.doubleToRawLongBits(v1) != Double.doubleToRawLongBits(v2))
3060                 if (!Double.isNaN(v1) || !Double.isNaN(v2))
3061                     return false;
3062         }
3063 
3064         return true;
3065     }
3066 
3067     /**
3068      * Returns true if the two specified arrays of doubles, over the specified
3069      * ranges, are <i>equal</i> to one another.
3070      *
3071      * <p>Two arrays are considered equal if the number of elements covered by
3072      * each range is the same, and all corresponding pairs of elements over the
3073      * specified ranges in the two arrays are equal.  In other words, two arrays
3074      * are equal if they contain, over the specified ranges, the same elements
3075      * in the same order.
3076      *
3077      * <p>Two doubles {@code d1} and {@code d2} are considered equal if:
3078      * <pre>    {@code new Double(d1).equals(new Double(d2))}</pre>
3079      * (Unlike the {@code ==} operator, this method considers
3080      * {@code NaN} equals to itself, and 0.0d unequal to -0.0d.)
3081      *
3082      * @param a the first array to be tested for equality
3083      * @param aFromIndex the index (inclusive) of the first element in the
3084      *                   first array to be tested
3085      * @param aToIndex the index (exclusive) of the last element in the
3086      *                 first array to be tested
3087      * @param b the second array to be tested fro equality
3088      * @param bFromIndex the index (inclusive) of the first element in the
3089      *                   second array to be tested
3090      * @param bToIndex the index (exclusive) of the last element in the
3091      *                 second array to be tested
3092      * @return {@code true} if the two arrays, over the specified ranges, are
3093      *         equal
3094      * @throws IllegalArgumentException
3095      *         if {@code aFromIndex > aToIndex} or
3096      *         if {@code bFromIndex > bToIndex}
3097      * @throws ArrayIndexOutOfBoundsException
3098      *         if {@code aFromIndex < 0 or aToIndex > a.length} or
3099      *         if {@code bFromIndex < 0 or bToIndex > b.length}
3100      * @throws NullPointerException
3101      *         if either array is {@code null}
3102      * @see Double#equals(Object)
3103      * @since 9
3104      */
3105     public static boolean equals(double[] a, int aFromIndex, int aToIndex,
3106                                  double[] b, int bFromIndex, int bToIndex) {
3107         rangeCheck(a.length, aFromIndex, aToIndex);
3108         rangeCheck(b.length, bFromIndex, bToIndex);
3109 
3110         int aLength = aToIndex - aFromIndex;
3111         int bLength = bToIndex - bFromIndex;
3112         if (aLength != bLength)
3113             return false;
3114 
3115         for (int i = 0; i < aLength; i++) {
3116             Double va = a[aFromIndex++], vb = b[bFromIndex++];
3117             if (Double.doubleToRawLongBits(va) != Double.doubleToRawLongBits(vb))
3118                 if (!Double.isNaN(va) || !Double.isNaN(vb))
3119                     return false;
3120         }
3121 
3122         return true;
3123     }
3124 
3125     /**
3126      * Returns {@code true} if the two specified arrays of floats are
3127      * <i>equal</i> to one another.  Two arrays are considered equal if both
3128      * arrays contain the same number of elements, and all corresponding pairs
3129      * of elements in the two arrays are equal.  In other words, two arrays
3130      * are equal if they contain the same elements in the same order.  Also,
3131      * two array references are considered equal if both are {@code null}.
3132      *
3133      * Two floats {@code f1} and {@code f2} are considered equal if:
3134      * <pre>    {@code new Float(f1).equals(new Float(f2))}</pre>
3135      * (Unlike the {@code ==} operator, this method considers
3136      * {@code NaN} equals to itself, and 0.0f unequal to -0.0f.)
3137      *
3138      * @param a one array to be tested for equality
3139      * @param a2 the other array to be tested for equality
3140      * @return {@code true} if the two arrays are equal
3141      * @see Float#equals(Object)
3142      */
3143     public static boolean equals(float[] a, float[] a2) {
3144         if (a==a2)
3145             return true;
3146         if (a==null || a2==null)
3147             return false;
3148 
3149         int length = a.length;
3150         if (a2.length != length)
3151             return false;
3152 
3153         for (int i=0; i<length; i++) {
3154             float v1 = a[i], v2 = a2[i];
3155             if (Float.floatToRawIntBits(v1) != Float.floatToRawIntBits(v2))
3156                 if (!Float.isNaN(v1) || !Float.isNaN(v2))
3157                     return false;
3158         }
3159 
3160         return true;
3161     }
3162 
3163     /**
3164      * Returns true if the two specified arrays of floats, over the specified
3165      * ranges, are <i>equal</i> to one another.
3166      *
3167      * <p>Two arrays are considered equal if the number of elements covered by
3168      * each range is the same, and all corresponding pairs of elements over the
3169      * specified ranges in the two arrays are equal.  In other words, two arrays
3170      * are equal if they contain, over the specified ranges, the same elements
3171      * in the same order.
3172      *
3173      * <p>Two floats {@code f1} and {@code f2} are considered equal if:
3174      * <pre>    {@code new Float(f1).equals(new Float(f2))}</pre>
3175      * (Unlike the {@code ==} operator, this method considers
3176      * {@code NaN} equals to itself, and 0.0f unequal to -0.0f.)
3177      *
3178      * @param a the first array to be tested for equality
3179      * @param aFromIndex the index (inclusive) of the first element in the
3180      *                   first array to be tested
3181      * @param aToIndex the index (exclusive) of the last element in the
3182      *                 first array to be tested
3183      * @param b the second array to be tested fro equality
3184      * @param bFromIndex the index (inclusive) of the first element in the
3185      *                   second array to be tested
3186      * @param bToIndex the index (exclusive) of the last element in the
3187      *                 second array to be tested
3188      * @return {@code true} if the two arrays, over the specified ranges, are
3189      *         equal
3190      * @throws IllegalArgumentException
3191      *         if {@code aFromIndex > aToIndex} or
3192      *         if {@code bFromIndex > bToIndex}
3193      * @throws ArrayIndexOutOfBoundsException
3194      *         if {@code aFromIndex < 0 or aToIndex > a.length} or
3195      *         if {@code bFromIndex < 0 or bToIndex > b.length}
3196      * @throws NullPointerException
3197      *         if either array is {@code null}
3198      * @see Float#equals(Object)
3199      * @since 9
3200      */
3201     public static boolean equals(float[] a, int aFromIndex, int aToIndex,
3202                                  float[] b, int bFromIndex, int bToIndex) {
3203         rangeCheck(a.length, aFromIndex, aToIndex);
3204         rangeCheck(b.length, bFromIndex, bToIndex);
3205 
3206         int aLength = aToIndex - aFromIndex;
3207         int bLength = bToIndex - bFromIndex;
3208         if (aLength != bLength)
3209             return false;
3210 
3211         for (int i = 0; i < aLength; i++) {
3212             float va = a[aFromIndex++], vb = b[bFromIndex++];
3213             if (Float.floatToRawIntBits(va) != Float.floatToRawIntBits(vb))
3214                 if (!Float.isNaN(va) || !Float.isNaN(vb))
3215                     return false;
3216         }
3217 
3218         return true;
3219     }
3220 
3221     /**
3222      * Returns {@code true} if the two specified arrays of Objects are
3223      * <i>equal</i> to one another.  The two arrays are considered equal if
3224      * both arrays contain the same number of elements, and all corresponding
3225      * pairs of elements in the two arrays are equal.  Two objects {@code e1}
3226      * and {@code e2} are considered <i>equal</i> if
3227      * {@code Objects.equals(e1, e2)}.
3228      * In other words, the two arrays are equal if
3229      * they contain the same elements in the same order.  Also, two array
3230      * references are considered equal if both are {@code null}.
3231      *
3232      * @param a one array to be tested for equality
3233      * @param a2 the other array to be tested for equality
3234      * @return {@code true} if the two arrays are equal
3235      */
3236     public static boolean equals(Object[] a, Object[] a2) {
3237         if (a==a2)
3238             return true;
3239         if (a==null || a2==null)
3240             return false;
3241 
3242         int length = a.length;
3243         if (a2.length != length)
3244             return false;
3245 
3246         for (int i=0; i<length; i++) {
3247             if (!Objects.equals(a[i], a2[i]))
3248                 return false;
3249         }
3250 
3251         return true;
3252     }
3253 
3254     /**
3255      * Returns true if the two specified arrays of Objects, over the specified
3256      * ranges, are <i>equal</i> to one another.
3257      *
3258      * <p>Two arrays are considered equal if the number of elements covered by
3259      * each range is the same, and all corresponding pairs of elements over the
3260      * specified ranges in the two arrays are equal.  In other words, two arrays
3261      * are equal if they contain, over the specified ranges, the same elements
3262      * in the same order.
3263      *
3264      * <p>Two objects {@code e1} and {@code e2} are considered <i>equal</i> if
3265      * {@code Objects.equals(e1, e2)}.
3266      *
3267      * @param a the first array to be tested for equality
3268      * @param aFromIndex the index (inclusive) of the first element in the
3269      *                   first array to be tested
3270      * @param aToIndex the index (exclusive) of the last element in the
3271      *                 first array to be tested
3272      * @param b the second array to be tested fro equality
3273      * @param bFromIndex the index (inclusive) of the first element in the
3274      *                   second array to be tested
3275      * @param bToIndex the index (exclusive) of the last element in the
3276      *                 second array to be tested
3277      * @return {@code true} if the two arrays, over the specified ranges, are
3278      *         equal
3279      * @throws IllegalArgumentException
3280      *         if {@code aFromIndex > aToIndex} or
3281      *         if {@code bFromIndex > bToIndex}
3282      * @throws ArrayIndexOutOfBoundsException
3283      *         if {@code aFromIndex < 0 or aToIndex > a.length} or
3284      *         if {@code bFromIndex < 0 or bToIndex > b.length}
3285      * @throws NullPointerException
3286      *         if either array is {@code null}
3287      * @since 9
3288      */
3289     public static boolean equals(Object[] a, int aFromIndex, int aToIndex,
3290                                  Object[] b, int bFromIndex, int bToIndex) {
3291         rangeCheck(a.length, aFromIndex, aToIndex);
3292         rangeCheck(b.length, bFromIndex, bToIndex);
3293 
3294         int aLength = aToIndex - aFromIndex;
3295         int bLength = bToIndex - bFromIndex;
3296         if (aLength != bLength)
3297             return false;
3298 
3299         for (int i = 0; i < aLength; i++) {
3300             if (!Objects.equals(a[aFromIndex++], b[bFromIndex++]))
3301                 return false;
3302         }
3303 
3304         return true;
3305     }
3306 
3307     // Filling
3308 
3309     /**
3310      * Assigns the specified long value to each element of the specified array
3311      * of longs.
3312      *
3313      * @param a the array to be filled
3314      * @param val the value to be stored in all elements of the array
3315      */
3316     public static void fill(long[] a, long val) {
3317         for (int i = 0, len = a.length; i < len; i++)
3318             a[i] = val;
3319     }
3320 
3321     /**
3322      * Assigns the specified long value to each element of the specified
3323      * range of the specified array of longs.  The range to be filled
3324      * extends from index {@code fromIndex}, inclusive, to index
3325      * {@code toIndex}, exclusive.  (If {@code fromIndex==toIndex}, the
3326      * range to be filled is empty.)
3327      *
3328      * @param a the array to be filled
3329      * @param fromIndex the index of the first element (inclusive) to be
3330      *        filled with the specified value
3331      * @param toIndex the index of the last element (exclusive) to be
3332      *        filled with the specified value
3333      * @param val the value to be stored in all elements of the array
3334      * @throws IllegalArgumentException if {@code fromIndex > toIndex}
3335      * @throws ArrayIndexOutOfBoundsException if {@code fromIndex < 0} or
3336      *         {@code toIndex > a.length}
3337      */
3338     public static void fill(long[] a, int fromIndex, int toIndex, long val) {
3339         rangeCheck(a.length, fromIndex, toIndex);
3340         for (int i = fromIndex; i < toIndex; i++)
3341             a[i] = val;
3342     }
3343 
3344     /**
3345      * Assigns the specified int value to each element of the specified array
3346      * of ints.
3347      *
3348      * @param a the array to be filled
3349      * @param val the value to be stored in all elements of the array
3350      */
3351     public static void fill(int[] a, int val) {
3352         for (int i = 0, len = a.length; i < len; i++)
3353             a[i] = val;
3354     }
3355 
3356     /**
3357      * Assigns the specified int value to each element of the specified
3358      * range of the specified array of ints.  The range to be filled
3359      * extends from index {@code fromIndex}, inclusive, to index
3360      * {@code toIndex}, exclusive.  (If {@code fromIndex==toIndex}, the
3361      * range to be filled is empty.)
3362      *
3363      * @param a the array to be filled
3364      * @param fromIndex the index of the first element (inclusive) to be
3365      *        filled with the specified value
3366      * @param toIndex the index of the last element (exclusive) to be
3367      *        filled with the specified value
3368      * @param val the value to be stored in all elements of the array
3369      * @throws IllegalArgumentException if {@code fromIndex > toIndex}
3370      * @throws ArrayIndexOutOfBoundsException if {@code fromIndex < 0} or
3371      *         {@code toIndex > a.length}
3372      */
3373     public static void fill(int[] a, int fromIndex, int toIndex, int val) {
3374         rangeCheck(a.length, fromIndex, toIndex);
3375         for (int i = fromIndex; i < toIndex; i++)
3376             a[i] = val;
3377     }
3378 
3379     /**
3380      * Assigns the specified short value to each element of the specified array
3381      * of shorts.
3382      *
3383      * @param a the array to be filled
3384      * @param val the value to be stored in all elements of the array
3385      */
3386     public static void fill(short[] a, short val) {
3387         for (int i = 0, len = a.length; i < len; i++)
3388             a[i] = val;
3389     }
3390 
3391     /**
3392      * Assigns the specified short value to each element of the specified
3393      * range of the specified array of shorts.  The range to be filled
3394      * extends from index {@code fromIndex}, inclusive, to index
3395      * {@code toIndex}, exclusive.  (If {@code fromIndex==toIndex}, the
3396      * range to be filled is empty.)
3397      *
3398      * @param a the array to be filled
3399      * @param fromIndex the index of the first element (inclusive) to be
3400      *        filled with the specified value
3401      * @param toIndex the index of the last element (exclusive) to be
3402      *        filled with the specified value
3403      * @param val the value to be stored in all elements of the array
3404      * @throws IllegalArgumentException if {@code fromIndex > toIndex}
3405      * @throws ArrayIndexOutOfBoundsException if {@code fromIndex < 0} or
3406      *         {@code toIndex > a.length}
3407      */
3408     public static void fill(short[] a, int fromIndex, int toIndex, short val) {
3409         rangeCheck(a.length, fromIndex, toIndex);
3410         for (int i = fromIndex; i < toIndex; i++)
3411             a[i] = val;
3412     }
3413 
3414     /**
3415      * Assigns the specified char value to each element of the specified array
3416      * of chars.
3417      *
3418      * @param a the array to be filled
3419      * @param val the value to be stored in all elements of the array
3420      */
3421     public static void fill(char[] a, char val) {
3422         for (int i = 0, len = a.length; i < len; i++)
3423             a[i] = val;
3424     }
3425 
3426     /**
3427      * Assigns the specified char value to each element of the specified
3428      * range of the specified array of chars.  The range to be filled
3429      * extends from index {@code fromIndex}, inclusive, to index
3430      * {@code toIndex}, exclusive.  (If {@code fromIndex==toIndex}, the
3431      * range to be filled is empty.)
3432      *
3433      * @param a the array to be filled
3434      * @param fromIndex the index of the first element (inclusive) to be
3435      *        filled with the specified value
3436      * @param toIndex the index of the last element (exclusive) to be
3437      *        filled with the specified value
3438      * @param val the value to be stored in all elements of the array
3439      * @throws IllegalArgumentException if {@code fromIndex > toIndex}
3440      * @throws ArrayIndexOutOfBoundsException if {@code fromIndex < 0} or
3441      *         {@code toIndex > a.length}
3442      */
3443     public static void fill(char[] a, int fromIndex, int toIndex, char val) {
3444         rangeCheck(a.length, fromIndex, toIndex);
3445         for (int i = fromIndex; i < toIndex; i++)
3446             a[i] = val;
3447     }
3448 
3449     /**
3450      * Assigns the specified byte value to each element of the specified array
3451      * of bytes.
3452      *
3453      * @param a the array to be filled
3454      * @param val the value to be stored in all elements of the array
3455      */
3456     public static void fill(byte[] a, byte val) {
3457         for (int i = 0, len = a.length; i < len; i++)
3458             a[i] = val;
3459     }
3460 
3461     /**
3462      * Assigns the specified byte value to each element of the specified
3463      * range of the specified array of bytes.  The range to be filled
3464      * extends from index {@code fromIndex}, inclusive, to index
3465      * {@code toIndex}, exclusive.  (If {@code fromIndex==toIndex}, the
3466      * range to be filled is empty.)
3467      *
3468      * @param a the array to be filled
3469      * @param fromIndex the index of the first element (inclusive) to be
3470      *        filled with the specified value
3471      * @param toIndex the index of the last element (exclusive) to be
3472      *        filled with the specified value
3473      * @param val the value to be stored in all elements of the array
3474      * @throws IllegalArgumentException if {@code fromIndex > toIndex}
3475      * @throws ArrayIndexOutOfBoundsException if {@code fromIndex < 0} or
3476      *         {@code toIndex > a.length}
3477      */
3478     public static void fill(byte[] a, int fromIndex, int toIndex, byte val) {
3479         rangeCheck(a.length, fromIndex, toIndex);
3480         for (int i = fromIndex; i < toIndex; i++)
3481             a[i] = val;
3482     }
3483 
3484     /**
3485      * Assigns the specified boolean value to each element of the specified
3486      * array of booleans.
3487      *
3488      * @param a the array to be filled
3489      * @param val the value to be stored in all elements of the array
3490      */
3491     public static void fill(boolean[] a, boolean val) {
3492         for (int i = 0, len = a.length; i < len; i++)
3493             a[i] = val;
3494     }
3495 
3496     /**
3497      * Assigns the specified boolean value to each element of the specified
3498      * range of the specified array of booleans.  The range to be filled
3499      * extends from index {@code fromIndex}, inclusive, to index
3500      * {@code toIndex}, exclusive.  (If {@code fromIndex==toIndex}, the
3501      * range to be filled is empty.)
3502      *
3503      * @param a the array to be filled
3504      * @param fromIndex the index of the first element (inclusive) to be
3505      *        filled with the specified value
3506      * @param toIndex the index of the last element (exclusive) to be
3507      *        filled with the specified value
3508      * @param val the value to be stored in all elements of the array
3509      * @throws IllegalArgumentException if {@code fromIndex > toIndex}
3510      * @throws ArrayIndexOutOfBoundsException if {@code fromIndex < 0} or
3511      *         {@code toIndex > a.length}
3512      */
3513     public static void fill(boolean[] a, int fromIndex, int toIndex,
3514                             boolean 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 double value to each element of the specified
3522      * array of doubles.
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(double[] a, double val) {
3528         for (int i = 0, len = a.length; i < len; i++)
3529             a[i] = val;
3530     }
3531 
3532     /**
3533      * Assigns the specified double value to each element of the specified
3534      * range of the specified array of doubles.  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(double[] a, int fromIndex, int toIndex,double val){
3550         rangeCheck(a.length, fromIndex, toIndex);
3551         for (int i = fromIndex; i < toIndex; i++)
3552             a[i] = val;
3553     }
3554 
3555     /**
3556      * Assigns the specified float value to each element of the specified array
3557      * of floats.
3558      *
3559      * @param a the array to be filled
3560      * @param val the value to be stored in all elements of the array
3561      */
3562     public static void fill(float[] a, float val) {
3563         for (int i = 0, len = a.length; i < len; i++)
3564             a[i] = val;
3565     }
3566 
3567     /**
3568      * Assigns the specified float value to each element of the specified
3569      * range of the specified array of floats.  The range to be filled
3570      * extends from index {@code fromIndex}, inclusive, to index
3571      * {@code toIndex}, exclusive.  (If {@code fromIndex==toIndex}, the
3572      * range to be filled is empty.)
3573      *
3574      * @param a the array to be filled
3575      * @param fromIndex the index of the first element (inclusive) to be
3576      *        filled with the specified value
3577      * @param toIndex the index of the last element (exclusive) to be
3578      *        filled with the specified value
3579      * @param val the value to be stored in all elements of the array
3580      * @throws IllegalArgumentException if {@code fromIndex > toIndex}
3581      * @throws ArrayIndexOutOfBoundsException if {@code fromIndex < 0} or
3582      *         {@code toIndex > a.length}
3583      */
3584     public static void fill(float[] a, int fromIndex, int toIndex, float val) {
3585         rangeCheck(a.length, fromIndex, toIndex);
3586         for (int i = fromIndex; i < toIndex; i++)
3587             a[i] = val;
3588     }
3589 
3590     /**
3591      * Assigns the specified Object reference to each element of the specified
3592      * array of Objects.
3593      *
3594      * @param a the array to be filled
3595      * @param val the value to be stored in all elements of the array
3596      * @throws ArrayStoreException if the specified value is not of a
3597      *         runtime type that can be stored in the specified array
3598      */
3599     public static void fill(Object[] a, Object val) {
3600         for (int i = 0, len = a.length; i < len; i++)
3601             a[i] = val;
3602     }
3603 
3604     /**
3605      * Assigns the specified Object reference to each element of the specified
3606      * range of the specified array of Objects.  The range to be filled
3607      * extends from index {@code fromIndex}, inclusive, to index
3608      * {@code toIndex}, exclusive.  (If {@code fromIndex==toIndex}, the
3609      * range to be filled is empty.)
3610      *
3611      * @param a the array to be filled
3612      * @param fromIndex the index of the first element (inclusive) to be
3613      *        filled with the specified value
3614      * @param toIndex the index of the last element (exclusive) to be
3615      *        filled with the specified value
3616      * @param val the value to be stored in all elements of the array
3617      * @throws IllegalArgumentException if {@code fromIndex > toIndex}
3618      * @throws ArrayIndexOutOfBoundsException if {@code fromIndex < 0} or
3619      *         {@code toIndex > a.length}
3620      * @throws ArrayStoreException if the specified value is not of a
3621      *         runtime type that can be stored in the specified array
3622      */
3623     public static void fill(Object[] a, int fromIndex, int toIndex, Object val) {
3624         rangeCheck(a.length, fromIndex, toIndex);
3625         for (int i = fromIndex; i < toIndex; i++)
3626             a[i] = val;
3627     }
3628 
3629     // Cloning
3630 
3631     /**
3632      * Copies the specified array, truncating or padding with nulls (if necessary)
3633      * so the copy has the specified length.  For all indices that are
3634      * valid in both the original array and the copy, the two arrays will
3635      * contain identical values.  For any indices that are valid in the
3636      * copy but not the original, the copy will contain {@code null}.
3637      * Such indices will exist if and only if the specified length
3638      * is greater than that of the original array.
3639      * The resulting array is of exactly the same class as the original array.
3640      *
3641      * @param <T> the class of the objects in the array
3642      * @param original the array to be copied
3643      * @param newLength the length of the copy to be returned
3644      * @return a copy of the original array, truncated or padded with nulls
3645      *     to obtain the specified length
3646      * @throws NegativeArraySizeException if {@code newLength} is negative
3647      * @throws NullPointerException if {@code original} is null
3648      * @since 1.6
3649      */
3650     @SuppressWarnings("unchecked")
3651     public static <T> T[] copyOf(T[] original, int newLength) {
3652         return (T[]) copyOf(original, newLength, original.getClass());
3653     }
3654 
3655     /**
3656      * Copies the specified array, truncating or padding with nulls (if necessary)
3657      * so the copy has the specified length.  For all indices that are
3658      * valid in both the original array and the copy, the two arrays will
3659      * contain identical values.  For any indices that are valid in the
3660      * copy but not the original, the copy will contain {@code null}.
3661      * Such indices will exist if and only if the specified length
3662      * is greater than that of the original array.
3663      * The resulting array is of the class {@code newType}.
3664      *
3665      * @param <U> the class of the objects in the original array
3666      * @param <T> the class of the objects in the returned array
3667      * @param original the array to be copied
3668      * @param newLength the length of the copy to be returned
3669      * @param newType the class of the copy to be returned
3670      * @return a copy of the original array, truncated or padded with nulls
3671      *     to obtain the specified length
3672      * @throws NegativeArraySizeException if {@code newLength} is negative
3673      * @throws NullPointerException if {@code original} is null
3674      * @throws ArrayStoreException if an element copied from
3675      *     {@code original} is not of a runtime type that can be stored in
3676      *     an array of class {@code newType}
3677      * @since 1.6
3678      */
3679     @HotSpotIntrinsicCandidate
3680     public static <T,U> T[] copyOf(U[] original, int newLength, Class<? extends T[]> newType) {
3681         @SuppressWarnings("unchecked")
3682         T[] copy = ((Object)newType == (Object)Object[].class)
3683             ? (T[]) new Object[newLength]
3684             : (T[]) Array.newInstance(newType.getComponentType(), newLength);
3685         System.arraycopy(original, 0, copy, 0,
3686                          Math.min(original.length, newLength));
3687         return copy;
3688     }
3689 
3690     /**
3691      * Copies the specified array, truncating or padding with zeros (if necessary)
3692      * so the copy has the specified length.  For all indices that are
3693      * valid in both the original array and the copy, the two arrays will
3694      * contain identical values.  For any indices that are valid in the
3695      * copy but not the original, the copy will contain {@code (byte)0}.
3696      * Such indices will exist if and only if the specified length
3697      * is greater than that of the original array.
3698      *
3699      * @param original the array to be copied
3700      * @param newLength the length of the copy to be returned
3701      * @return a copy of the original array, truncated or padded with zeros
3702      *     to obtain the specified length
3703      * @throws NegativeArraySizeException if {@code newLength} is negative
3704      * @throws NullPointerException if {@code original} is null
3705      * @since 1.6
3706      */
3707     public static byte[] copyOf(byte[] original, int newLength) {
3708         byte[] copy = new byte[newLength];
3709         System.arraycopy(original, 0, copy, 0,
3710                          Math.min(original.length, newLength));
3711         return copy;
3712     }
3713 
3714     /**
3715      * Copies the specified array, truncating or padding with zeros (if necessary)
3716      * so the copy has the specified length.  For all indices that are
3717      * valid in both the original array and the copy, the two arrays will
3718      * contain identical values.  For any indices that are valid in the
3719      * copy but not the original, the copy will contain {@code (short)0}.
3720      * Such indices will exist if and only if the specified length
3721      * is greater than that of the original array.
3722      *
3723      * @param original the array to be copied
3724      * @param newLength the length of the copy to be returned
3725      * @return a copy of the original array, truncated or padded with zeros
3726      *     to obtain the specified length
3727      * @throws NegativeArraySizeException if {@code newLength} is negative
3728      * @throws NullPointerException if {@code original} is null
3729      * @since 1.6
3730      */
3731     public static short[] copyOf(short[] original, int newLength) {
3732         short[] copy = new short[newLength];
3733         System.arraycopy(original, 0, copy, 0,
3734                          Math.min(original.length, newLength));
3735         return copy;
3736     }
3737 
3738     /**
3739      * Copies the specified array, truncating or padding with zeros (if necessary)
3740      * so the copy has the specified length.  For all indices that are
3741      * valid in both the original array and the copy, the two arrays will
3742      * contain identical values.  For any indices that are valid in the
3743      * copy but not the original, the copy will contain {@code 0}.
3744      * Such indices will exist if and only if the specified length
3745      * is greater than that of the original array.
3746      *
3747      * @param original the array to be copied
3748      * @param newLength the length of the copy to be returned
3749      * @return a copy of the original array, truncated or padded with zeros
3750      *     to obtain the specified length
3751      * @throws NegativeArraySizeException if {@code newLength} is negative
3752      * @throws NullPointerException if {@code original} is null
3753      * @since 1.6
3754      */
3755     public static int[] copyOf(int[] original, int newLength) {
3756         int[] copy = new int[newLength];
3757         System.arraycopy(original, 0, copy, 0,
3758                          Math.min(original.length, newLength));
3759         return copy;
3760     }
3761 
3762     /**
3763      * Copies the specified array, truncating or padding with zeros (if necessary)
3764      * so the copy has the specified length.  For all indices that are
3765      * valid in both the original array and the copy, the two arrays will
3766      * contain identical values.  For any indices that are valid in the
3767      * copy but not the original, the copy will contain {@code 0L}.
3768      * Such indices will exist if and only if the specified length
3769      * is greater than that of the original array.
3770      *
3771      * @param original the array to be copied
3772      * @param newLength the length of the copy to be returned
3773      * @return a copy of the original array, truncated or padded with zeros
3774      *     to obtain the specified length
3775      * @throws NegativeArraySizeException if {@code newLength} is negative
3776      * @throws NullPointerException if {@code original} is null
3777      * @since 1.6
3778      */
3779     public static long[] copyOf(long[] original, int newLength) {
3780         long[] copy = new long[newLength];
3781         System.arraycopy(original, 0, copy, 0,
3782                          Math.min(original.length, newLength));
3783         return copy;
3784     }
3785 
3786     /**
3787      * Copies the specified array, truncating or padding with null characters (if necessary)
3788      * so the copy has the specified length.  For all indices that are valid
3789      * in both the original array and the copy, the two arrays will contain
3790      * identical values.  For any indices that are valid in the copy but not
3791      * the original, the copy will contain {@code '\\u000'}.  Such indices
3792      * will exist if and only if the specified length is greater than that of
3793      * the original array.
3794      *
3795      * @param original the array to be copied
3796      * @param newLength the length of the copy to be returned
3797      * @return a copy of the original array, truncated or padded with null characters
3798      *     to obtain the specified length
3799      * @throws NegativeArraySizeException if {@code newLength} is negative
3800      * @throws NullPointerException if {@code original} is null
3801      * @since 1.6
3802      */
3803     public static char[] copyOf(char[] original, int newLength) {
3804         char[] copy = new char[newLength];
3805         System.arraycopy(original, 0, copy, 0,
3806                          Math.min(original.length, newLength));
3807         return copy;
3808     }
3809 
3810     /**
3811      * Copies the specified array, truncating or padding with zeros (if necessary)
3812      * so the copy has the specified length.  For all indices that are
3813      * valid in both the original array and the copy, the two arrays will
3814      * contain identical values.  For any indices that are valid in the
3815      * copy but not the original, the copy will contain {@code 0f}.
3816      * Such indices will exist if and only if the specified length
3817      * is greater than that of the original array.
3818      *
3819      * @param original the array to be copied
3820      * @param newLength the length of the copy to be returned
3821      * @return a copy of the original array, truncated or padded with zeros
3822      *     to obtain the specified length
3823      * @throws NegativeArraySizeException if {@code newLength} is negative
3824      * @throws NullPointerException if {@code original} is null
3825      * @since 1.6
3826      */
3827     public static float[] copyOf(float[] original, int newLength) {
3828         float[] copy = new float[newLength];
3829         System.arraycopy(original, 0, copy, 0,
3830                          Math.min(original.length, newLength));
3831         return copy;
3832     }
3833 
3834     /**
3835      * Copies the specified array, truncating or padding with zeros (if necessary)
3836      * so the copy has the specified length.  For all indices that are
3837      * valid in both the original array and the copy, the two arrays will
3838      * contain identical values.  For any indices that are valid in the
3839      * copy but not the original, the copy will contain {@code 0d}.
3840      * Such indices will exist if and only if the specified length
3841      * is greater than that of the original array.
3842      *
3843      * @param original the array to be copied
3844      * @param newLength the length of the copy to be returned
3845      * @return a copy of the original array, truncated or padded with zeros
3846      *     to obtain the specified length
3847      * @throws NegativeArraySizeException if {@code newLength} is negative
3848      * @throws NullPointerException if {@code original} is null
3849      * @since 1.6
3850      */
3851     public static double[] copyOf(double[] original, int newLength) {
3852         double[] copy = new double[newLength];
3853         System.arraycopy(original, 0, copy, 0,
3854                          Math.min(original.length, newLength));
3855         return copy;
3856     }
3857 
3858     /**
3859      * Copies the specified array, truncating or padding with {@code false} (if necessary)
3860      * so the copy has the specified length.  For all indices that are
3861      * valid in both the original array and the copy, the two arrays will
3862      * contain identical values.  For any indices that are valid in the
3863      * copy but not the original, the copy will contain {@code false}.
3864      * Such indices will exist if and only if the specified length
3865      * is greater than that of the original array.
3866      *
3867      * @param original the array to be copied
3868      * @param newLength the length of the copy to be returned
3869      * @return a copy of the original array, truncated or padded with false elements
3870      *     to obtain the specified length
3871      * @throws NegativeArraySizeException if {@code newLength} is negative
3872      * @throws NullPointerException if {@code original} is null
3873      * @since 1.6
3874      */
3875     public static boolean[] copyOf(boolean[] original, int newLength) {
3876         boolean[] copy = new boolean[newLength];
3877         System.arraycopy(original, 0, copy, 0,
3878                          Math.min(original.length, newLength));
3879         return copy;
3880     }
3881 
3882     /**
3883      * Copies the specified range of the specified array into a new array.
3884      * The initial index of the range ({@code from}) must lie between zero
3885      * and {@code original.length}, inclusive.  The value at
3886      * {@code original[from]} is placed into the initial element of the copy
3887      * (unless {@code from == original.length} or {@code from == to}).
3888      * Values from subsequent elements in the original array are placed into
3889      * subsequent elements in the copy.  The final index of the range
3890      * ({@code to}), which must be greater than or equal to {@code from},
3891      * may be greater than {@code original.length}, in which case
3892      * {@code null} is placed in all elements of the copy whose index is
3893      * greater than or equal to {@code original.length - from}.  The length
3894      * of the returned array will be {@code to - from}.
3895      * <p>
3896      * The resulting array is of exactly the same class as the original array.
3897      *
3898      * @param <T> the class of the objects in the array
3899      * @param original the array from which a range is to be copied
3900      * @param from the initial index of the range to be copied, inclusive
3901      * @param to the final index of the range to be copied, exclusive.
3902      *     (This index may lie outside the array.)
3903      * @return a new array containing the specified range from the original array,
3904      *     truncated or padded with nulls to obtain the required length
3905      * @throws ArrayIndexOutOfBoundsException if {@code from < 0}
3906      *     or {@code from > original.length}
3907      * @throws IllegalArgumentException if {@code from > to}
3908      * @throws NullPointerException if {@code original} is null
3909      * @since 1.6
3910      */
3911     @SuppressWarnings("unchecked")
3912     public static <T> T[] copyOfRange(T[] original, int from, int to) {
3913         return copyOfRange(original, from, to, (Class<? extends T[]>) original.getClass());
3914     }
3915 
3916     /**
3917      * Copies the specified range of the specified array into a new array.
3918      * The initial index of the range ({@code from}) must lie between zero
3919      * and {@code original.length}, inclusive.  The value at
3920      * {@code original[from]} is placed into the initial element of the copy
3921      * (unless {@code from == original.length} or {@code from == to}).
3922      * Values from subsequent elements in the original array are placed into
3923      * subsequent elements in the copy.  The final index of the range
3924      * ({@code to}), which must be greater than or equal to {@code from},
3925      * may be greater than {@code original.length}, in which case
3926      * {@code null} is placed in all elements of the copy whose index is
3927      * greater than or equal to {@code original.length - from}.  The length
3928      * of the returned array will be {@code to - from}.
3929      * The resulting array is of the class {@code newType}.
3930      *
3931      * @param <U> the class of the objects in the original array
3932      * @param <T> the class of the objects in the returned array
3933      * @param original the array from which a range is to be copied
3934      * @param from the initial index of the range to be copied, inclusive
3935      * @param to the final index of the range to be copied, exclusive.
3936      *     (This index may lie outside the array.)
3937      * @param newType the class of the copy to be returned
3938      * @return a new array containing the specified range from the original array,
3939      *     truncated or padded with nulls to obtain the required length
3940      * @throws ArrayIndexOutOfBoundsException if {@code from < 0}
3941      *     or {@code from > original.length}
3942      * @throws IllegalArgumentException if {@code from > to}
3943      * @throws NullPointerException if {@code original} is null
3944      * @throws ArrayStoreException if an element copied from
3945      *     {@code original} is not of a runtime type that can be stored in
3946      *     an array of class {@code newType}.
3947      * @since 1.6
3948      */
3949     @HotSpotIntrinsicCandidate
3950     public static <T,U> T[] copyOfRange(U[] original, int from, int to, Class<? extends T[]> newType) {
3951         int newLength = to - from;
3952         if (newLength < 0)
3953             throw new IllegalArgumentException(from + " > " + to);
3954         @SuppressWarnings("unchecked")
3955         T[] copy = ((Object)newType == (Object)Object[].class)
3956             ? (T[]) new Object[newLength]
3957             : (T[]) Array.newInstance(newType.getComponentType(), newLength);
3958         System.arraycopy(original, from, copy, 0,
3959                          Math.min(original.length - from, newLength));
3960         return copy;
3961     }
3962 
3963     /**
3964      * Copies the specified range of the specified array into a new array.
3965      * The initial index of the range ({@code from}) must lie between zero
3966      * and {@code original.length}, inclusive.  The value at
3967      * {@code original[from]} is placed into the initial element of the copy
3968      * (unless {@code from == original.length} or {@code from == to}).
3969      * Values from subsequent elements in the original array are placed into
3970      * subsequent elements in the copy.  The final index of the range
3971      * ({@code to}), which must be greater than or equal to {@code from},
3972      * may be greater than {@code original.length}, in which case
3973      * {@code (byte)0} is placed in all elements of the copy whose index is
3974      * greater than or equal to {@code original.length - from}.  The length
3975      * of the returned array will be {@code to - from}.
3976      *
3977      * @param original the array from which a range is to be copied
3978      * @param from the initial index of the range to be copied, inclusive
3979      * @param to the final index of the range to be copied, exclusive.
3980      *     (This index may lie outside the array.)
3981      * @return a new array containing the specified range from the original array,
3982      *     truncated or padded with zeros to obtain the required length
3983      * @throws ArrayIndexOutOfBoundsException if {@code from < 0}
3984      *     or {@code from > original.length}
3985      * @throws IllegalArgumentException if {@code from > to}
3986      * @throws NullPointerException if {@code original} is null
3987      * @since 1.6
3988      */
3989     public static byte[] copyOfRange(byte[] original, int from, int to) {
3990         int newLength = to - from;
3991         if (newLength < 0)
3992             throw new IllegalArgumentException(from + " > " + to);
3993         byte[] copy = new byte[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 (short)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 short[] copyOfRange(short[] original, int from, int to) {
4026         int newLength = to - from;
4027         if (newLength < 0)
4028             throw new IllegalArgumentException(from + " > " + to);
4029         short[] copy = new short[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 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 int[] copyOfRange(int[] original, int from, int to) {
4062         int newLength = to - from;
4063         if (newLength < 0)
4064             throw new IllegalArgumentException(from + " > " + to);
4065         int[] copy = new int[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 0L} 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 long[] copyOfRange(long[] original, int from, int to) {
4098         int newLength = to - from;
4099         if (newLength < 0)
4100             throw new IllegalArgumentException(from + " > " + to);
4101         long[] copy = new long[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 '\\u000'} 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 null characters 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 char[] copyOfRange(char[] original, int from, int to) {
4134         int newLength = to - from;
4135         if (newLength < 0)
4136             throw new IllegalArgumentException(from + " > " + to);
4137         char[] copy = new char[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 0f} 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 zeros 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 float[] copyOfRange(float[] original, int from, int to) {
4170         int newLength = to - from;
4171         if (newLength < 0)
4172             throw new IllegalArgumentException(from + " > " + to);
4173         float[] copy = new float[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 0d} 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 double[] copyOfRange(double[] original, int from, int to) {
4206         int newLength = to - from;
4207         if (newLength < 0)
4208             throw new IllegalArgumentException(from + " > " + to);
4209         double[] copy = new double[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 false} 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 false elements 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 boolean[] copyOfRange(boolean[] original, int from, int to) {
4242         int newLength = to - from;
4243         if (newLength < 0)
4244             throw new IllegalArgumentException(from + " > " + to);
4245         boolean[] copy = new boolean[newLength];
4246         System.arraycopy(original, from, copy, 0,
4247                          Math.min(original.length - from, newLength));
4248         return copy;
4249     }
4250 
4251     // Misc
4252 
4253     /**
4254      * Returns a fixed-size list backed by the specified array.  (Changes to
4255      * the returned list "write through" to the array.)  This method acts
4256      * as bridge between array-based and collection-based APIs, in
4257      * combination with {@link Collection#toArray}.  The returned list is
4258      * serializable and implements {@link RandomAccess}.
4259      *
4260      * <p>This method also provides a convenient way to create a fixed-size
4261      * list initialized to contain several elements:
4262      * <pre>
4263      *     List&lt;String&gt; stooges = Arrays.asList("Larry", "Moe", "Curly");
4264      * </pre>
4265      *
4266      * @param <T> the class of the objects in the array
4267      * @param a the array by which the list will be backed
4268      * @return a list view of the specified array
4269      */
4270     @SafeVarargs
4271     @SuppressWarnings("varargs")
4272     public static <T> List<T> asList(T... a) {
4273         return new ArrayList<>(a);
4274     }
4275 
4276     /**
4277      * @serial include
4278      */
4279     private static class ArrayList<E> extends AbstractList<E>
4280         implements RandomAccess, java.io.Serializable
4281     {
4282         private static final long serialVersionUID = -2764017481108945198L;
4283         private final E[] a;
4284 
4285         ArrayList(E[] array) {
4286             a = Objects.requireNonNull(array);
4287         }
4288 
4289         @Override
4290         public int size() {
4291             return a.length;
4292         }
4293 
4294         @Override
4295         public Object[] toArray() {
4296             return Arrays.copyOf(a, a.length, Object[].class);
4297         }
4298 
4299         @Override
4300         @SuppressWarnings("unchecked")
4301         public <T> T[] toArray(T[] a) {
4302             int size = size();
4303             if (a.length < size)
4304                 return Arrays.copyOf(this.a, size,
4305                                      (Class<? extends T[]>) a.getClass());
4306             System.arraycopy(this.a, 0, a, 0, size);
4307             if (a.length > size)
4308                 a[size] = null;
4309             return a;
4310         }
4311 
4312         @Override
4313         public E get(int index) {
4314             return a[index];
4315         }
4316 
4317         @Override
4318         public E set(int index, E element) {
4319             E oldValue = a[index];
4320             a[index] = element;
4321             return oldValue;
4322         }
4323 
4324         @Override
4325         public int indexOf(Object o) {
4326             E[] a = this.a;
4327             if (o == null) {
4328                 for (int i = 0; i < a.length; i++)
4329                     if (a[i] == null)
4330                         return i;
4331             } else {
4332                 for (int i = 0; i < a.length; i++)
4333                     if (o.equals(a[i]))
4334                         return i;
4335             }
4336             return -1;
4337         }
4338 
4339         @Override
4340         public boolean contains(Object o) {
4341             return indexOf(o) >= 0;
4342         }
4343 
4344         @Override
4345         public Spliterator<E> spliterator() {
4346             return Spliterators.spliterator(a, Spliterator.ORDERED);
4347         }
4348 
4349         @Override
4350         public void forEach(Consumer<? super E> action) {
4351             Objects.requireNonNull(action);
4352             for (E e : a) {
4353                 action.accept(e);
4354             }
4355         }
4356 
4357         @Override
4358         public void replaceAll(UnaryOperator<E> operator) {
4359             Objects.requireNonNull(operator);
4360             E[] a = this.a;
4361             for (int i = 0; i < a.length; i++) {
4362                 a[i] = operator.apply(a[i]);
4363             }
4364         }
4365 
4366         @Override
4367         public void sort(Comparator<? super E> c) {
4368             Arrays.sort(a, c);
4369         }
4370     }
4371 
4372     /**
4373      * Returns a hash code based on the contents of the specified array.
4374      * For any two {@code long} arrays {@code a} and {@code b}
4375      * such that {@code Arrays.equals(a, b)}, it is also the case that
4376      * {@code Arrays.hashCode(a) == Arrays.hashCode(b)}.
4377      *
4378      * <p>The value returned by this method is the same value that would be
4379      * obtained by invoking the {@link List#hashCode() hashCode}
4380      * method on a {@link List} containing a sequence of {@link Long}
4381      * instances representing the elements of {@code a} in the same order.
4382      * If {@code a} is {@code null}, this method returns 0.
4383      *
4384      * @param a the array whose hash value to compute
4385      * @return a content-based hash code for {@code a}
4386      * @since 1.5
4387      */
4388     public static int hashCode(long a[]) {
4389         if (a == null)
4390             return 0;
4391 
4392         int result = 1;
4393         for (long element : a) {
4394             int elementHash = (int)(element ^ (element >>> 32));
4395             result = 31 * result + elementHash;
4396         }
4397 
4398         return result;
4399     }
4400 
4401     /**
4402      * Returns a hash code based on the contents of the specified array.
4403      * For any two non-null {@code int} arrays {@code a} and {@code b}
4404      * such that {@code Arrays.equals(a, b)}, it is also the case that
4405      * {@code Arrays.hashCode(a) == Arrays.hashCode(b)}.
4406      *
4407      * <p>The value returned by this method is the same value that would be
4408      * obtained by invoking the {@link List#hashCode() hashCode}
4409      * method on a {@link List} containing a sequence of {@link Integer}
4410      * instances representing the elements of {@code a} in the same order.
4411      * If {@code a} is {@code null}, this method returns 0.
4412      *
4413      * @param a the array whose hash value to compute
4414      * @return a content-based hash code for {@code a}
4415      * @since 1.5
4416      */
4417     public static int hashCode(int a[]) {
4418         if (a == null)
4419             return 0;
4420 
4421         int result = 1;
4422         for (int element : a)
4423             result = 31 * result + element;
4424 
4425         return result;
4426     }
4427 
4428     /**
4429      * Returns a hash code based on the contents of the specified array.
4430      * For any two {@code short} arrays {@code a} and {@code b}
4431      * such that {@code Arrays.equals(a, b)}, it is also the case that
4432      * {@code Arrays.hashCode(a) == Arrays.hashCode(b)}.
4433      *
4434      * <p>The value returned by this method is the same value that would be
4435      * obtained by invoking the {@link List#hashCode() hashCode}
4436      * method on a {@link List} containing a sequence of {@link Short}
4437      * instances representing the elements of {@code a} in the same order.
4438      * If {@code a} is {@code null}, this method returns 0.
4439      *
4440      * @param a the array whose hash value to compute
4441      * @return a content-based hash code for {@code a}
4442      * @since 1.5
4443      */
4444     public static int hashCode(short a[]) {
4445         if (a == null)
4446             return 0;
4447 
4448         int result = 1;
4449         for (short element : a)
4450             result = 31 * result + element;
4451 
4452         return result;
4453     }
4454 
4455     /**
4456      * Returns a hash code based on the contents of the specified array.
4457      * For any two {@code char} arrays {@code a} and {@code b}
4458      * such that {@code Arrays.equals(a, b)}, it is also the case that
4459      * {@code Arrays.hashCode(a) == Arrays.hashCode(b)}.
4460      *
4461      * <p>The value returned by this method is the same value that would be
4462      * obtained by invoking the {@link List#hashCode() hashCode}
4463      * method on a {@link List} containing a sequence of {@link Character}
4464      * instances representing the elements of {@code a} in the same order.
4465      * If {@code a} is {@code null}, this method returns 0.
4466      *
4467      * @param a the array whose hash value to compute
4468      * @return a content-based hash code for {@code a}
4469      * @since 1.5
4470      */
4471     public static int hashCode(char a[]) {
4472         if (a == null)
4473             return 0;
4474 
4475         int result = 1;
4476         for (char element : a)
4477             result = 31 * result + element;
4478 
4479         return result;
4480     }
4481 
4482     /**
4483      * Returns a hash code based on the contents of the specified array.
4484      * For any two {@code byte} arrays {@code a} and {@code b}
4485      * such that {@code Arrays.equals(a, b)}, it is also the case that
4486      * {@code Arrays.hashCode(a) == Arrays.hashCode(b)}.
4487      *
4488      * <p>The value returned by this method is the same value that would be
4489      * obtained by invoking the {@link List#hashCode() hashCode}
4490      * method on a {@link List} containing a sequence of {@link Byte}
4491      * instances representing the elements of {@code a} in the same order.
4492      * If {@code a} is {@code null}, this method returns 0.
4493      *
4494      * @param a the array whose hash value to compute
4495      * @return a content-based hash code for {@code a}
4496      * @since 1.5
4497      */
4498     public static int hashCode(byte a[]) {
4499         if (a == null)
4500             return 0;
4501 
4502         int result = 1;
4503         for (byte element : a)
4504             result = 31 * result + element;
4505 
4506         return result;
4507     }
4508 
4509     /**
4510      * Returns a hash code based on the contents of the specified array.
4511      * For any two {@code boolean} arrays {@code a} and {@code b}
4512      * such that {@code Arrays.equals(a, b)}, it is also the case that
4513      * {@code Arrays.hashCode(a) == Arrays.hashCode(b)}.
4514      *
4515      * <p>The value returned by this method is the same value that would be
4516      * obtained by invoking the {@link List#hashCode() hashCode}
4517      * method on a {@link List} containing a sequence of {@link Boolean}
4518      * instances representing the elements of {@code a} in the same order.
4519      * If {@code a} is {@code null}, this method returns 0.
4520      *
4521      * @param a the array whose hash value to compute
4522      * @return a content-based hash code for {@code a}
4523      * @since 1.5
4524      */
4525     public static int hashCode(boolean a[]) {
4526         if (a == null)
4527             return 0;
4528 
4529         int result = 1;
4530         for (boolean element : a)
4531             result = 31 * result + (element ? 1231 : 1237);
4532 
4533         return result;
4534     }
4535 
4536     /**
4537      * Returns a hash code based on the contents of the specified array.
4538      * For any two {@code float} arrays {@code a} and {@code b}
4539      * such that {@code Arrays.equals(a, b)}, it is also the case that
4540      * {@code Arrays.hashCode(a) == Arrays.hashCode(b)}.
4541      *
4542      * <p>The value returned by this method is the same value that would be
4543      * obtained by invoking the {@link List#hashCode() hashCode}
4544      * method on a {@link List} containing a sequence of {@link Float}
4545      * instances representing the elements of {@code a} in the same order.
4546      * If {@code a} is {@code null}, this method returns 0.
4547      *
4548      * @param a the array whose hash value to compute
4549      * @return a content-based hash code for {@code a}
4550      * @since 1.5
4551      */
4552     public static int hashCode(float a[]) {
4553         if (a == null)
4554             return 0;
4555 
4556         int result = 1;
4557         for (float element : a)
4558             result = 31 * result + Float.floatToIntBits(element);
4559 
4560         return result;
4561     }
4562 
4563     /**
4564      * Returns a hash code based on the contents of the specified array.
4565      * For any two {@code double} arrays {@code a} and {@code b}
4566      * such that {@code Arrays.equals(a, b)}, it is also the case that
4567      * {@code Arrays.hashCode(a) == Arrays.hashCode(b)}.
4568      *
4569      * <p>The value returned by this method is the same value that would be
4570      * obtained by invoking the {@link List#hashCode() hashCode}
4571      * method on a {@link List} containing a sequence of {@link Double}
4572      * instances representing the elements of {@code a} in the same order.
4573      * If {@code a} is {@code null}, this method returns 0.
4574      *
4575      * @param a the array whose hash value to compute
4576      * @return a content-based hash code for {@code a}
4577      * @since 1.5
4578      */
4579     public static int hashCode(double a[]) {
4580         if (a == null)
4581             return 0;
4582 
4583         int result = 1;
4584         for (double element : a) {
4585             long bits = Double.doubleToLongBits(element);
4586             result = 31 * result + (int)(bits ^ (bits >>> 32));
4587         }
4588         return result;
4589     }
4590 
4591     /**
4592      * Returns a hash code based on the contents of the specified array.  If
4593      * the array contains other arrays as elements, the hash code is based on
4594      * their identities rather than their contents.  It is therefore
4595      * acceptable to invoke this method on an array that contains itself as an
4596      * element,  either directly or indirectly through one or more levels of
4597      * arrays.
4598      *
4599      * <p>For any two arrays {@code a} and {@code b} such that
4600      * {@code Arrays.equals(a, b)}, it is also the case that
4601      * {@code Arrays.hashCode(a) == Arrays.hashCode(b)}.
4602      *
4603      * <p>The value returned by this method is equal to the value that would
4604      * be returned by {@code Arrays.asList(a).hashCode()}, unless {@code a}
4605      * is {@code null}, in which case {@code 0} is returned.
4606      *
4607      * @param a the array whose content-based hash code to compute
4608      * @return a content-based hash code for {@code a}
4609      * @see #deepHashCode(Object[])
4610      * @since 1.5
4611      */
4612     public static int hashCode(Object a[]) {
4613         if (a == null)
4614             return 0;
4615 
4616         int result = 1;
4617 
4618         for (Object element : a)
4619             result = 31 * result + (element == null ? 0 : element.hashCode());
4620 
4621         return result;
4622     }
4623 
4624     /**
4625      * Returns a hash code based on the "deep contents" of the specified
4626      * array.  If the array contains other arrays as elements, the
4627      * hash code is based on their contents and so on, ad infinitum.
4628      * It is therefore unacceptable to invoke this method on an array that
4629      * contains itself as an element, either directly or indirectly through
4630      * one or more levels of arrays.  The behavior of such an invocation is
4631      * undefined.
4632      *
4633      * <p>For any two arrays {@code a} and {@code b} such that
4634      * {@code Arrays.deepEquals(a, b)}, it is also the case that
4635      * {@code Arrays.deepHashCode(a) == Arrays.deepHashCode(b)}.
4636      *
4637      * <p>The computation of the value returned by this method is similar to
4638      * that of the value returned by {@link List#hashCode()} on a list
4639      * containing the same elements as {@code a} in the same order, with one
4640      * difference: If an element {@code e} of {@code a} is itself an array,
4641      * its hash code is computed not by calling {@code e.hashCode()}, but as
4642      * by calling the appropriate overloading of {@code Arrays.hashCode(e)}
4643      * if {@code e} is an array of a primitive type, or as by calling
4644      * {@code Arrays.deepHashCode(e)} recursively if {@code e} is an array
4645      * of a reference type.  If {@code a} is {@code null}, this method
4646      * returns 0.
4647      *
4648      * @param a the array whose deep-content-based hash code to compute
4649      * @return a deep-content-based hash code for {@code a}
4650      * @see #hashCode(Object[])
4651      * @since 1.5
4652      */
4653     public static int deepHashCode(Object a[]) {
4654         if (a == null)
4655             return 0;
4656 
4657         int result = 1;
4658 
4659         for (Object element : a) {
4660             int elementHash = 0;
4661             if (element instanceof Object[])
4662                 elementHash = deepHashCode((Object[]) element);
4663             else if (element instanceof byte[])
4664                 elementHash = hashCode((byte[]) element);
4665             else if (element instanceof short[])
4666                 elementHash = hashCode((short[]) element);
4667             else if (element instanceof int[])
4668                 elementHash = hashCode((int[]) element);
4669             else if (element instanceof long[])
4670                 elementHash = hashCode((long[]) element);
4671             else if (element instanceof char[])
4672                 elementHash = hashCode((char[]) element);
4673             else if (element instanceof float[])
4674                 elementHash = hashCode((float[]) element);
4675             else if (element instanceof double[])
4676                 elementHash = hashCode((double[]) element);
4677             else if (element instanceof boolean[])
4678                 elementHash = hashCode((boolean[]) element);
4679             else if (element != null)
4680                 elementHash = element.hashCode();
4681 
4682             result = 31 * result + elementHash;
4683         }
4684 
4685         return result;
4686     }
4687 
4688     /**
4689      * Returns {@code true} if the two specified arrays are <i>deeply
4690      * equal</i> to one another.  Unlike the {@link #equals(Object[],Object[])}
4691      * method, this method is appropriate for use with nested arrays of
4692      * arbitrary depth.
4693      *
4694      * <p>Two array references are considered deeply equal if both
4695      * are {@code null}, or if they refer to arrays that contain the same
4696      * number of elements and all corresponding pairs of elements in the two
4697      * arrays are deeply equal.
4698      *
4699      * <p>Two possibly {@code null} elements {@code e1} and {@code e2} are
4700      * deeply equal if any of the following conditions hold:
4701      * <ul>
4702      *    <li> {@code e1} and {@code e2} are both arrays of object reference
4703      *         types, and {@code Arrays.deepEquals(e1, e2) would return true}
4704      *    <li> {@code e1} and {@code e2} are arrays of the same primitive
4705      *         type, and the appropriate overloading of
4706      *         {@code Arrays.equals(e1, e2)} would return true.
4707      *    <li> {@code e1 == e2}
4708      *    <li> {@code e1.equals(e2)} would return true.
4709      * </ul>
4710      * Note that this definition permits {@code null} elements at any depth.
4711      *
4712      * <p>If either of the specified arrays contain themselves as elements
4713      * either directly or indirectly through one or more levels of arrays,
4714      * the behavior of this method is undefined.
4715      *
4716      * @param a1 one array to be tested for equality
4717      * @param a2 the other array to be tested for equality
4718      * @return {@code true} if the two arrays are equal
4719      * @see #equals(Object[],Object[])
4720      * @see Objects#deepEquals(Object, Object)
4721      * @since 1.5
4722      */
4723     public static boolean deepEquals(Object[] a1, Object[] a2) {
4724         if (a1 == a2)
4725             return true;
4726         if (a1 == null || a2==null)
4727             return false;
4728         int length = a1.length;
4729         if (a2.length != length)
4730             return false;
4731 
4732         for (int i = 0; i < length; i++) {
4733             Object e1 = a1[i];
4734             Object e2 = a2[i];
4735 
4736             if (e1 == e2)
4737                 continue;
4738             if (e1 == null)
4739                 return false;
4740 
4741             // Figure out whether the two elements are equal
4742             boolean eq = deepEquals0(e1, e2);
4743 
4744             if (!eq)
4745                 return false;
4746         }
4747         return true;
4748     }
4749 
4750     static boolean deepEquals0(Object e1, Object e2) {
4751         assert e1 != null;
4752         boolean eq;
4753         if (e1 instanceof Object[] && e2 instanceof Object[])
4754             eq = deepEquals ((Object[]) e1, (Object[]) e2);
4755         else if (e1 instanceof byte[] && e2 instanceof byte[])
4756             eq = equals((byte[]) e1, (byte[]) e2);
4757         else if (e1 instanceof short[] && e2 instanceof short[])
4758             eq = equals((short[]) e1, (short[]) e2);
4759         else if (e1 instanceof int[] && e2 instanceof int[])
4760             eq = equals((int[]) e1, (int[]) e2);
4761         else if (e1 instanceof long[] && e2 instanceof long[])
4762             eq = equals((long[]) e1, (long[]) e2);
4763         else if (e1 instanceof char[] && e2 instanceof char[])
4764             eq = equals((char[]) e1, (char[]) e2);
4765         else if (e1 instanceof float[] && e2 instanceof float[])
4766             eq = equals((float[]) e1, (float[]) e2);
4767         else if (e1 instanceof double[] && e2 instanceof double[])
4768             eq = equals((double[]) e1, (double[]) e2);
4769         else if (e1 instanceof boolean[] && e2 instanceof boolean[])
4770             eq = equals((boolean[]) e1, (boolean[]) e2);
4771         else
4772             eq = e1.equals(e2);
4773         return eq;
4774     }
4775 
4776     /**
4777      * Returns a string representation of the contents of the specified array.
4778      * The string representation consists of a list of the array's elements,
4779      * enclosed in square brackets ({@code "[]"}).  Adjacent elements are
4780      * separated by the characters {@code ", "} (a comma followed by a
4781      * space).  Elements are converted to strings as by
4782      * {@code String.valueOf(long)}.  Returns {@code "null"} if {@code a}
4783      * is {@code null}.
4784      *
4785      * @param a the array whose string representation to return
4786      * @return a string representation of {@code a}
4787      * @since 1.5
4788      */
4789     public static String toString(long[] a) {
4790         if (a == null)
4791             return "null";
4792         int iMax = a.length - 1;
4793         if (iMax == -1)
4794             return "[]";
4795 
4796         StringBuilder b = new StringBuilder();
4797         b.append('[');
4798         for (int i = 0; ; i++) {
4799             b.append(a[i]);
4800             if (i == iMax)
4801                 return b.append(']').toString();
4802             b.append(", ");
4803         }
4804     }
4805 
4806     /**
4807      * Returns a string representation of the contents of the specified array.
4808      * The string representation consists of a list of the array's elements,
4809      * enclosed in square brackets ({@code "[]"}).  Adjacent elements are
4810      * separated by the characters {@code ", "} (a comma followed by a
4811      * space).  Elements are converted to strings as by
4812      * {@code String.valueOf(int)}.  Returns {@code "null"} if {@code a} is
4813      * {@code null}.
4814      *
4815      * @param a the array whose string representation to return
4816      * @return a string representation of {@code a}
4817      * @since 1.5
4818      */
4819     public static String toString(int[] a) {
4820         if (a == null)
4821             return "null";
4822         int iMax = a.length - 1;
4823         if (iMax == -1)
4824             return "[]";
4825 
4826         StringBuilder b = new StringBuilder();
4827         b.append('[');
4828         for (int i = 0; ; i++) {
4829             b.append(a[i]);
4830             if (i == iMax)
4831                 return b.append(']').toString();
4832             b.append(", ");
4833         }
4834     }
4835 
4836     /**
4837      * Returns a string representation of the contents of the specified array.
4838      * The string representation consists of a list of the array's elements,
4839      * enclosed in square brackets ({@code "[]"}).  Adjacent elements are
4840      * separated by the characters {@code ", "} (a comma followed by a
4841      * space).  Elements are converted to strings as by
4842      * {@code String.valueOf(short)}.  Returns {@code "null"} if {@code a}
4843      * is {@code null}.
4844      *
4845      * @param a the array whose string representation to return
4846      * @return a string representation of {@code a}
4847      * @since 1.5
4848      */
4849     public static String toString(short[] a) {
4850         if (a == null)
4851             return "null";
4852         int iMax = a.length - 1;
4853         if (iMax == -1)
4854             return "[]";
4855 
4856         StringBuilder b = new StringBuilder();
4857         b.append('[');
4858         for (int i = 0; ; i++) {
4859             b.append(a[i]);
4860             if (i == iMax)
4861                 return b.append(']').toString();
4862             b.append(", ");
4863         }
4864     }
4865 
4866     /**
4867      * Returns a string representation of the contents of the specified array.
4868      * The string representation consists of a list of the array's elements,
4869      * enclosed in square brackets ({@code "[]"}).  Adjacent elements are
4870      * separated by the characters {@code ", "} (a comma followed by a
4871      * space).  Elements are converted to strings as by
4872      * {@code String.valueOf(char)}.  Returns {@code "null"} if {@code a}
4873      * is {@code null}.
4874      *
4875      * @param a the array whose string representation to return
4876      * @return a string representation of {@code a}
4877      * @since 1.5
4878      */
4879     public static String toString(char[] a) {
4880         if (a == null)
4881             return "null";
4882         int iMax = a.length - 1;
4883         if (iMax == -1)
4884             return "[]";
4885 
4886         StringBuilder b = new StringBuilder();
4887         b.append('[');
4888         for (int i = 0; ; i++) {
4889             b.append(a[i]);
4890             if (i == iMax)
4891                 return b.append(']').toString();
4892             b.append(", ");
4893         }
4894     }
4895 
4896     /**
4897      * Returns a string representation of the contents of the specified array.
4898      * The string representation consists of a list of the array's elements,
4899      * enclosed in square brackets ({@code "[]"}).  Adjacent elements
4900      * are separated by the characters {@code ", "} (a comma followed
4901      * by a space).  Elements are converted to strings as by
4902      * {@code String.valueOf(byte)}.  Returns {@code "null"} if
4903      * {@code a} is {@code null}.
4904      *
4905      * @param a the array whose string representation to return
4906      * @return a string representation of {@code a}
4907      * @since 1.5
4908      */
4909     public static String toString(byte[] a) {
4910         if (a == null)
4911             return "null";
4912         int iMax = a.length - 1;
4913         if (iMax == -1)
4914             return "[]";
4915 
4916         StringBuilder b = new StringBuilder();
4917         b.append('[');
4918         for (int i = 0; ; i++) {
4919             b.append(a[i]);
4920             if (i == iMax)
4921                 return b.append(']').toString();
4922             b.append(", ");
4923         }
4924     }
4925 
4926     /**
4927      * Returns a string representation of the contents of the specified array.
4928      * The string representation consists of a list of the array's elements,
4929      * enclosed in square brackets ({@code "[]"}).  Adjacent elements are
4930      * separated by the characters {@code ", "} (a comma followed by a
4931      * space).  Elements are converted to strings as by
4932      * {@code String.valueOf(boolean)}.  Returns {@code "null"} if
4933      * {@code a} is {@code null}.
4934      *
4935      * @param a the array whose string representation to return
4936      * @return a string representation of {@code a}
4937      * @since 1.5
4938      */
4939     public static String toString(boolean[] a) {
4940         if (a == null)
4941             return "null";
4942         int iMax = a.length - 1;
4943         if (iMax == -1)
4944             return "[]";
4945 
4946         StringBuilder b = new StringBuilder();
4947         b.append('[');
4948         for (int i = 0; ; i++) {
4949             b.append(a[i]);
4950             if (i == iMax)
4951                 return b.append(']').toString();
4952             b.append(", ");
4953         }
4954     }
4955 
4956     /**
4957      * Returns a string representation of the contents of the specified array.
4958      * The string representation consists of a list of the array's elements,
4959      * enclosed in square brackets ({@code "[]"}).  Adjacent elements are
4960      * separated by the characters {@code ", "} (a comma followed by a
4961      * space).  Elements are converted to strings as by
4962      * {@code String.valueOf(float)}.  Returns {@code "null"} if {@code a}
4963      * is {@code null}.
4964      *
4965      * @param a the array whose string representation to return
4966      * @return a string representation of {@code a}
4967      * @since 1.5
4968      */
4969     public static String toString(float[] a) {
4970         if (a == null)
4971             return "null";
4972 
4973         int iMax = a.length - 1;
4974         if (iMax == -1)
4975             return "[]";
4976 
4977         StringBuilder b = new StringBuilder();
4978         b.append('[');
4979         for (int i = 0; ; i++) {
4980             b.append(a[i]);
4981             if (i == iMax)
4982                 return b.append(']').toString();
4983             b.append(", ");
4984         }
4985     }
4986 
4987     /**
4988      * Returns a string representation of the contents of the specified array.
4989      * The string representation consists of a list of the array's elements,
4990      * enclosed in square brackets ({@code "[]"}).  Adjacent elements are
4991      * separated by the characters {@code ", "} (a comma followed by a
4992      * space).  Elements are converted to strings as by
4993      * {@code String.valueOf(double)}.  Returns {@code "null"} if {@code a}
4994      * is {@code null}.
4995      *
4996      * @param a the array whose string representation to return
4997      * @return a string representation of {@code a}
4998      * @since 1.5
4999      */
5000     public static String toString(double[] a) {
5001         if (a == null)
5002             return "null";
5003         int iMax = a.length - 1;
5004         if (iMax == -1)
5005             return "[]";
5006 
5007         StringBuilder b = new StringBuilder();
5008         b.append('[');
5009         for (int i = 0; ; i++) {
5010             b.append(a[i]);
5011             if (i == iMax)
5012                 return b.append(']').toString();
5013             b.append(", ");
5014         }
5015     }
5016 
5017     /**
5018      * Returns a string representation of the contents of the specified array.
5019      * If the array contains other arrays as elements, they are converted to
5020      * strings by the {@link Object#toString} method inherited from
5021      * {@code Object}, which describes their <i>identities</i> rather than
5022      * their contents.
5023      *
5024      * <p>The value returned by this method is equal to the value that would
5025      * be returned by {@code Arrays.asList(a).toString()}, unless {@code a}
5026      * is {@code null}, in which case {@code "null"} is returned.
5027      *
5028      * @param a the array whose string representation to return
5029      * @return a string representation of {@code a}
5030      * @see #deepToString(Object[])
5031      * @since 1.5
5032      */
5033     public static String toString(Object[] a) {
5034         if (a == null)
5035             return "null";
5036 
5037         int iMax = a.length - 1;
5038         if (iMax == -1)
5039             return "[]";
5040 
5041         StringBuilder b = new StringBuilder();
5042         b.append('[');
5043         for (int i = 0; ; i++) {
5044             b.append(String.valueOf(a[i]));
5045             if (i == iMax)
5046                 return b.append(']').toString();
5047             b.append(", ");
5048         }
5049     }
5050 
5051     /**
5052      * Returns a string representation of the "deep contents" of the specified
5053      * array.  If the array contains other arrays as elements, the string
5054      * representation contains their contents and so on.  This method is
5055      * designed for converting multidimensional arrays to strings.
5056      *
5057      * <p>The string representation consists of a list of the array's
5058      * elements, enclosed in square brackets ({@code "[]"}).  Adjacent
5059      * elements are separated by the characters {@code ", "} (a comma
5060      * followed by a space).  Elements are converted to strings as by
5061      * {@code String.valueOf(Object)}, unless they are themselves
5062      * arrays.
5063      *
5064      * <p>If an element {@code e} is an array of a primitive type, it is
5065      * converted to a string as by invoking the appropriate overloading of
5066      * {@code Arrays.toString(e)}.  If an element {@code e} is an array of a
5067      * reference type, it is converted to a string as by invoking
5068      * this method recursively.
5069      *
5070      * <p>To avoid infinite recursion, if the specified array contains itself
5071      * as an element, or contains an indirect reference to itself through one
5072      * or more levels of arrays, the self-reference is converted to the string
5073      * {@code "[...]"}.  For example, an array containing only a reference
5074      * to itself would be rendered as {@code "[[...]]"}.
5075      *
5076      * <p>This method returns {@code "null"} if the specified array
5077      * is {@code null}.
5078      *
5079      * @param a the array whose string representation to return
5080      * @return a string representation of {@code a}
5081      * @see #toString(Object[])
5082      * @since 1.5
5083      */
5084     public static String deepToString(Object[] a) {
5085         if (a == null)
5086             return "null";
5087 
5088         int bufLen = 20 * a.length;
5089         if (a.length != 0 && bufLen <= 0)
5090             bufLen = Integer.MAX_VALUE;
5091         StringBuilder buf = new StringBuilder(bufLen);
5092         deepToString(a, buf, new HashSet<>());
5093         return buf.toString();
5094     }
5095 
5096     private static void deepToString(Object[] a, StringBuilder buf,
5097                                      Set<Object[]> dejaVu) {
5098         if (a == null) {
5099             buf.append("null");
5100             return;
5101         }
5102         int iMax = a.length - 1;
5103         if (iMax == -1) {
5104             buf.append("[]");
5105             return;
5106         }
5107 
5108         dejaVu.add(a);
5109         buf.append('[');
5110         for (int i = 0; ; i++) {
5111 
5112             Object element = a[i];
5113             if (element == null) {
5114                 buf.append("null");
5115             } else {
5116                 Class<?> eClass = element.getClass();
5117 
5118                 if (eClass.isArray()) {
5119                     if (eClass == byte[].class)
5120                         buf.append(toString((byte[]) element));
5121                     else if (eClass == short[].class)
5122                         buf.append(toString((short[]) element));
5123                     else if (eClass == int[].class)
5124                         buf.append(toString((int[]) element));
5125                     else if (eClass == long[].class)
5126                         buf.append(toString((long[]) element));
5127                     else if (eClass == char[].class)
5128                         buf.append(toString((char[]) element));
5129                     else if (eClass == float[].class)
5130                         buf.append(toString((float[]) element));
5131                     else if (eClass == double[].class)
5132                         buf.append(toString((double[]) element));
5133                     else if (eClass == boolean[].class)
5134                         buf.append(toString((boolean[]) element));
5135                     else { // element is an array of object references
5136                         if (dejaVu.contains(element))
5137                             buf.append("[...]");
5138                         else
5139                             deepToString((Object[])element, buf, dejaVu);
5140                     }
5141                 } else {  // element is non-null and not an array
5142                     buf.append(element.toString());
5143                 }
5144             }
5145             if (i == iMax)
5146                 break;
5147             buf.append(", ");
5148         }
5149         buf.append(']');
5150         dejaVu.remove(a);
5151     }
5152 
5153 
5154     /**
5155      * Set all elements of the specified array, using the provided
5156      * generator function to compute each element.
5157      *
5158      * <p>If the generator function throws an exception, it is relayed to
5159      * the caller and the array is left in an indeterminate state.
5160      *
5161      * @apiNote
5162      * Setting a subrange of an array, using a generator function to compute
5163      * each element, can be written as follows:
5164      * <pre>{@code
5165      * IntStream.range(startInclusive, endExclusive)
5166      *          .forEach(i -> array[i] = generator.apply(i));
5167      * }</pre>
5168      *
5169      * @param <T> type of elements of the array
5170      * @param array array to be initialized
5171      * @param generator a function accepting an index and producing the desired
5172      *        value for that position
5173      * @throws NullPointerException if the generator is null
5174      * @since 1.8
5175      */
5176     public static <T> void setAll(T[] array, IntFunction<? extends T> generator) {
5177         Objects.requireNonNull(generator);
5178         for (int i = 0; i < array.length; i++)
5179             array[i] = generator.apply(i);
5180     }
5181 
5182     /**
5183      * Set all elements of the specified array, in parallel, using the
5184      * provided generator function to compute each element.
5185      *
5186      * <p>If the generator function throws an exception, an unchecked exception
5187      * is thrown from {@code parallelSetAll} and the array is left in an
5188      * indeterminate state.
5189      *
5190      * @apiNote
5191      * Setting a subrange of an array, in parallel, using a generator function
5192      * to compute each element, can be written as follows:
5193      * <pre>{@code
5194      * IntStream.range(startInclusive, endExclusive)
5195      *          .parallel()
5196      *          .forEach(i -> array[i] = generator.apply(i));
5197      * }</pre>
5198      *
5199      * @param <T> type of elements of the array
5200      * @param array array to be initialized
5201      * @param generator a function accepting an index and producing the desired
5202      *        value for that position
5203      * @throws NullPointerException if the generator is null
5204      * @since 1.8
5205      */
5206     public static <T> void parallelSetAll(T[] array, IntFunction<? extends T> generator) {
5207         Objects.requireNonNull(generator);
5208         IntStream.range(0, array.length).parallel().forEach(i -> { array[i] = generator.apply(i); });
5209     }
5210 
5211     /**
5212      * Set all elements of the specified array, using the provided
5213      * generator function to compute each element.
5214      *
5215      * <p>If the generator function throws an exception, it is relayed to
5216      * the caller and the array is left in an indeterminate state.
5217      *
5218      * @apiNote
5219      * Setting a subrange of an array, using a generator function to compute
5220      * each element, can be written as follows:
5221      * <pre>{@code
5222      * IntStream.range(startInclusive, endExclusive)
5223      *          .forEach(i -> array[i] = generator.applyAsInt(i));
5224      * }</pre>
5225      *
5226      * @param array array to be initialized
5227      * @param generator a function accepting an index and producing the desired
5228      *        value for that position
5229      * @throws NullPointerException if the generator is null
5230      * @since 1.8
5231      */
5232     public static void setAll(int[] array, IntUnaryOperator generator) {
5233         Objects.requireNonNull(generator);
5234         for (int i = 0; i < array.length; i++)
5235             array[i] = generator.applyAsInt(i);
5236     }
5237 
5238     /**
5239      * Set all elements of the specified array, in parallel, using the
5240      * provided generator function to compute each element.
5241      *
5242      * <p>If the generator function throws an exception, an unchecked exception
5243      * is thrown from {@code parallelSetAll} and the array is left in an
5244      * indeterminate state.
5245      *
5246      * @apiNote
5247      * Setting a subrange of an array, in parallel, using a generator function
5248      * to compute each element, can be written as follows:
5249      * <pre>{@code
5250      * IntStream.range(startInclusive, endExclusive)
5251      *          .parallel()
5252      *          .forEach(i -> array[i] = generator.applyAsInt(i));
5253      * }</pre>
5254      *
5255      * @param array array to be initialized
5256      * @param generator a function accepting an index and producing the desired
5257      * value for that position
5258      * @throws NullPointerException if the generator is null
5259      * @since 1.8
5260      */
5261     public static void parallelSetAll(int[] array, IntUnaryOperator generator) {
5262         Objects.requireNonNull(generator);
5263         IntStream.range(0, array.length).parallel().forEach(i -> { array[i] = generator.applyAsInt(i); });
5264     }
5265 
5266     /**
5267      * Set all elements of the specified array, using the provided
5268      * generator function to compute each element.
5269      *
5270      * <p>If the generator function throws an exception, it is relayed to
5271      * the caller and the array is left in an indeterminate state.
5272      *
5273      * @apiNote
5274      * Setting a subrange of an array, using a generator function to compute
5275      * each element, can be written as follows:
5276      * <pre>{@code
5277      * IntStream.range(startInclusive, endExclusive)
5278      *          .forEach(i -> array[i] = generator.applyAsLong(i));
5279      * }</pre>
5280      *
5281      * @param array array to be initialized
5282      * @param generator a function accepting an index and producing the desired
5283      *        value for that position
5284      * @throws NullPointerException if the generator is null
5285      * @since 1.8
5286      */
5287     public static void setAll(long[] array, IntToLongFunction generator) {
5288         Objects.requireNonNull(generator);
5289         for (int i = 0; i < array.length; i++)
5290             array[i] = generator.applyAsLong(i);
5291     }
5292 
5293     /**
5294      * Set all elements of the specified array, in parallel, using the
5295      * provided generator function to compute each element.
5296      *
5297      * <p>If the generator function throws an exception, an unchecked exception
5298      * is thrown from {@code parallelSetAll} and the array is left in an
5299      * indeterminate state.
5300      *
5301      * @apiNote
5302      * Setting a subrange of an array, in parallel, using a generator function
5303      * to compute each element, can be written as follows:
5304      * <pre>{@code
5305      * IntStream.range(startInclusive, endExclusive)
5306      *          .parallel()
5307      *          .forEach(i -> array[i] = generator.applyAsLong(i));
5308      * }</pre>
5309      *
5310      * @param array array to be initialized
5311      * @param generator a function accepting an index and producing the desired
5312      *        value for that position
5313      * @throws NullPointerException if the generator is null
5314      * @since 1.8
5315      */
5316     public static void parallelSetAll(long[] array, IntToLongFunction generator) {
5317         Objects.requireNonNull(generator);
5318         IntStream.range(0, array.length).parallel().forEach(i -> { array[i] = generator.applyAsLong(i); });
5319     }
5320 
5321     /**
5322      * Set all elements of the specified array, using the provided
5323      * generator function to compute each element.
5324      *
5325      * <p>If the generator function throws an exception, it is relayed to
5326      * the caller and the array is left in an indeterminate state.
5327      *
5328      * @apiNote
5329      * Setting a subrange of an array, using a generator function to compute
5330      * each element, can be written as follows:
5331      * <pre>{@code
5332      * IntStream.range(startInclusive, endExclusive)
5333      *          .forEach(i -> array[i] = generator.applyAsDouble(i));
5334      * }</pre>
5335      *
5336      * @param array array to be initialized
5337      * @param generator a function accepting an index and producing the desired
5338      *        value for that position
5339      * @throws NullPointerException if the generator is null
5340      * @since 1.8
5341      */
5342     public static void setAll(double[] array, IntToDoubleFunction generator) {
5343         Objects.requireNonNull(generator);
5344         for (int i = 0; i < array.length; i++)
5345             array[i] = generator.applyAsDouble(i);
5346     }
5347 
5348     /**
5349      * Set all elements of the specified array, in parallel, using the
5350      * provided generator function to compute each element.
5351      *
5352      * <p>If the generator function throws an exception, an unchecked exception
5353      * is thrown from {@code parallelSetAll} and the array is left in an
5354      * indeterminate state.
5355      *
5356      * @apiNote
5357      * Setting a subrange of an array, in parallel, using a generator function
5358      * to compute each element, can be written as follows:
5359      * <pre>{@code
5360      * IntStream.range(startInclusive, endExclusive)
5361      *          .parallel()
5362      *          .forEach(i -> array[i] = generator.applyAsDouble(i));
5363      * }</pre>
5364      *
5365      * @param array array to be initialized
5366      * @param generator a function accepting an index and producing the desired
5367      *        value for that position
5368      * @throws NullPointerException if the generator is null
5369      * @since 1.8
5370      */
5371     public static void parallelSetAll(double[] array, IntToDoubleFunction generator) {
5372         Objects.requireNonNull(generator);
5373         IntStream.range(0, array.length).parallel().forEach(i -> { array[i] = generator.applyAsDouble(i); });
5374     }
5375 
5376     /**
5377      * Returns a {@link Spliterator} covering all of the specified array.
5378      *
5379      * <p>The spliterator reports {@link Spliterator#SIZED},
5380      * {@link Spliterator#SUBSIZED}, {@link Spliterator#ORDERED}, and
5381      * {@link Spliterator#IMMUTABLE}.
5382      *
5383      * @param <T> type of elements
5384      * @param array the array, assumed to be unmodified during use
5385      * @return a spliterator for the array elements
5386      * @since 1.8
5387      */
5388     public static <T> Spliterator<T> spliterator(T[] array) {
5389         return Spliterators.spliterator(array,
5390                                         Spliterator.ORDERED | Spliterator.IMMUTABLE);
5391     }
5392 
5393     /**
5394      * Returns a {@link Spliterator} covering the specified range of the
5395      * specified array.
5396      *
5397      * <p>The spliterator reports {@link Spliterator#SIZED},
5398      * {@link Spliterator#SUBSIZED}, {@link Spliterator#ORDERED}, and
5399      * {@link Spliterator#IMMUTABLE}.
5400      *
5401      * @param <T> type of elements
5402      * @param array the array, assumed to be unmodified during use
5403      * @param startInclusive the first index to cover, inclusive
5404      * @param endExclusive index immediately past the last index to cover
5405      * @return a spliterator for the array elements
5406      * @throws ArrayIndexOutOfBoundsException if {@code startInclusive} is
5407      *         negative, {@code endExclusive} is less than
5408      *         {@code startInclusive}, or {@code endExclusive} is greater than
5409      *         the array size
5410      * @since 1.8
5411      */
5412     public static <T> Spliterator<T> spliterator(T[] array, int startInclusive, int endExclusive) {
5413         return Spliterators.spliterator(array, startInclusive, endExclusive,
5414                                         Spliterator.ORDERED | Spliterator.IMMUTABLE);
5415     }
5416 
5417     /**
5418      * Returns a {@link Spliterator.OfInt} covering all of the specified array.
5419      *
5420      * <p>The spliterator reports {@link Spliterator#SIZED},
5421      * {@link Spliterator#SUBSIZED}, {@link Spliterator#ORDERED}, and
5422      * {@link Spliterator#IMMUTABLE}.
5423      *
5424      * @param array the array, assumed to be unmodified during use
5425      * @return a spliterator for the array elements
5426      * @since 1.8
5427      */
5428     public static Spliterator.OfInt spliterator(int[] array) {
5429         return Spliterators.spliterator(array,
5430                                         Spliterator.ORDERED | Spliterator.IMMUTABLE);
5431     }
5432 
5433     /**
5434      * Returns a {@link Spliterator.OfInt} covering the specified range of the
5435      * specified array.
5436      *
5437      * <p>The spliterator reports {@link Spliterator#SIZED},
5438      * {@link Spliterator#SUBSIZED}, {@link Spliterator#ORDERED}, and
5439      * {@link Spliterator#IMMUTABLE}.
5440      *
5441      * @param array the array, assumed to be unmodified during use
5442      * @param startInclusive the first index to cover, inclusive
5443      * @param endExclusive index immediately past the last index to cover
5444      * @return a spliterator for the array elements
5445      * @throws ArrayIndexOutOfBoundsException if {@code startInclusive} is
5446      *         negative, {@code endExclusive} is less than
5447      *         {@code startInclusive}, or {@code endExclusive} is greater than
5448      *         the array size
5449      * @since 1.8
5450      */
5451     public static Spliterator.OfInt spliterator(int[] array, int startInclusive, int endExclusive) {
5452         return Spliterators.spliterator(array, startInclusive, endExclusive,
5453                                         Spliterator.ORDERED | Spliterator.IMMUTABLE);
5454     }
5455 
5456     /**
5457      * Returns a {@link Spliterator.OfLong} covering all of the specified array.
5458      *
5459      * <p>The spliterator reports {@link Spliterator#SIZED},
5460      * {@link Spliterator#SUBSIZED}, {@link Spliterator#ORDERED}, and
5461      * {@link Spliterator#IMMUTABLE}.
5462      *
5463      * @param array the array, assumed to be unmodified during use
5464      * @return the spliterator for the array elements
5465      * @since 1.8
5466      */
5467     public static Spliterator.OfLong spliterator(long[] array) {
5468         return Spliterators.spliterator(array,
5469                                         Spliterator.ORDERED | Spliterator.IMMUTABLE);
5470     }
5471 
5472     /**
5473      * Returns a {@link Spliterator.OfLong} covering the specified range of the
5474      * specified array.
5475      *
5476      * <p>The spliterator reports {@link Spliterator#SIZED},
5477      * {@link Spliterator#SUBSIZED}, {@link Spliterator#ORDERED}, and
5478      * {@link Spliterator#IMMUTABLE}.
5479      *
5480      * @param array the array, assumed to be unmodified during use
5481      * @param startInclusive the first index to cover, inclusive
5482      * @param endExclusive index immediately past the last index to cover
5483      * @return a spliterator for the array elements
5484      * @throws ArrayIndexOutOfBoundsException if {@code startInclusive} is
5485      *         negative, {@code endExclusive} is less than
5486      *         {@code startInclusive}, or {@code endExclusive} is greater than
5487      *         the array size
5488      * @since 1.8
5489      */
5490     public static Spliterator.OfLong spliterator(long[] array, int startInclusive, int endExclusive) {
5491         return Spliterators.spliterator(array, startInclusive, endExclusive,
5492                                         Spliterator.ORDERED | Spliterator.IMMUTABLE);
5493     }
5494 
5495     /**
5496      * Returns a {@link Spliterator.OfDouble} covering all of the specified
5497      * array.
5498      *
5499      * <p>The spliterator reports {@link Spliterator#SIZED},
5500      * {@link Spliterator#SUBSIZED}, {@link Spliterator#ORDERED}, and
5501      * {@link Spliterator#IMMUTABLE}.
5502      *
5503      * @param array the array, assumed to be unmodified during use
5504      * @return a spliterator for the array elements
5505      * @since 1.8
5506      */
5507     public static Spliterator.OfDouble spliterator(double[] array) {
5508         return Spliterators.spliterator(array,
5509                                         Spliterator.ORDERED | Spliterator.IMMUTABLE);
5510     }
5511 
5512     /**
5513      * Returns a {@link Spliterator.OfDouble} covering the specified range of
5514      * the specified array.
5515      *
5516      * <p>The spliterator reports {@link Spliterator#SIZED},
5517      * {@link Spliterator#SUBSIZED}, {@link Spliterator#ORDERED}, and
5518      * {@link Spliterator#IMMUTABLE}.
5519      *
5520      * @param array the array, assumed to be unmodified during use
5521      * @param startInclusive the first index to cover, inclusive
5522      * @param endExclusive index immediately past the last index to cover
5523      * @return a spliterator for the array elements
5524      * @throws ArrayIndexOutOfBoundsException if {@code startInclusive} is
5525      *         negative, {@code endExclusive} is less than
5526      *         {@code startInclusive}, or {@code endExclusive} is greater than
5527      *         the array size
5528      * @since 1.8
5529      */
5530     public static Spliterator.OfDouble spliterator(double[] array, int startInclusive, int endExclusive) {
5531         return Spliterators.spliterator(array, startInclusive, endExclusive,
5532                                         Spliterator.ORDERED | Spliterator.IMMUTABLE);
5533     }
5534 
5535     /**
5536      * Returns a sequential {@link Stream} with the specified array as its
5537      * source.
5538      *
5539      * @param <T> The type of the array elements
5540      * @param array The array, assumed to be unmodified during use
5541      * @return a {@code Stream} for the array
5542      * @since 1.8
5543      */
5544     public static <T> Stream<T> stream(T[] array) {
5545         return stream(array, 0, array.length);
5546     }
5547 
5548     /**
5549      * Returns a sequential {@link Stream} with the specified range of the
5550      * specified array as its source.
5551      *
5552      * @param <T> the type of the array elements
5553      * @param array the array, assumed to be unmodified during use
5554      * @param startInclusive the first index to cover, inclusive
5555      * @param endExclusive index immediately past the last index to cover
5556      * @return a {@code Stream} for the array range
5557      * @throws ArrayIndexOutOfBoundsException if {@code startInclusive} is
5558      *         negative, {@code endExclusive} is less than
5559      *         {@code startInclusive}, or {@code endExclusive} is greater than
5560      *         the array size
5561      * @since 1.8
5562      */
5563     public static <T> Stream<T> stream(T[] array, int startInclusive, int endExclusive) {
5564         return StreamSupport.stream(spliterator(array, startInclusive, endExclusive), false);
5565     }
5566 
5567     /**
5568      * Returns a sequential {@link IntStream} with the specified array as its
5569      * source.
5570      *
5571      * @param array the array, assumed to be unmodified during use
5572      * @return an {@code IntStream} for the array
5573      * @since 1.8
5574      */
5575     public static IntStream stream(int[] array) {
5576         return stream(array, 0, array.length);
5577     }
5578 
5579     /**
5580      * Returns a sequential {@link IntStream} with the specified range of the
5581      * specified array as its source.
5582      *
5583      * @param array the array, assumed to be unmodified during use
5584      * @param startInclusive the first index to cover, inclusive
5585      * @param endExclusive index immediately past the last index to cover
5586      * @return an {@code IntStream} for the array range
5587      * @throws ArrayIndexOutOfBoundsException if {@code startInclusive} is
5588      *         negative, {@code endExclusive} is less than
5589      *         {@code startInclusive}, or {@code endExclusive} is greater than
5590      *         the array size
5591      * @since 1.8
5592      */
5593     public static IntStream stream(int[] array, int startInclusive, int endExclusive) {
5594         return StreamSupport.intStream(spliterator(array, startInclusive, endExclusive), false);
5595     }
5596 
5597     /**
5598      * Returns a sequential {@link LongStream} with the specified array as its
5599      * source.
5600      *
5601      * @param array the array, assumed to be unmodified during use
5602      * @return a {@code LongStream} for the array
5603      * @since 1.8
5604      */
5605     public static LongStream stream(long[] array) {
5606         return stream(array, 0, array.length);
5607     }
5608 
5609     /**
5610      * Returns a sequential {@link LongStream} with the specified range of the
5611      * specified array as its source.
5612      *
5613      * @param array the array, assumed to be unmodified during use
5614      * @param startInclusive the first index to cover, inclusive
5615      * @param endExclusive index immediately past the last index to cover
5616      * @return a {@code LongStream} for the array range
5617      * @throws ArrayIndexOutOfBoundsException if {@code startInclusive} is
5618      *         negative, {@code endExclusive} is less than
5619      *         {@code startInclusive}, or {@code endExclusive} is greater than
5620      *         the array size
5621      * @since 1.8
5622      */
5623     public static LongStream stream(long[] array, int startInclusive, int endExclusive) {
5624         return StreamSupport.longStream(spliterator(array, startInclusive, endExclusive), false);
5625     }
5626 
5627     /**
5628      * Returns a sequential {@link DoubleStream} with the specified array as its
5629      * source.
5630      *
5631      * @param array the array, assumed to be unmodified during use
5632      * @return a {@code DoubleStream} for the array
5633      * @since 1.8
5634      */
5635     public static DoubleStream stream(double[] array) {
5636         return stream(array, 0, array.length);
5637     }
5638 
5639     /**
5640      * Returns a sequential {@link DoubleStream} with the specified range of the
5641      * specified array as its source.
5642      *
5643      * @param array the array, assumed to be unmodified during use
5644      * @param startInclusive the first index to cover, inclusive
5645      * @param endExclusive index immediately past the last index to cover
5646      * @return a {@code DoubleStream} for the array range
5647      * @throws ArrayIndexOutOfBoundsException if {@code startInclusive} is
5648      *         negative, {@code endExclusive} is less than
5649      *         {@code startInclusive}, or {@code endExclusive} is greater than
5650      *         the array size
5651      * @since 1.8
5652      */
5653     public static DoubleStream stream(double[] array, int startInclusive, int endExclusive) {
5654         return StreamSupport.doubleStream(spliterator(array, startInclusive, endExclusive), false);
5655     }
5656 
5657 
5658     // Comparison methods
5659 
5660     // Compare boolean
5661 
5662     /**
5663      * Compares two {@code boolean} arrays lexicographically.
5664      *
5665      * <p>If the two arrays share a common prefix then the lexicographic
5666      * comparison is the result of comparing two elements, as if by
5667      * {@link Boolean#compare(boolean, boolean)}, at an index within the
5668      * respective arrays that is the prefix length.
5669      * Otherwise, one array is a proper prefix of the other and, lexicographic
5670      * comparison is the result of comparing the two array lengths.
5671      * (See {@link #mismatch(boolean[], boolean[])} for the definition of a
5672      * common and proper prefix.)
5673      *
5674      * <p>A {@code null} array reference is considered lexicographically less
5675      * than a non-{@code null} array reference.  Two {@code null} array
5676      * references are considered equal.
5677      *
5678      * <p>The comparison is consistent with {@link #equals(boolean[], boolean[]) equals},
5679      * more specifically the following holds for arrays {@code a} and {@code b}:
5680      * <pre>{@code
5681      *     Arrays.equals(a, b) == (Arrays.compare(a, b) == 0)
5682      * }</pre>
5683      *
5684      * @apiNote
5685      * <p>This method behaves as if (for non-{@code null} array references):
5686      * <pre>{@code
5687      *     int i = Arrays.mismatch(a, b);
5688      *     if (i >= 0 && i < Math.min(a.length, b.length))
5689      *         return Boolean.compare(a[i], b[i]);
5690      *     return a.length - b.length;
5691      * }</pre>
5692      *
5693      * @param a the first array to compare
5694      * @param b the second array to compare
5695      * @return the value {@code 0} if the first and second array are equal and
5696      *         contain the same elements in the same order;
5697      *         a value less than {@code 0} if the first array is
5698      *         lexicographically less than the second array; and
5699      *         a value greater than {@code 0} if the first array is
5700      *         lexicographically greater than the second array
5701      * @since 9
5702      */
5703     public static int compare(boolean[] a, boolean[] b) {
5704         if (a == b)
5705             return 0;
5706         if (a == null || b == null)
5707             return a == null ? -1 : 1;
5708 
5709         int length = Math.min(a.length, b.length);
5710         for (int i = 0; i < length; i++) {
5711             if (a[i] != b[i]) return Boolean.compare(a[i], b[i]);
5712         }
5713 
5714         return a.length - b.length;
5715     }
5716 
5717     /**
5718      * Compares two {@code boolean} arrays lexicographically over the specified
5719      * ranges.
5720      *
5721      * <p>If the two arrays, over the specified ranges, share a common prefix
5722      * then the lexicographic comparison is the result of comparing two
5723      * elements, as if by {@link Boolean#compare(boolean, boolean)}, at a
5724      * relative index within the respective arrays that is the length of the
5725      * prefix.
5726      * Otherwise, one array is a proper prefix of the other and, lexicographic
5727      * comparison is the result of comparing the two range lengths.
5728      * (See {@link #mismatch(boolean[], int, int, boolean[], int, int)} for the
5729      * definition of a common and proper prefix.)
5730      *
5731      * <p>The comparison is consistent with
5732      * {@link #equals(boolean[], int, int, boolean[], int, int) equals}, more
5733      * specifically the following holds for arrays {@code a} and {@code b} with
5734      * specified ranges [{@code aFromIndex}, {@code atoIndex}) and
5735      * [{@code bFromIndex}, {@code btoIndex}) respectively:
5736      * <pre>{@code
5737      *     Arrays.equals(a, aFromIndex, aToIndex, b, bFromIndex, bToIndex) ==
5738      *         (Arrays.compare(a, aFromIndex, aToIndex, b, bFromIndex, bToIndex) == 0)
5739      * }</pre>
5740      *
5741      * @apiNote
5742      * <p>This method behaves as if:
5743      * <pre>{@code
5744      *     int i = Arrays.mismatch(a, aFromIndex, aToIndex,
5745      *                             b, bFromIndex, bToIndex);
5746      *     if (i >= 0 && i < Math.min(aToIndex - aFromIndex, bToIndex - bFromIndex))
5747      *         return Boolean.compare(a[aFromIndex + i], b[bFromIndex + i]);
5748      *     return (aToIndex - aFromIndex) - (bToIndex - bFromIndex);
5749      * }</pre>
5750      *
5751      * @param a the first array to compare
5752      * @param aFromIndex the index (inclusive) of the first element in the
5753      *                   first array to be compared
5754      * @param aToIndex the index (exclusive) of the last element in the
5755      *                 first array to be compared
5756      * @param b the second array to compare
5757      * @param bFromIndex the index (inclusive) of the first element in the
5758      *                   second array to be compared
5759      * @param bToIndex the index (exclusive) of the last element in the
5760      *                 second array to be compared
5761      * @return the value {@code 0} if, over the specified ranges, the first and
5762      *         second array are equal and contain the same elements in the same
5763      *         order;
5764      *         a value less than {@code 0} if, over the specified ranges, the
5765      *         first array is lexicographically less than the second array; and
5766      *         a value greater than {@code 0} if, over the specified ranges, the
5767      *         first array is lexicographically greater than the second array
5768      * @throws IllegalArgumentException
5769      *         if {@code aFromIndex > aToIndex} or
5770      *         if {@code bFromIndex > bToIndex}
5771      * @throws ArrayIndexOutOfBoundsException
5772      *         if {@code aFromIndex < 0 or aToIndex > a.length} or
5773      *         if {@code bFromIndex < 0 or bToIndex > b.length}
5774      * @throws NullPointerException
5775      *         if either array is {@code null}
5776      * @since 9
5777      */
5778     public static int compare(boolean[] a, int aFromIndex, int aToIndex,
5779                               boolean[] b, int bFromIndex, int bToIndex) {
5780         rangeCheck(a.length, aFromIndex, aToIndex);
5781         rangeCheck(b.length, bFromIndex, bToIndex);
5782 
5783         int aLength = aToIndex - aFromIndex;
5784         int bLength = bToIndex - bFromIndex;
5785         int length = Math.min(aLength, bLength);
5786         for (int i = 0; i < length; i++) {
5787             boolean va = a[aFromIndex++];
5788             boolean vb = b[bFromIndex++];
5789             if (va != vb) return Boolean.compare(va, vb);
5790         }
5791 
5792         return aLength - bLength;
5793     }
5794 
5795     // Compare byte
5796 
5797     /**
5798      * Compares two {@code byte} arrays lexicographically.
5799      *
5800      * <p>If the two arrays share a common prefix then the lexicographic
5801      * comparison is the result of comparing two elements, as if by
5802      * {@link Byte#compare(byte, byte)}, at an index within the respective
5803      * arrays that is the prefix length.
5804      * Otherwise, one array is a proper prefix of the other and, lexicographic
5805      * comparison is the result of comparing the two array lengths.
5806      * (See {@link #mismatch(byte[], byte[])} for the definition of a common and
5807      * proper prefix.)
5808      *
5809      * <p>A {@code null} array reference is considered lexicographically less
5810      * than a non-{@code null} array reference.  Two {@code null} array
5811      * references are considered equal.
5812      *
5813      * <p>The comparison is consistent with {@link #equals(byte[], byte[]) equals},
5814      * more specifically the following holds for arrays {@code a} and {@code b}:
5815      * <pre>{@code
5816      *     Arrays.equals(a, b) == (Arrays.compare(a, b) == 0)
5817      * }</pre>
5818      *
5819      * @apiNote
5820      * <p>This method behaves as if (for non-{@code null} array references):
5821      * <pre>{@code
5822      *     int i = Arrays.mismatch(a, b);
5823      *     if (i >= 0 && i < Math.min(a.length, b.length))
5824      *         return Byte.compare(a[i], b[i]);
5825      *     return a.length - b.length;
5826      * }</pre>
5827      *
5828      * @param a the first array to compare
5829      * @param b the second array to compare
5830      * @return the value {@code 0} if the first and second array are equal and
5831      *         contain the same elements in the same order;
5832      *         a value less than {@code 0} if the first array is
5833      *         lexicographically less than the second array; and
5834      *         a value greater than {@code 0} if the first array is
5835      *         lexicographically greater than the second array
5836      * @since 9
5837      */
5838     public static int compare(byte[] a, byte[] b) {
5839         if (a == b)
5840             return 0;
5841         if (a == null || b == null)
5842             return a == null ? -1 : 1;
5843 
5844         int length = Math.min(a.length, b.length);
5845         for (int i = 0; i < length; i++) {
5846             if (a[i] != b[i]) return Byte.compare(a[i], b[i]);
5847         }
5848 
5849         return a.length - b.length;
5850     }
5851 
5852     /**
5853      * Compares two {@code byte} arrays lexicographically over the specified
5854      * ranges.
5855      *
5856      * <p>If the two arrays, over the specified ranges, share a common prefix
5857      * then the lexicographic comparison is the result of comparing two
5858      * elements, as if by {@link Byte#compare(byte, byte)}, at a relative index
5859      * within the respective arrays that is the length of the prefix.
5860      * Otherwise, one array is a proper prefix of the other and, lexicographic
5861      * comparison is the result of comparing the two range lengths.
5862      * (See {@link #mismatch(byte[], int, int, byte[], int, int)} for the
5863      * definition of a common and proper prefix.)
5864      *
5865      * <p>The comparison is consistent with
5866      * {@link #equals(byte[], int, int, byte[], int, int) equals}, more
5867      * specifically the following holds for arrays {@code a} and {@code b} with
5868      * specified ranges [{@code aFromIndex}, {@code atoIndex}) and
5869      * [{@code bFromIndex}, {@code btoIndex}) respectively:
5870      * <pre>{@code
5871      *     Arrays.equals(a, aFromIndex, aToIndex, b, bFromIndex, bToIndex) ==
5872      *         (Arrays.compare(a, aFromIndex, aToIndex, b, bFromIndex, bToIndex) == 0)
5873      * }</pre>
5874      *
5875      * @apiNote
5876      * <p>This method behaves as if:
5877      * <pre>{@code
5878      *     int i = Arrays.mismatch(a, aFromIndex, aToIndex,
5879      *                             b, bFromIndex, bToIndex);
5880      *     if (i >= 0 && i < Math.min(aToIndex - aFromIndex, bToIndex - bFromIndex))
5881      *         return Byte.compare(a[aFromIndex + i], b[bFromIndex + i]);
5882      *     return (aToIndex - aFromIndex) - (bToIndex - bFromIndex);
5883      * }</pre>
5884      *
5885      * @param a the first array to compare
5886      * @param aFromIndex the index (inclusive) of the first element in the
5887      *                   first array to be compared
5888      * @param aToIndex the index (exclusive) of the last element in the
5889      *                 first array to be compared
5890      * @param b the second array to compare
5891      * @param bFromIndex the index (inclusive) of the first element in the
5892      *                   second array to be compared
5893      * @param bToIndex the index (exclusive) of the last element in the
5894      *                 second array to be compared
5895      * @return the value {@code 0} if, over the specified ranges, the first and
5896      *         second array are equal and contain the same elements in the same
5897      *         order;
5898      *         a value less than {@code 0} if, over the specified ranges, the
5899      *         first array is lexicographically less than the second array; and
5900      *         a value greater than {@code 0} if, over the specified ranges, the
5901      *         first array is lexicographically greater than the second array
5902      * @throws IllegalArgumentException
5903      *         if {@code aFromIndex > aToIndex} or
5904      *         if {@code bFromIndex > bToIndex}
5905      * @throws ArrayIndexOutOfBoundsException
5906      *         if {@code aFromIndex < 0 or aToIndex > a.length} or
5907      *         if {@code bFromIndex < 0 or bToIndex > b.length}
5908      * @throws NullPointerException
5909      *         if either array is {@code null}
5910      * @since 9
5911      */
5912     public static int compare(byte[] a, int aFromIndex, int aToIndex,
5913                               byte[] b, int bFromIndex, int bToIndex) {
5914         rangeCheck(a.length, aFromIndex, aToIndex);
5915         rangeCheck(b.length, bFromIndex, bToIndex);
5916 
5917         int aLength = aToIndex - aFromIndex;
5918         int bLength = bToIndex - bFromIndex;
5919         int length = Math.min(aLength, bLength);
5920         for (int i = 0; i < length; i++) {
5921             byte va = a[aFromIndex++];
5922             byte vb = b[bFromIndex++];
5923             if (va != vb) return Byte.compare(va, vb);
5924         }
5925 
5926         return aLength - bLength;
5927     }
5928 
5929     /**
5930      * Compares two {@code byte} arrays lexicographically, numerically treating
5931      * elements as unsigned.
5932      *
5933      * <p>If the two arrays share a common prefix then the lexicographic
5934      * comparison is the result of comparing two elements, as if by
5935      * {@link Byte#compareUnsigned(byte, byte)}, at an index within the
5936      * respective arrays that is the prefix length.
5937      * Otherwise, one array is a proper prefix of the other and, lexicographic
5938      * comparison is the result of comparing the two array lengths.
5939      * (See {@link #mismatch(byte[], byte[])} for the definition of a common
5940      * and proper prefix.)
5941      *
5942      * <p>A {@code null} array reference is considered lexicographically less
5943      * than a non-{@code null} array reference.  Two {@code null} array
5944      * references are considered equal.
5945      *
5946      * @apiNote
5947      * <p>This method behaves as if (for non-{@code null} array references):
5948      * <pre>{@code
5949      *     int i = Arrays.mismatch(a, b);
5950      *     if (i >= 0 && i < Math.min(a.length, b.length))
5951      *         return Byte.compareUnsigned(a[i], b[i]);
5952      *     return a.length - b.length;
5953      * }</pre>
5954      *
5955      * @param a the first array to compare
5956      * @param b the second array to compare
5957      * @return the value {@code 0} if the first and second array are
5958      *         equal and contain the same elements in the same order;
5959      *         a value less than {@code 0} if the first array is
5960      *         lexicographically less than the second array; and
5961      *         a value greater than {@code 0} if the first array is
5962      *         lexicographically greater than the second array
5963      * @since 9
5964      */
5965     public static int compareUnsigned(byte[] a, byte[] b) {
5966         if (a == b)
5967             return 0;
5968         if (a == null || b == null)
5969             return a == null ? -1 : 1;
5970 
5971         int length = Math.min(a.length, b.length);
5972         for (int i = 0; i < length; i++) {
5973             if (a[i] != b[i]) return Byte.compareUnsigned(a[i], b[i]);
5974         }
5975 
5976         return a.length - b.length;
5977     }
5978 
5979 
5980     /**
5981      * Compares two {@code byte} arrays lexicographically over the specified
5982      * ranges, numerically treating elements as unsigned.
5983      *
5984      * <p>If the two arrays, over the specified ranges, share a common prefix
5985      * then the lexicographic comparison is the result of comparing two
5986      * elements, as if by {@link Byte#compareUnsigned(byte, byte)}, at a
5987      * relative index within the respective arrays that is the length of the
5988      * prefix.
5989      * Otherwise, one array is a proper prefix of the other and, lexicographic
5990      * comparison is the result of comparing the two range lengths.
5991      * (See {@link #mismatch(byte[], int, int, byte[], int, int)} for the
5992      * definition of a common and proper prefix.)
5993      *
5994      * @apiNote
5995      * <p>This method behaves as if:
5996      * <pre>{@code
5997      *     int i = Arrays.mismatch(a, aFromIndex, aToIndex,
5998      *                             b, bFromIndex, bToIndex);
5999      *     if (i >= 0 && i < Math.min(aToIndex - aFromIndex, bToIndex - bFromIndex))
6000      *         return Byte.compareUnsigned(a[aFromIndex + i], b[bFromIndex + i]);
6001      *     return (aToIndex - aFromIndex) - (bToIndex - bFromIndex);
6002      * }</pre>
6003      *
6004      * @param a the first array to compare
6005      * @param aFromIndex the index (inclusive) of the first element in the
6006      *                   first array to be compared
6007      * @param aToIndex the index (exclusive) of the last element in the
6008      *                 first array to be compared
6009      * @param b the second array to compare
6010      * @param bFromIndex the index (inclusive) of the first element in the
6011      *                   second array to be compared
6012      * @param bToIndex the index (exclusive) of the last element in the
6013      *                 second array to be compared
6014      * @return the value {@code 0} if, over the specified ranges, the first and
6015      *         second array are equal and contain the same elements in the same
6016      *         order;
6017      *         a value less than {@code 0} if, over the specified ranges, the
6018      *         first array is lexicographically less than the second array; and
6019      *         a value greater than {@code 0} if, over the specified ranges, the
6020      *         first array is lexicographically greater than the second array
6021      * @throws IllegalArgumentException
6022      *         if {@code aFromIndex > aToIndex} or
6023      *         if {@code bFromIndex > bToIndex}
6024      * @throws ArrayIndexOutOfBoundsException
6025      *         if {@code aFromIndex < 0 or aToIndex > a.length} or
6026      *         if {@code bFromIndex < 0 or bToIndex > b.length}
6027      * @throws NullPointerException
6028      *         if either array is null
6029      * @since 9
6030      */
6031     public static int compareUnsigned(byte[] a, int aFromIndex, int aToIndex,
6032                                       byte[] b, int bFromIndex, int bToIndex) {
6033         rangeCheck(a.length, aFromIndex, aToIndex);
6034         rangeCheck(b.length, bFromIndex, bToIndex);
6035 
6036         int aLength = aToIndex - aFromIndex;
6037         int bLength = bToIndex - bFromIndex;
6038         int length = Math.min(aLength, bLength);
6039         for (int i = 0; i < length; i++) {
6040             byte va = a[aFromIndex++];
6041             byte vb = b[bFromIndex++];
6042             if (va != vb) return Byte.compareUnsigned(va, vb);
6043         }
6044 
6045         return aLength - bLength;
6046     }
6047 
6048     // Compare short
6049 
6050     /**
6051      * Compares two {@code short} arrays lexicographically.
6052      *
6053      * <p>If the two arrays share a common prefix then the lexicographic
6054      * comparison is the result of comparing two elements, as if by
6055      * {@link Short#compare(short, short)}, at an index within the respective
6056      * arrays that is the prefix length.
6057      * Otherwise, one array is a proper prefix of the other and, lexicographic
6058      * comparison is the result of comparing the two array lengths.
6059      * (See {@link #mismatch(short[], short[])} for the definition of a common
6060      * and proper prefix.)
6061      *
6062      * <p>A {@code null} array reference is considered lexicographically less
6063      * than a non-{@code null} array reference.  Two {@code null} array
6064      * references are considered equal.
6065      *
6066      * <p>The comparison is consistent with {@link #equals(short[], short[]) equals},
6067      * more specifically the following holds for arrays {@code a} and {@code b}:
6068      * <pre>{@code
6069      *     Arrays.equals(a, b) == (Arrays.compare(a, b) == 0)
6070      * }</pre>
6071      *
6072      * @apiNote
6073      * <p>This method behaves as if (for non-{@code null} array references):
6074      * <pre>{@code
6075      *     int i = Arrays.mismatch(a, b);
6076      *     if (i >= 0 && i < Math.min(a.length, b.length))
6077      *         return Short.compare(a[i], b[i]);
6078      *     return a.length - b.length;
6079      * }</pre>
6080      *
6081      * @param a the first array to compare
6082      * @param b the second array to compare
6083      * @return the value {@code 0} if the first and second array are equal and
6084      *         contain the same elements in the same order;
6085      *         a value less than {@code 0} if the first array is
6086      *         lexicographically less than the second array; and
6087      *         a value greater than {@code 0} if the first array is
6088      *         lexicographically greater than the second array
6089      * @since 9
6090      */
6091     public static int compare(short[] a, short[] b) {
6092         if (a == b)
6093             return 0;
6094         if (a == null || b == null)
6095             return a == null ? -1 : 1;
6096 
6097         int length = Math.min(a.length, b.length);
6098         for (int i = 0; i < length; i++) {
6099             if (a[i] != b[i]) return Short.compare(a[i], b[i]);
6100         }
6101 
6102         return a.length - b.length;
6103     }
6104 
6105     /**
6106      * Compares two {@code short} arrays lexicographically over the specified
6107      * ranges.
6108      *
6109      * <p>If the two arrays, over the specified ranges, share a common prefix
6110      * then the lexicographic comparison is the result of comparing two
6111      * elements, as if by {@link Short#compare(short, short)}, at a relative
6112      * index within the respective arrays that is the length of the prefix.
6113      * Otherwise, one array is a proper prefix of the other and, lexicographic
6114      * comparison is the result of comparing the two range lengths.
6115      * (See {@link #mismatch(short[], int, int, short[], int, int)} for the
6116      * definition of a common and proper prefix.)
6117      *
6118      * <p>The comparison is consistent with
6119      * {@link #equals(short[], int, int, short[], int, int) equals}, more
6120      * specifically the following holds for arrays {@code a} and {@code b} with
6121      * specified ranges [{@code aFromIndex}, {@code atoIndex}) and
6122      * [{@code bFromIndex}, {@code btoIndex}) respectively:
6123      * <pre>{@code
6124      *     Arrays.equals(a, aFromIndex, aToIndex, b, bFromIndex, bToIndex) ==
6125      *         (Arrays.compare(a, aFromIndex, aToIndex, b, bFromIndex, bToIndex) == 0)
6126      * }</pre>
6127      *
6128      * @apiNote
6129      * <p>This method behaves as if:
6130      * <pre>{@code
6131      *     int i = Arrays.mismatch(a, aFromIndex, aToIndex,
6132      *                             b, bFromIndex, bToIndex);
6133      *     if (i >= 0 && i < Math.min(aToIndex - aFromIndex, bToIndex - bFromIndex))
6134      *         return Short.compare(a[aFromIndex + i], b[bFromIndex + i]);
6135      *     return (aToIndex - aFromIndex) - (bToIndex - bFromIndex);
6136      * }</pre>
6137      *
6138      * @param a the first array to compare
6139      * @param aFromIndex the index (inclusive) of the first element in the
6140      *                   first array to be compared
6141      * @param aToIndex the index (exclusive) of the last element in the
6142      *                 first array to be compared
6143      * @param b the second array to compare
6144      * @param bFromIndex the index (inclusive) of the first element in the
6145      *                   second array to be compared
6146      * @param bToIndex the index (exclusive) of the last element in the
6147      *                 second array to be compared
6148      * @return the value {@code 0} if, over the specified ranges, the first and
6149      *         second array are equal and contain the same elements in the same
6150      *         order;
6151      *         a value less than {@code 0} if, over the specified ranges, the
6152      *         first array is lexicographically less than the second array; and
6153      *         a value greater than {@code 0} if, over the specified ranges, the
6154      *         first array is lexicographically greater than the second array
6155      * @throws IllegalArgumentException
6156      *         if {@code aFromIndex > aToIndex} or
6157      *         if {@code bFromIndex > bToIndex}
6158      * @throws ArrayIndexOutOfBoundsException
6159      *         if {@code aFromIndex < 0 or aToIndex > a.length} or
6160      *         if {@code bFromIndex < 0 or bToIndex > b.length}
6161      * @throws NullPointerException
6162      *         if either array is {@code null}
6163      * @since 9
6164      */
6165     public static int compare(short[] a, int aFromIndex, int aToIndex,
6166                               short[] b, int bFromIndex, int bToIndex) {
6167         rangeCheck(a.length, aFromIndex, aToIndex);
6168         rangeCheck(b.length, bFromIndex, bToIndex);
6169 
6170         int aLength = aToIndex - aFromIndex;
6171         int bLength = bToIndex - bFromIndex;
6172         int length = Math.min(aLength, bLength);
6173         for (int i = 0; i < length; i++) {
6174             short va = a[aFromIndex++];
6175             short vb = b[bFromIndex++];
6176             if (va != vb) return Short.compare(va, vb);
6177         }
6178 
6179         return aLength - bLength;
6180     }
6181 
6182     /**
6183      * Compares two {@code short} arrays lexicographically, numerically treating
6184      * elements as unsigned.
6185      *
6186      * <p>If the two arrays share a common prefix then the lexicographic
6187      * comparison is the result of comparing two elements, as if by
6188      * {@link Short#compareUnsigned(short, short)}, at an index within the
6189      * respective arrays that is the prefix length.
6190      * Otherwise, one array is a proper prefix of the other and, lexicographic
6191      * comparison is the result of comparing the two array lengths.
6192      * (See {@link #mismatch(short[], short[])} for the definition of a common
6193      * and proper prefix.)
6194      *
6195      * <p>A {@code null} array reference is considered lexicographically less
6196      * than a non-{@code null} array reference.  Two {@code null} array
6197      * references are considered equal.
6198      *
6199      * @apiNote
6200      * <p>This method behaves as if (for non-{@code null} array references):
6201      * <pre>{@code
6202      *     int i = Arrays.mismatch(a, b);
6203      *     if (i >= 0 && i < Math.min(a.length, b.length))
6204      *         return Short.compareUnsigned(a[i], b[i]);
6205      *     return a.length - b.length;
6206      * }</pre>
6207      *
6208      * @param a the first array to compare
6209      * @param b the second array to compare
6210      * @return the value {@code 0} if the first and second array are
6211      *         equal and contain the same elements in the same order;
6212      *         a value less than {@code 0} if the first array is
6213      *         lexicographically less than the second array; and
6214      *         a value greater than {@code 0} if the first array is
6215      *         lexicographically greater than the second array
6216      * @since 9
6217      */
6218     public static int compareUnsigned(short[] a, short[] b) {
6219         if (a == b)
6220             return 0;
6221         if (a == null || b == null)
6222             return a == null ? -1 : 1;
6223 
6224         int length = Math.min(a.length, b.length);
6225         for (int i = 0; i < length; i++) {
6226             if (a[i] != b[i]) return Short.compareUnsigned(a[i], b[i]);
6227         }
6228 
6229         return a.length - b.length;
6230     }
6231 
6232     /**
6233      * Compares two {@code short} arrays lexicographically over the specified
6234      * ranges, numerically treating elements as unsigned.
6235      *
6236      * <p>If the two arrays, over the specified ranges, share a common prefix
6237      * then the lexicographic comparison is the result of comparing two
6238      * elements, as if by {@link Short#compareUnsigned(short, short)}, at a
6239      * relative index within the respective arrays that is the length of the
6240      * prefix.
6241      * Otherwise, one array is a proper prefix of the other and, lexicographic
6242      * comparison is the result of comparing the two range lengths.
6243      * (See {@link #mismatch(short[], int, int, short[], int, int)} for the
6244      * definition of a common and proper prefix.)
6245      *
6246      * @apiNote
6247      * <p>This method behaves as if:
6248      * <pre>{@code
6249      *     int i = Arrays.mismatch(a, aFromIndex, aToIndex,
6250      *                             b, bFromIndex, bToIndex);
6251      *     if (i >= 0 && i < Math.min(aToIndex - aFromIndex, bToIndex - bFromIndex))
6252      *         return Short.compareUnsigned(a[aFromIndex + i], b[bFromIndex + i]);
6253      *     return (aToIndex - aFromIndex) - (bToIndex - bFromIndex);
6254      * }</pre>
6255      *
6256      * @param a the first array to compare
6257      * @param aFromIndex the index (inclusive) of the first element in the
6258      *                   first array to be compared
6259      * @param aToIndex the index (exclusive) of the last element in the
6260      *                 first array to be compared
6261      * @param b the second array to compare
6262      * @param bFromIndex the index (inclusive) of the first element in the
6263      *                   second array to be compared
6264      * @param bToIndex the index (exclusive) of the last element in the
6265      *                 second array to be compared
6266      * @return the value {@code 0} if, over the specified ranges, the first and
6267      *         second array are equal and contain the same elements in the same
6268      *         order;
6269      *         a value less than {@code 0} if, over the specified ranges, the
6270      *         first array is lexicographically less than the second array; and
6271      *         a value greater than {@code 0} if, over the specified ranges, the
6272      *         first array is lexicographically greater than the second array
6273      * @throws IllegalArgumentException
6274      *         if {@code aFromIndex > aToIndex} or
6275      *         if {@code bFromIndex > bToIndex}
6276      * @throws ArrayIndexOutOfBoundsException
6277      *         if {@code aFromIndex < 0 or aToIndex > a.length} or
6278      *         if {@code bFromIndex < 0 or bToIndex > b.length}
6279      * @throws NullPointerException
6280      *         if either array is null
6281      * @since 9
6282      */
6283     public static int compareUnsigned(short[] a, int aFromIndex, int aToIndex,
6284                                       short[] b, int bFromIndex, int bToIndex) {
6285         rangeCheck(a.length, aFromIndex, aToIndex);
6286         rangeCheck(b.length, bFromIndex, bToIndex);
6287 
6288         int aLength = aToIndex - aFromIndex;
6289         int bLength = bToIndex - bFromIndex;
6290         int length = Math.min(aLength, bLength);
6291         for (int i = 0; i < length; i++) {
6292             short va = a[aFromIndex++];
6293             short vb = b[bFromIndex++];
6294             if (va != vb) return Short.compareUnsigned(va, vb);
6295         }
6296 
6297         return aLength - bLength;
6298     }
6299 
6300     // Compare char
6301 
6302     /**
6303      * Compares two {@code char} arrays lexicographically.
6304      *
6305      * <p>If the two arrays share a common prefix then the lexicographic
6306      * comparison is the result of comparing two elements, as if by
6307      * {@link Character#compare(char, char)}, at an index within the respective
6308      * arrays that is the prefix length.
6309      * Otherwise, one array is a proper prefix of the other and, lexicographic
6310      * comparison is the result of comparing the two array lengths.
6311      * (See {@link #mismatch(char[], char[])} for the definition of a common and
6312      * proper prefix.)
6313      *
6314      * <p>A {@code null} array reference is considered lexicographically less
6315      * than a non-{@code null} array reference.  Two {@code null} array
6316      * references are considered equal.
6317      *
6318      * <p>The comparison is consistent with {@link #equals(char[], char[]) equals},
6319      * more specifically the following holds for arrays {@code a} and {@code b}:
6320      * <pre>{@code
6321      *     Arrays.equals(a, b) == (Arrays.compare(a, b) == 0)
6322      * }</pre>
6323      *
6324      * @apiNote
6325      * <p>This method behaves as if (for non-{@code null} array references):
6326      * <pre>{@code
6327      *     int i = Arrays.mismatch(a, b);
6328      *     if (i >= 0 && i < Math.min(a.length, b.length))
6329      *         return Character.compare(a[i], b[i]);
6330      *     return a.length - b.length;
6331      * }</pre>
6332      *
6333      * @param a the first array to compare
6334      * @param b the second array to compare
6335      * @return the value {@code 0} if the first and second array are equal and
6336      *         contain the same elements in the same order;
6337      *         a value less than {@code 0} if the first array is
6338      *         lexicographically less than the second array; and
6339      *         a value greater than {@code 0} if the first array is
6340      *         lexicographically greater than the second array
6341      * @since 9
6342      */
6343     public static int compare(char[] a, char[] b) {
6344         if (a == b)
6345             return 0;
6346         if (a == null || b == null)
6347             return a == null ? -1 : 1;
6348 
6349         int length = Math.min(a.length, b.length);
6350         for (int i = 0; i < length; i++) {
6351             if (a[i] != b[i]) return Character.compare(a[i], b[i]);
6352         }
6353 
6354         return a.length - b.length;
6355     }
6356 
6357     /**
6358      * Compares two {@code char} arrays lexicographically over the specified
6359      * ranges.
6360      *
6361      * <p>If the two arrays, over the specified ranges, share a common prefix
6362      * then the lexicographic comparison is the result of comparing two
6363      * elements, as if by {@link Character#compare(char, char)}, at a relative
6364      * index within the respective arrays that is the length of the prefix.
6365      * Otherwise, one array is a proper prefix of the other and, lexicographic
6366      * comparison is the result of comparing the two range lengths.
6367      * (See {@link #mismatch(char[], int, int, char[], int, int)} for the
6368      * definition of a common and proper prefix.)
6369      *
6370      * <p>The comparison is consistent with
6371      * {@link #equals(char[], int, int, char[], int, int) equals}, more
6372      * specifically the following holds for arrays {@code a} and {@code b} with
6373      * specified ranges [{@code aFromIndex}, {@code atoIndex}) and
6374      * [{@code bFromIndex}, {@code btoIndex}) respectively:
6375      * <pre>{@code
6376      *     Arrays.equals(a, aFromIndex, aToIndex, b, bFromIndex, bToIndex) ==
6377      *         (Arrays.compare(a, aFromIndex, aToIndex, b, bFromIndex, bToIndex) == 0)
6378      * }</pre>
6379      *
6380      * @apiNote
6381      * <p>This method behaves as if:
6382      * <pre>{@code
6383      *     int i = Arrays.mismatch(a, aFromIndex, aToIndex,
6384      *                             b, bFromIndex, bToIndex);
6385      *     if (i >= 0 && i < Math.min(aToIndex - aFromIndex, bToIndex - bFromIndex))
6386      *         return Character.compare(a[aFromIndex + i], b[bFromIndex + i]);
6387      *     return (aToIndex - aFromIndex) - (bToIndex - bFromIndex);
6388      * }</pre>
6389      *
6390      * @param a the first array to compare
6391      * @param aFromIndex the index (inclusive) of the first element in the
6392      *                   first array to be compared
6393      * @param aToIndex the index (exclusive) of the last element in the
6394      *                 first array to be compared
6395      * @param b the second array to compare
6396      * @param bFromIndex the index (inclusive) of the first element in the
6397      *                   second array to be compared
6398      * @param bToIndex the index (exclusive) of the last element in the
6399      *                 second array to be compared
6400      * @return the value {@code 0} if, over the specified ranges, the first and
6401      *         second array are equal and contain the same elements in the same
6402      *         order;
6403      *         a value less than {@code 0} if, over the specified ranges, the
6404      *         first array is lexicographically less than the second array; and
6405      *         a value greater than {@code 0} if, over the specified ranges, the
6406      *         first array is lexicographically greater than the second array
6407      * @throws IllegalArgumentException
6408      *         if {@code aFromIndex > aToIndex} or
6409      *         if {@code bFromIndex > bToIndex}
6410      * @throws ArrayIndexOutOfBoundsException
6411      *         if {@code aFromIndex < 0 or aToIndex > a.length} or
6412      *         if {@code bFromIndex < 0 or bToIndex > b.length}
6413      * @throws NullPointerException
6414      *         if either array is {@code null}
6415      * @since 9
6416      */
6417     public static int compare(char[] a, int aFromIndex, int aToIndex,
6418                               char[] b, int bFromIndex, int bToIndex) {
6419         rangeCheck(a.length, aFromIndex, aToIndex);
6420         rangeCheck(b.length, bFromIndex, bToIndex);
6421 
6422         int aLength = aToIndex - aFromIndex;
6423         int bLength = bToIndex - bFromIndex;
6424         int length = Math.min(aLength, bLength);
6425         for (int i = 0; i < length; i++) {
6426             char va = a[aFromIndex++];
6427             char vb = b[bFromIndex++];
6428             if (va != vb) return Character.compare(va, vb);
6429         }
6430 
6431         return aLength - bLength;
6432     }
6433 
6434     // Compare int
6435 
6436     /**
6437      * Compares two {@code int} arrays lexicographically.
6438      *
6439      * <p>If the two arrays share a common prefix then the lexicographic
6440      * comparison is the result of comparing two elements, as if by
6441      * {@link Integer#compare(int, int)}, at an index within the respective
6442      * arrays that is the prefix length.
6443      * Otherwise, one array is a proper prefix of the other and, lexicographic
6444      * comparison is the result of comparing the two array lengths.
6445      * (See {@link #mismatch(int[], int[])} for the definition of a common and
6446      * proper prefix.)
6447      *
6448      * <p>A {@code null} array reference is considered lexicographically less
6449      * than a non-{@code null} array reference.  Two {@code null} array
6450      * references are considered equal.
6451      *
6452      * <p>The comparison is consistent with {@link #equals(int[], int[]) equals},
6453      * more specifically the following holds for arrays {@code a} and {@code b}:
6454      * <pre>{@code
6455      *     Arrays.equals(a, b) == (Arrays.compare(a, b) == 0)
6456      * }</pre>
6457      *
6458      * @apiNote
6459      * <p>This method behaves as if (for non-{@code null} array references):
6460      * <pre>{@code
6461      *     int i = Arrays.mismatch(a, b);
6462      *     if (i >= 0 && i < Math.min(a.length, b.length))
6463      *         return Integer.compare(a[i], b[i]);
6464      *     return a.length - b.length;
6465      * }</pre>
6466      *
6467      * @param a the first array to compare
6468      * @param b the second array to compare
6469      * @return the value {@code 0} if the first and second array are equal and
6470      *         contain the same elements in the same order;
6471      *         a value less than {@code 0} if the first array is
6472      *         lexicographically less than the second array; and
6473      *         a value greater than {@code 0} if the first array is
6474      *         lexicographically greater than the second array
6475      * @since 9
6476      */
6477     public static int compare(int[] a, int[] b) {
6478         if (a == b)
6479             return 0;
6480         if (a == null || b == null)
6481             return a == null ? -1 : 1;
6482 
6483         int length = Math.min(a.length, b.length);
6484         for (int i = 0; i < length; i++) {
6485             if (a[i] != b[i]) return Integer.compare(a[i], b[i]);
6486         }
6487 
6488         return a.length - b.length;
6489     }
6490 
6491     /**
6492      * Compares two {@code int} arrays lexicographically over the specified
6493      * ranges.
6494      *
6495      * <p>If the two arrays, over the specified ranges, share a common prefix
6496      * then the lexicographic comparison is the result of comparing two
6497      * elements, as if by {@link Integer#compare(int, int)}, at a relative index
6498      * within the respective arrays that is the length of the prefix.
6499      * Otherwise, one array is a proper prefix of the other and, lexicographic
6500      * comparison is the result of comparing the two range lengths.
6501      * (See {@link #mismatch(int[], int, int, int[], int, int)} for the
6502      * definition of a common and proper prefix.)
6503      *
6504      * <p>The comparison is consistent with
6505      * {@link #equals(int[], int, int, int[], int, int) equals}, more
6506      * specifically the following holds for arrays {@code a} and {@code b} with
6507      * specified ranges [{@code aFromIndex}, {@code atoIndex}) and
6508      * [{@code bFromIndex}, {@code btoIndex}) respectively:
6509      * <pre>{@code
6510      *     Arrays.equals(a, aFromIndex, aToIndex, b, bFromIndex, bToIndex) ==
6511      *         (Arrays.compare(a, aFromIndex, aToIndex, b, bFromIndex, bToIndex) == 0)
6512      * }</pre>
6513      *
6514      * @apiNote
6515      * <p>This method behaves as if:
6516      * <pre>{@code
6517      *     int i = Arrays.mismatch(a, aFromIndex, aToIndex,
6518      *                             b, bFromIndex, bToIndex);
6519      *     if (i >= 0 && i < Math.min(aToIndex - aFromIndex, bToIndex - bFromIndex))
6520      *         return Integer.compare(a[aFromIndex + i], b[bFromIndex + i]);
6521      *     return (aToIndex - aFromIndex) - (bToIndex - bFromIndex);
6522      * }</pre>
6523      *
6524      * @param a the first array to compare
6525      * @param aFromIndex the index (inclusive) of the first element in the
6526      *                   first array to be compared
6527      * @param aToIndex the index (exclusive) of the last element in the
6528      *                 first array to be compared
6529      * @param b the second array to compare
6530      * @param bFromIndex the index (inclusive) of the first element in the
6531      *                   second array to be compared
6532      * @param bToIndex the index (exclusive) of the last element in the
6533      *                 second array to be compared
6534      * @return the value {@code 0} if, over the specified ranges, the first and
6535      *         second array are equal and contain the same elements in the same
6536      *         order;
6537      *         a value less than {@code 0} if, over the specified ranges, the
6538      *         first array is lexicographically less than the second array; and
6539      *         a value greater than {@code 0} if, over the specified ranges, the
6540      *         first array is lexicographically greater than the second array
6541      * @throws IllegalArgumentException
6542      *         if {@code aFromIndex > aToIndex} or
6543      *         if {@code bFromIndex > bToIndex}
6544      * @throws ArrayIndexOutOfBoundsException
6545      *         if {@code aFromIndex < 0 or aToIndex > a.length} or
6546      *         if {@code bFromIndex < 0 or bToIndex > b.length}
6547      * @throws NullPointerException
6548      *         if either array is {@code null}
6549      * @since 9
6550      */
6551     public static int compare(int[] a, int aFromIndex, int aToIndex,
6552                               int[] b, int bFromIndex, int bToIndex) {
6553         rangeCheck(a.length, aFromIndex, aToIndex);
6554         rangeCheck(b.length, bFromIndex, bToIndex);
6555 
6556         int aLength = aToIndex - aFromIndex;
6557         int bLength = bToIndex - bFromIndex;
6558         int length = Math.min(aLength, bLength);
6559         for (int i = 0; i < length; i++) {
6560             int va = a[aFromIndex++];
6561             int vb = b[bFromIndex++];
6562             if (va != vb) return Integer.compare(va, vb);
6563         }
6564 
6565         return aLength - bLength;
6566     }
6567 
6568     /**
6569      * Compares two {@code int} arrays lexicographically, numerically treating
6570      * elements as unsigned.
6571      *
6572      * <p>If the two arrays share a common prefix then the lexicographic
6573      * comparison is the result of comparing two elements, as if by
6574      * {@link Integer#compareUnsigned(int, int)}, at an index within the
6575      * respective arrays that is the prefix length.
6576      * Otherwise, one array is a proper prefix of the other and, lexicographic
6577      * comparison is the result of comparing the two array lengths.
6578      * (See {@link #mismatch(int[], int[])} for the definition of a common
6579      * and proper prefix.)
6580      *
6581      * <p>A {@code null} array reference is considered lexicographically less
6582      * than a non-{@code null} array reference.  Two {@code null} array
6583      * references are considered equal.
6584      *
6585      * @apiNote
6586      * <p>This method behaves as if (for non-{@code null} array references):
6587      * <pre>{@code
6588      *     int i = Arrays.mismatch(a, b);
6589      *     if (i >= 0 && i < Math.min(a.length, b.length))
6590      *         return Integer.compareUnsigned(a[i], b[i]);
6591      *     return a.length - b.length;
6592      * }</pre>
6593      *
6594      * @param a the first array to compare
6595      * @param b the second array to compare
6596      * @return the value {@code 0} if the first and second array are
6597      *         equal and contain the same elements in the same order;
6598      *         a value less than {@code 0} if the first array is
6599      *         lexicographically less than the second array; and
6600      *         a value greater than {@code 0} if the first array is
6601      *         lexicographically greater than the second array
6602      * @since 9
6603      */
6604     public static int compareUnsigned(int[] a, int[] b) {
6605         if (a == b)
6606             return 0;
6607         if (a == null || b == null)
6608             return a == null ? -1 : 1;
6609 
6610         int length = Math.min(a.length, b.length);
6611         for (int i = 0; i < length; i++) {
6612             if (a[i] != b[i]) return Integer.compareUnsigned(a[i], b[i]);
6613         }
6614 
6615         return a.length - b.length;
6616     }
6617 
6618     /**
6619      * Compares two {@code int} arrays lexicographically over the specified
6620      * ranges, numerically treating elements as unsigned.
6621      *
6622      * <p>If the two arrays, over the specified ranges, share a common prefix
6623      * then the lexicographic comparison is the result of comparing two
6624      * elements, as if by {@link Integer#compareUnsigned(int, int)}, at a
6625      * relative index within the respective arrays that is the length of the
6626      * prefix.
6627      * Otherwise, one array is a proper prefix of the other and, lexicographic
6628      * comparison is the result of comparing the two range lengths.
6629      * (See {@link #mismatch(int[], int, int, int[], int, int)} for the
6630      * definition of a common and proper prefix.)
6631      *
6632      * @apiNote
6633      * <p>This method behaves as if:
6634      * <pre>{@code
6635      *     int i = Arrays.mismatch(a, aFromIndex, aToIndex,
6636      *                             b, bFromIndex, bToIndex);
6637      *     if (i >= 0 && i < Math.min(aToIndex - aFromIndex, bToIndex - bFromIndex))
6638      *         return Integer.compareUnsigned(a[aFromIndex + i], b[bFromIndex + i]);
6639      *     return (aToIndex - aFromIndex) - (bToIndex - bFromIndex);
6640      * }</pre>
6641      *
6642      * @param a the first array to compare
6643      * @param aFromIndex the index (inclusive) of the first element in the
6644      *                   first array to be compared
6645      * @param aToIndex the index (exclusive) of the last element in the
6646      *                 first array to be compared
6647      * @param b the second array to compare
6648      * @param bFromIndex the index (inclusive) of the first element in the
6649      *                   second array to be compared
6650      * @param bToIndex the index (exclusive) of the last element in the
6651      *                 second array to be compared
6652      * @return the value {@code 0} if, over the specified ranges, the first and
6653      *         second array are equal and contain the same elements in the same
6654      *         order;
6655      *         a value less than {@code 0} if, over the specified ranges, the
6656      *         first array is lexicographically less than the second array; and
6657      *         a value greater than {@code 0} if, over the specified ranges, the
6658      *         first array is lexicographically greater than the second array
6659      * @throws IllegalArgumentException
6660      *         if {@code aFromIndex > aToIndex} or
6661      *         if {@code bFromIndex > bToIndex}
6662      * @throws ArrayIndexOutOfBoundsException
6663      *         if {@code aFromIndex < 0 or aToIndex > a.length} or
6664      *         if {@code bFromIndex < 0 or bToIndex > b.length}
6665      * @throws NullPointerException
6666      *         if either array is null
6667      * @since 9
6668      */
6669     public static int compareUnsigned(int[] a, int aFromIndex, int aToIndex,
6670                                       int[] b, int bFromIndex, int bToIndex) {
6671         rangeCheck(a.length, aFromIndex, aToIndex);
6672         rangeCheck(b.length, bFromIndex, bToIndex);
6673 
6674         int aLength = aToIndex - aFromIndex;
6675         int bLength = bToIndex - bFromIndex;
6676         int length = Math.min(aLength, bLength);
6677         for (int i = 0; i < length; i++) {
6678             int va = a[aFromIndex++];
6679             int vb = b[bFromIndex++];
6680             if (va != vb) return Integer.compareUnsigned(va, vb);
6681         }
6682 
6683         return aLength - bLength;
6684     }
6685 
6686     // Compare long
6687 
6688     /**
6689      * Compares two {@code long} arrays lexicographically.
6690      *
6691      * <p>If the two arrays share a common prefix then the lexicographic
6692      * comparison is the result of comparing two elements, as if by
6693      * {@link Long#compare(long, long)}, at an index within the respective
6694      * arrays that is the prefix length.
6695      * Otherwise, one array is a proper prefix of the other and, lexicographic
6696      * comparison is the result of comparing the two array lengths.
6697      * (See {@link #mismatch(long[], long[])} for the definition of a common and
6698      * proper prefix.)
6699      *
6700      * <p>A {@code null} array reference is considered lexicographically less
6701      * than a non-{@code null} array reference.  Two {@code null} array
6702      * references are considered equal.
6703      *
6704      * <p>The comparison is consistent with {@link #equals(long[], long[]) equals},
6705      * more specifically the following holds for arrays {@code a} and {@code b}:
6706      * <pre>{@code
6707      *     Arrays.equals(a, b) == (Arrays.compare(a, b) == 0)
6708      * }</pre>
6709      *
6710      * @apiNote
6711      * <p>This method behaves as if (for non-{@code null} array references):
6712      * <pre>{@code
6713      *     int i = Arrays.mismatch(a, b);
6714      *     if (i >= 0 && i < Math.min(a.length, b.length))
6715      *         return Long.compare(a[i], b[i]);
6716      *     return a.length - b.length;
6717      * }</pre>
6718      *
6719      * @param a the first array to compare
6720      * @param b the second array to compare
6721      * @return the value {@code 0} if the first and second array are equal and
6722      *         contain the same elements in the same order;
6723      *         a value less than {@code 0} if the first array is
6724      *         lexicographically less than the second array; and
6725      *         a value greater than {@code 0} if the first array is
6726      *         lexicographically greater than the second array
6727      * @since 9
6728      */
6729     public static int compare(long[] a, long[] b) {
6730         if (a == b)
6731             return 0;
6732         if (a == null || b == null)
6733             return a == null ? -1 : 1;
6734 
6735         int length = Math.min(a.length, b.length);
6736         for (int i = 0; i < length; i++) {
6737             if (a[i] != b[i]) return Long.compare(a[i], b[i]);
6738         }
6739 
6740         return a.length - b.length;
6741     }
6742 
6743     /**
6744      * Compares two {@code long} arrays lexicographically over the specified
6745      * ranges.
6746      *
6747      * <p>If the two arrays, over the specified ranges, share a common prefix
6748      * then the lexicographic comparison is the result of comparing two
6749      * elements, as if by {@link Long#compare(long, long)}, at a relative index
6750      * within the respective arrays that is the length of the prefix.
6751      * Otherwise, one array is a proper prefix of the other and, lexicographic
6752      * comparison is the result of comparing the two range lengths.
6753      * (See {@link #mismatch(long[], int, int, long[], int, int)} for the
6754      * definition of a common and proper prefix.)
6755      *
6756      * <p>The comparison is consistent with
6757      * {@link #equals(long[], int, int, long[], int, int) equals}, more
6758      * specifically the following holds for arrays {@code a} and {@code b} with
6759      * specified ranges [{@code aFromIndex}, {@code atoIndex}) and
6760      * [{@code bFromIndex}, {@code btoIndex}) respectively:
6761      * <pre>{@code
6762      *     Arrays.equals(a, aFromIndex, aToIndex, b, bFromIndex, bToIndex) ==
6763      *         (Arrays.compare(a, aFromIndex, aToIndex, b, bFromIndex, bToIndex) == 0)
6764      * }</pre>
6765      *
6766      * @apiNote
6767      * <p>This method behaves as if:
6768      * <pre>{@code
6769      *     int i = Arrays.mismatch(a, aFromIndex, aToIndex,
6770      *                             b, bFromIndex, bToIndex);
6771      *     if (i >= 0 && i < Math.min(aToIndex - aFromIndex, bToIndex - bFromIndex))
6772      *         return Long.compare(a[aFromIndex + i], b[bFromIndex + i]);
6773      *     return (aToIndex - aFromIndex) - (bToIndex - bFromIndex);
6774      * }</pre>
6775      *
6776      * @param a the first array to compare
6777      * @param aFromIndex the index (inclusive) of the first element in the
6778      *                   first array to be compared
6779      * @param aToIndex the index (exclusive) of the last element in the
6780      *                 first array to be compared
6781      * @param b the second array to compare
6782      * @param bFromIndex the index (inclusive) of the first element in the
6783      *                   second array to be compared
6784      * @param bToIndex the index (exclusive) of the last element in the
6785      *                 second array to be compared
6786      * @return the value {@code 0} if, over the specified ranges, the first and
6787      *         second array are equal and contain the same elements in the same
6788      *         order;
6789      *         a value less than {@code 0} if, over the specified ranges, the
6790      *         first array is lexicographically less than the second array; and
6791      *         a value greater than {@code 0} if, over the specified ranges, the
6792      *         first array is lexicographically greater than the second array
6793      * @throws IllegalArgumentException
6794      *         if {@code aFromIndex > aToIndex} or
6795      *         if {@code bFromIndex > bToIndex}
6796      * @throws ArrayIndexOutOfBoundsException
6797      *         if {@code aFromIndex < 0 or aToIndex > a.length} or
6798      *         if {@code bFromIndex < 0 or bToIndex > b.length}
6799      * @throws NullPointerException
6800      *         if either array is {@code null}
6801      * @since 9
6802      */
6803     public static int compare(long[] a, int aFromIndex, int aToIndex,
6804                               long[] b, int bFromIndex, int bToIndex) {
6805         rangeCheck(a.length, aFromIndex, aToIndex);
6806         rangeCheck(b.length, bFromIndex, bToIndex);
6807 
6808         int aLength = aToIndex - aFromIndex;
6809         int bLength = bToIndex - bFromIndex;
6810         int length = Math.min(aLength, bLength);
6811         for (int i = 0; i < length; i++) {
6812             long va = a[aFromIndex++];
6813             long vb = b[bFromIndex++];
6814             if (va != vb) return Long.compare(va, vb);
6815         }
6816 
6817         return aLength - bLength;
6818     }
6819 
6820     /**
6821      * Compares two {@code long} arrays lexicographically, numerically treating
6822      * elements as unsigned.
6823      *
6824      * <p>If the two arrays share a common prefix then the lexicographic
6825      * comparison is the result of comparing two elements, as if by
6826      * {@link Long#compareUnsigned(long, long)}, at an index within the
6827      * respective arrays that is the prefix length.
6828      * Otherwise, one array is a proper prefix of the other and, lexicographic
6829      * comparison is the result of comparing the two array lengths.
6830      * (See {@link #mismatch(long[], long[])} for the definition of a common
6831      * and proper prefix.)
6832      *
6833      * <p>A {@code null} array reference is considered lexicographically less
6834      * than a non-{@code null} array reference.  Two {@code null} array
6835      * references are considered equal.
6836      *
6837      * @apiNote
6838      * <p>This method behaves as if (for non-{@code null} array references):
6839      * <pre>{@code
6840      *     int i = Arrays.mismatch(a, b);
6841      *     if (i >= 0 && i < Math.min(a.length, b.length))
6842      *         return Long.compareUnsigned(a[i], b[i]);
6843      *     return a.length - b.length;
6844      * }</pre>
6845      *
6846      * @param a the first array to compare
6847      * @param b the second array to compare
6848      * @return the value {@code 0} if the first and second array are
6849      *         equal and contain the same elements in the same order;
6850      *         a value less than {@code 0} if the first array is
6851      *         lexicographically less than the second array; and
6852      *         a value greater than {@code 0} if the first array is
6853      *         lexicographically greater than the second array
6854      * @since 9
6855      */
6856     public static int compareUnsigned(long[] a, long[] b) {
6857         if (a == b)
6858             return 0;
6859         if (a == null || b == null)
6860             return a == null ? -1 : 1;
6861 
6862         int length = Math.min(a.length, b.length);
6863         for (int i = 0; i < length; i++) {
6864             if (a[i] != b[i]) return Long.compareUnsigned(a[i], b[i]);
6865         }
6866 
6867         return a.length - b.length;
6868     }
6869 
6870     /**
6871      * Compares two {@code long} arrays lexicographically over the specified
6872      * ranges, numerically treating elements as unsigned.
6873      *
6874      * <p>If the two arrays, over the specified ranges, share a common prefix
6875      * then the lexicographic comparison is the result of comparing two
6876      * elements, as if by {@link Long#compareUnsigned(long, long)}, at a
6877      * relative index within the respective arrays that is the length of the
6878      * prefix.
6879      * Otherwise, one array is a proper prefix of the other and, lexicographic
6880      * comparison is the result of comparing the two range lengths.
6881      * (See {@link #mismatch(long[], int, int, long[], int, int)} for the
6882      * definition of a common and proper prefix.)
6883      *
6884      * @apiNote
6885      * <p>This method behaves as if:
6886      * <pre>{@code
6887      *     int i = Arrays.mismatch(a, aFromIndex, aToIndex,
6888      *                             b, bFromIndex, bToIndex);
6889      *     if (i >= 0 && i < Math.min(aToIndex - aFromIndex, bToIndex - bFromIndex))
6890      *         return Long.compareUnsigned(a[aFromIndex + i], b[bFromIndex + i]);
6891      *     return (aToIndex - aFromIndex) - (bToIndex - bFromIndex);
6892      * }</pre>
6893      *
6894      * @param a the first array to compare
6895      * @param aFromIndex the index (inclusive) of the first element in the
6896      *                   first array to be compared
6897      * @param aToIndex the index (exclusive) of the last element in the
6898      *                 first array to be compared
6899      * @param b the second array to compare
6900      * @param bFromIndex the index (inclusive) of the first element in the
6901      *                   second array to be compared
6902      * @param bToIndex the index (exclusive) of the last element in the
6903      *                 second array to be compared
6904      * @return the value {@code 0} if, over the specified ranges, the first and
6905      *         second array are equal and contain the same elements in the same
6906      *         order;
6907      *         a value less than {@code 0} if, over the specified ranges, the
6908      *         first array is lexicographically less than the second array; and
6909      *         a value greater than {@code 0} if, over the specified ranges, the
6910      *         first array is lexicographically greater than the second array
6911      * @throws IllegalArgumentException
6912      *         if {@code aFromIndex > aToIndex} or
6913      *         if {@code bFromIndex > bToIndex}
6914      * @throws ArrayIndexOutOfBoundsException
6915      *         if {@code aFromIndex < 0 or aToIndex > a.length} or
6916      *         if {@code bFromIndex < 0 or bToIndex > b.length}
6917      * @throws NullPointerException
6918      *         if either array is null
6919      * @since 9
6920      */
6921     public static int compareUnsigned(long[] a, int aFromIndex, int aToIndex,
6922                                       long[] b, int bFromIndex, int bToIndex) {
6923         rangeCheck(a.length, aFromIndex, aToIndex);
6924         rangeCheck(b.length, bFromIndex, bToIndex);
6925 
6926         int aLength = aToIndex - aFromIndex;
6927         int bLength = bToIndex - bFromIndex;
6928         int length = Math.min(aLength, bLength);
6929         for (int i = 0; i < length; i++) {
6930             long va = a[aFromIndex++];
6931             long vb = b[bFromIndex++];
6932             if (va != vb) return Long.compareUnsigned(va, vb);
6933         }
6934 
6935         return aLength - bLength;
6936     }
6937 
6938     // Compare float
6939 
6940     /**
6941      * Compares two {@code float} arrays lexicographically.
6942      *
6943      * <p>If the two arrays share a common prefix then the lexicographic
6944      * comparison is the result of comparing two elements, as if by
6945      * {@link Float#compare(float, float)}, at an index within the respective
6946      * arrays that is the prefix length.
6947      * Otherwise, one array is a proper prefix of the other and, lexicographic
6948      * comparison is the result of comparing the two array lengths.
6949      * (See {@link #mismatch(float[], float[])} for the definition of a common
6950      * and proper prefix.)
6951      *
6952      * <p>A {@code null} array reference is considered lexicographically less
6953      * than a non-{@code null} array reference.  Two {@code null} array
6954      * references are considered equal.
6955      *
6956      * <p>The comparison is consistent with {@link #equals(float[], float[]) equals},
6957      * more specifically the following holds for arrays {@code a} and {@code b}:
6958      * <pre>{@code
6959      *     Arrays.equals(a, b) == (Arrays.compare(a, b) == 0)
6960      * }</pre>
6961      *
6962      * @apiNote
6963      * <p>This method behaves as if (for non-{@code null} array references):
6964      * <pre>{@code
6965      *     int i = Arrays.mismatch(a, b);
6966      *     if (i >= 0 && i < Math.min(a.length, b.length))
6967      *         return Float.compare(a[i], b[i]);
6968      *     return a.length - b.length;
6969      * }</pre>
6970      *
6971      * @param a the first array to compare
6972      * @param b the second array to compare
6973      * @return the value {@code 0} if the first and second array are equal and
6974      *         contain the same elements in the same order;
6975      *         a value less than {@code 0} if the first array is
6976      *         lexicographically less than the second array; and
6977      *         a value greater than {@code 0} if the first array is
6978      *         lexicographically greater than the second array
6979      * @since 9
6980      */
6981     public static int compare(float[] a, float[] b) {
6982         if (a == b)
6983             return 0;
6984         if (a == null || b == null)
6985             return a == null ? -1 : 1;
6986 
6987         int length = Math.min(a.length, b.length);
6988         for (int i = 0; i < length; i++) {
6989             float va = a[i], vb = b[i];
6990             if (Float.floatToRawIntBits(va) != Float.floatToRawIntBits(vb)) {
6991                 int c = Float.compare(va, vb);
6992                 if (c != 0) return c;
6993             }
6994         }
6995 
6996         return a.length - b.length;
6997     }
6998 
6999     /**
7000      * Compares two {@code float} arrays lexicographically over the specified
7001      * ranges.
7002      *
7003      * <p>If the two arrays, over the specified ranges, share a common prefix
7004      * then the lexicographic comparison is the result of comparing two
7005      * elements, as if by {@link Float#compare(float, float)}, at a relative
7006      * index within the respective arrays that is the length of the prefix.
7007      * Otherwise, one array is a proper prefix of the other and, lexicographic
7008      * comparison is the result of comparing the two range lengths.
7009      * (See {@link #mismatch(float[], int, int, float[], int, int)} for the
7010      * definition of a common and proper prefix.)
7011      *
7012      * <p>The comparison is consistent with
7013      * {@link #equals(float[], int, int, float[], int, int) equals}, more
7014      * specifically the following holds for arrays {@code a} and {@code b} with
7015      * specified ranges [{@code aFromIndex}, {@code atoIndex}) and
7016      * [{@code bFromIndex}, {@code btoIndex}) respectively:
7017      * <pre>{@code
7018      *     Arrays.equals(a, aFromIndex, aToIndex, b, bFromIndex, bToIndex) ==
7019      *         (Arrays.compare(a, aFromIndex, aToIndex, b, bFromIndex, bToIndex) == 0)
7020      * }</pre>
7021      *
7022      * @apiNote
7023      * <p>This method behaves as if:
7024      * <pre>{@code
7025      *     int i = Arrays.mismatch(a, aFromIndex, aToIndex,
7026      *                             b, bFromIndex, bToIndex);
7027      *     if (i >= 0 && i < Math.min(aToIndex - aFromIndex, bToIndex - bFromIndex))
7028      *         return Float.compare(a[aFromIndex + i], b[bFromIndex + i]);
7029      *     return (aToIndex - aFromIndex) - (bToIndex - bFromIndex);
7030      * }</pre>
7031      *
7032      * @param a the first array to compare
7033      * @param aFromIndex the index (inclusive) of the first element in the
7034      *                   first array to be compared
7035      * @param aToIndex the index (exclusive) of the last element in the
7036      *                 first array to be compared
7037      * @param b the second array to compare
7038      * @param bFromIndex the index (inclusive) of the first element in the
7039      *                   second array to be compared
7040      * @param bToIndex the index (exclusive) of the last element in the
7041      *                 second array to be compared
7042      * @return the value {@code 0} if, over the specified ranges, the first and
7043      *         second array are equal and contain the same elements in the same
7044      *         order;
7045      *         a value less than {@code 0} if, over the specified ranges, the
7046      *         first array is lexicographically less than the second array; and
7047      *         a value greater than {@code 0} if, over the specified ranges, the
7048      *         first array is lexicographically greater than the second array
7049      * @throws IllegalArgumentException
7050      *         if {@code aFromIndex > aToIndex} or
7051      *         if {@code bFromIndex > bToIndex}
7052      * @throws ArrayIndexOutOfBoundsException
7053      *         if {@code aFromIndex < 0 or aToIndex > a.length} or
7054      *         if {@code bFromIndex < 0 or bToIndex > b.length}
7055      * @throws NullPointerException
7056      *         if either array is {@code null}
7057      * @since 9
7058      */
7059     public static int compare(float[] a, int aFromIndex, int aToIndex,
7060                               float[] b, int bFromIndex, int bToIndex) {
7061         rangeCheck(a.length, aFromIndex, aToIndex);
7062         rangeCheck(b.length, bFromIndex, bToIndex);
7063 
7064         int aLength = aToIndex - aFromIndex;
7065         int bLength = bToIndex - bFromIndex;
7066         int length = Math.min(aLength, bLength);
7067         for (int i = 0; i < length; i++) {
7068             float va = a[aFromIndex++], vb = b[bFromIndex++];
7069             if (Float.floatToRawIntBits(va) != Float.floatToRawIntBits(vb)) {
7070                 int c = Float.compare(va, vb);
7071                 if (c != 0) return c;
7072             }
7073         }
7074 
7075         return aLength - bLength;
7076     }
7077 
7078     // Compare double
7079 
7080     /**
7081      * Compares two {@code double} arrays lexicographically.
7082      *
7083      * <p>If the two arrays share a common prefix then the lexicographic
7084      * comparison is the result of comparing two elements, as if by
7085      * {@link Double#compare(double, double)}, at an index within the respective
7086      * arrays that is the prefix length.
7087      * Otherwise, one array is a proper prefix of the other and, lexicographic
7088      * comparison is the result of comparing the two array lengths.
7089      * (See {@link #mismatch(double[], double[])} for the definition of a common
7090      * and proper prefix.)
7091      *
7092      * <p>A {@code null} array reference is considered lexicographically less
7093      * than a non-{@code null} array reference.  Two {@code null} array
7094      * references are considered equal.
7095      *
7096      * <p>The comparison is consistent with {@link #equals(double[], double[]) equals},
7097      * more specifically the following holds for arrays {@code a} and {@code b}:
7098      * <pre>{@code
7099      *     Arrays.equals(a, b) == (Arrays.compare(a, b) == 0)
7100      * }</pre>
7101      *
7102      * @apiNote
7103      * <p>This method behaves as if (for non-{@code null} array references):
7104      * <pre>{@code
7105      *     int i = Arrays.mismatch(a, b);
7106      *     if (i >= 0 && i < Math.min(a.length, b.length))
7107      *         return Double.compare(a[i], b[i]);
7108      *     return a.length - b.length;
7109      * }</pre>
7110      *
7111      * @param a the first array to compare
7112      * @param b the second array to compare
7113      * @return the value {@code 0} if the first and second array are equal and
7114      *         contain the same elements in the same order;
7115      *         a value less than {@code 0} if the first array is
7116      *         lexicographically less than the second array; and
7117      *         a value greater than {@code 0} if the first array is
7118      *         lexicographically greater than the second array
7119      * @since 9
7120      */
7121     public static int compare(double[] a, double[] b) {
7122         if (a == b)
7123             return 0;
7124         if (a == null || b == null)
7125             return a == null ? -1 : 1;
7126 
7127         int length = Math.min(a.length, b.length);
7128         for (int i = 0; i < length; i++) {
7129             double va = a[i], vb = b[i];
7130             if (Double.doubleToRawLongBits(va) != Double.doubleToRawLongBits(vb)) {
7131                 int c = Double.compare(va, vb);
7132                 if (c != 0) return c;
7133             }
7134         }
7135 
7136         return a.length - b.length;
7137     }
7138 
7139     /**
7140      * Compares two {@code double} arrays lexicographically over the specified
7141      * ranges.
7142      *
7143      * <p>If the two arrays, over the specified ranges, share a common prefix
7144      * then the lexicographic comparison is the result of comparing two
7145      * elements, as if by {@link Double#compare(double, double)}, at a relative
7146      * index within the respective arrays that is the length of the prefix.
7147      * Otherwise, one array is a proper prefix of the other and, lexicographic
7148      * comparison is the result of comparing the two range lengths.
7149      * (See {@link #mismatch(double[], int, int, double[], int, int)} for the
7150      * definition of a common and proper prefix.)
7151      *
7152      * <p>The comparison is consistent with
7153      * {@link #equals(double[], int, int, double[], int, int) equals}, more
7154      * specifically the following holds for arrays {@code a} and {@code b} with
7155      * specified ranges [{@code aFromIndex}, {@code atoIndex}) and
7156      * [{@code bFromIndex}, {@code btoIndex}) respectively:
7157      * <pre>{@code
7158      *     Arrays.equals(a, aFromIndex, aToIndex, b, bFromIndex, bToIndex) ==
7159      *         (Arrays.compare(a, aFromIndex, aToIndex, b, bFromIndex, bToIndex) == 0)
7160      * }</pre>
7161      *
7162      * @apiNote
7163      * <p>This method behaves as if:
7164      * <pre>{@code
7165      *     int i = Arrays.mismatch(a, aFromIndex, aToIndex,
7166      *                             b, bFromIndex, bToIndex);
7167      *     if (i >= 0 && i < Math.min(aToIndex - aFromIndex, bToIndex - bFromIndex))
7168      *         return Double.compare(a[aFromIndex + i], b[bFromIndex + i]);
7169      *     return (aToIndex - aFromIndex) - (bToIndex - bFromIndex);
7170      * }</pre>
7171      *
7172      * @param a the first array to compare
7173      * @param aFromIndex the index (inclusive) of the first element in the
7174      *                   first array to be compared
7175      * @param aToIndex the index (exclusive) of the last element in the
7176      *                 first array to be compared
7177      * @param b the second array to compare
7178      * @param bFromIndex the index (inclusive) of the first element in the
7179      *                   second array to be compared
7180      * @param bToIndex the index (exclusive) of the last element in the
7181      *                 second array to be compared
7182      * @return the value {@code 0} if, over the specified ranges, the first and
7183      *         second array are equal and contain the same elements in the same
7184      *         order;
7185      *         a value less than {@code 0} if, over the specified ranges, the
7186      *         first array is lexicographically less than the second array; and
7187      *         a value greater than {@code 0} if, over the specified ranges, the
7188      *         first array is lexicographically greater than the second array
7189      * @throws IllegalArgumentException
7190      *         if {@code aFromIndex > aToIndex} or
7191      *         if {@code bFromIndex > bToIndex}
7192      * @throws ArrayIndexOutOfBoundsException
7193      *         if {@code aFromIndex < 0 or aToIndex > a.length} or
7194      *         if {@code bFromIndex < 0 or bToIndex > b.length}
7195      * @throws NullPointerException
7196      *         if either array is {@code null}
7197      * @since 9
7198      */
7199     public static int compare(double[] a, int aFromIndex, int aToIndex,
7200                               double[] b, int bFromIndex, int bToIndex) {
7201         rangeCheck(a.length, aFromIndex, aToIndex);
7202         rangeCheck(b.length, bFromIndex, bToIndex);
7203 
7204         int aLength = aToIndex - aFromIndex;
7205         int bLength = bToIndex - bFromIndex;
7206         int length = Math.min(aLength, bLength);
7207         for (int i = 0; i < length; i++) {
7208             double va = a[aFromIndex++], vb = b[bFromIndex++];
7209             if (Double.doubleToRawLongBits(va) != Double.doubleToRawLongBits(vb)) {
7210                 int c = Double.compare(va, vb);
7211                 if (c != 0) return c;
7212             }
7213         }
7214 
7215         return aLength - bLength;
7216     }
7217 
7218     // Compare objects
7219 
7220     /**
7221      * Compares two {@code Object} arrays, within comparable elements,
7222      * lexicographically.
7223      *
7224      * <p>If the two arrays share a common prefix then the lexicographic
7225      * comparison is the result of comparing two elements of type {@code T} at
7226      * an index {@code i} within the respective arrays that is the prefix
7227      * length, as if by:
7228      * <pre>{@code
7229      *     Comparator.nullsFirst(Comparator.<T>naturalOrder()).
7230      *         compare(a[i], b[i])
7231      * }</pre>
7232      * Otherwise, one array is a proper prefix of the other and, lexicographic
7233      * comparison is the result of comparing the two array lengths.
7234      * (See {@link #mismatch(Object[], Object[])} for the definition of a common
7235      * and proper prefix.)
7236      *
7237      * <p>A {@code null} array reference is considered lexicographically less
7238      * than a non-{@code null} array reference.  Two {@code null} array
7239      * references are considered equal.
7240      * A {@code null} array element is considered lexicographically than a
7241      * non-{@code null} array element.  Two {@code null} array elements are
7242      * considered equal.
7243      *
7244      * <p>The comparison is consistent with {@link #equals(Object[], Object[]) equals},
7245      * more specifically the following holds for arrays {@code a} and {@code b}:
7246      * <pre>{@code
7247      *     Arrays.equals(a, b) == (Arrays.compare(a, b) == 0)
7248      * }</pre>
7249      *
7250      * @apiNote
7251      * <p>This method behaves as if (for non-{@code null} array references
7252      * and elements):
7253      * <pre>{@code
7254      *     int i = Arrays.mismatch(a, b);
7255      *     if (i >= 0 && i < Math.min(a.length, b.length))
7256      *         return a[i].compareTo(b[i]);
7257      *     return a.length - b.length;
7258      * }</pre>
7259      *
7260      * @param a the first array to compare
7261      * @param b the second array to compare
7262      * @param <T> the type of comparable array elements
7263      * @return the value {@code 0} if the first and second array are equal and
7264      *         contain the same elements in the same order;
7265      *         a value less than {@code 0} if the first array is
7266      *         lexicographically less than the second array; and
7267      *         a value greater than {@code 0} if the first array is
7268      *         lexicographically greater than the second array
7269      * @since 9
7270      */
7271     public static <T extends Comparable<? super T>> int compare(T[] a, T[] b) {
7272         if (a == b)
7273             return 0;
7274         // A null array is less than a non-null array
7275         if (a == null || b == null)
7276             return a == null ? -1 : 1;
7277 
7278         int length = Math.min(a.length, b.length);
7279         for (int i = 0; i < length; i++) {
7280             T oa = a[i];
7281             T ob = b[i];
7282             if (oa != ob) {
7283                 // A null element is less than a non-null element
7284                 if (oa == null || ob == null)
7285                     return oa == null ? -1 : 1;
7286                 int v = oa.compareTo(ob);
7287                 if (v != 0) {
7288                     return v;
7289                 }
7290             }
7291         }
7292 
7293         return a.length - b.length;
7294     }
7295 
7296     /**
7297      * Compares two {@code Object} arrays lexicographically over the specified
7298      * ranges.
7299      *
7300      * <p>If the two arrays, over the specified ranges, share a common prefix
7301      * then the lexicographic comparison is the result of comparing two
7302      * elements of type {@code T} at a relative index {@code i} within the
7303      * respective arrays that is the prefix length, as if by:
7304      * <pre>{@code
7305      *     Comparator.nullsFirst(Comparator.<T>naturalOrder()).
7306      *         compare(a[aFromIndex + i, b[bFromIndex + i])
7307      * }</pre>
7308      * Otherwise, one array is a proper prefix of the other and, lexicographic
7309      * comparison is the result of comparing the two range lengths.
7310      * (See {@link #mismatch(Object[], int, int, Object[], int, int)} for the
7311      * definition of a common and proper prefix.)
7312      *
7313      * <p>The comparison is consistent with
7314      * {@link #equals(Object[], int, int, Object[], int, int) equals}, more
7315      * specifically the following holds for arrays {@code a} and {@code b} with
7316      * specified ranges [{@code aFromIndex}, {@code atoIndex}) and
7317      * [{@code bFromIndex}, {@code btoIndex}) respectively:
7318      * <pre>{@code
7319      *     Arrays.equals(a, aFromIndex, aToIndex, b, bFromIndex, bToIndex) ==
7320      *         (Arrays.compare(a, aFromIndex, aToIndex, b, bFromIndex, bToIndex) == 0)
7321      * }</pre>
7322      *
7323      * @apiNote
7324      * <p>This method behaves as if (for non-{@code null} array elements):
7325      * <pre>{@code
7326      *     int i = Arrays.mismatch(a, aFromIndex, aToIndex,
7327      *                             b, bFromIndex, bToIndex);
7328      *     if (i >= 0 && i < Math.min(aToIndex - aFromIndex, bToIndex - bFromIndex))
7329      *         return a[aFromIndex + i].compareTo(b[bFromIndex + i]);
7330      *     return (aToIndex - aFromIndex) - (bToIndex - bFromIndex);
7331      * }</pre>
7332      *
7333      * @param a the first array to compare
7334      * @param aFromIndex the index (inclusive) of the first element in the
7335      *                   first array to be compared
7336      * @param aToIndex the index (exclusive) of the last element in the
7337      *                 first array to be compared
7338      * @param b the second array to compare
7339      * @param bFromIndex the index (inclusive) of the first element in the
7340      *                   second array to be compared
7341      * @param bToIndex the index (exclusive) of the last element in the
7342      *                 second array to be compared
7343      * @param <T> the type of comparable array elements
7344      * @return the value {@code 0} if, over the specified ranges, the first and
7345      *         second array are equal and contain the same elements in the same
7346      *         order;
7347      *         a value less than {@code 0} if, over the specified ranges, the
7348      *         first array is lexicographically less than the second array; and
7349      *         a value greater than {@code 0} if, over the specified ranges, the
7350      *         first array is lexicographically greater than the second array
7351      * @throws IllegalArgumentException
7352      *         if {@code aFromIndex > aToIndex} or
7353      *         if {@code bFromIndex > bToIndex}
7354      * @throws ArrayIndexOutOfBoundsException
7355      *         if {@code aFromIndex < 0 or aToIndex > a.length} or
7356      *         if {@code bFromIndex < 0 or bToIndex > b.length}
7357      * @throws NullPointerException
7358      *         if either array is {@code null}
7359      * @since 9
7360      */
7361     public static <T extends Comparable<? super T>> int compare(
7362             T[] a, int aFromIndex, int aToIndex,
7363             T[] b, int bFromIndex, int bToIndex) {
7364         rangeCheck(a.length, aFromIndex, aToIndex);
7365         rangeCheck(b.length, bFromIndex, bToIndex);
7366 
7367         int aLength = aToIndex - aFromIndex;
7368         int bLength = bToIndex - bFromIndex;
7369         int length = Math.min(aLength, bLength);
7370         for (int i = 0; i < length; i++) {
7371             T oa = a[aFromIndex++];
7372             T ob = b[bFromIndex++];
7373             if (oa != ob) {
7374                 if (oa == null || ob == null)
7375                     return oa == null ? -1 : 1;
7376                 int v = oa.compareTo(ob);
7377                 if (v != 0) {
7378                     return v;
7379                 }
7380             }
7381         }
7382 
7383         return aLength - bLength;
7384     }
7385 
7386     /**
7387      * Compares two {@code Object} arrays lexicographically using a specified
7388      * comparator.
7389      *
7390      * <p>If the two arrays share a common prefix then the lexicographic
7391      * comparison is the result of comparing with the specified comparator two
7392      * elements at an index within the respective arrays that is the prefix
7393      * length.
7394      * Otherwise, one array is a proper prefix of the other and, lexicographic
7395      * comparison is the result of comparing the two array lengths.
7396      * (See {@link #mismatch(Object[], Object[])} for the definition of a common
7397      * and proper prefix.)
7398      *
7399      * <p>A {@code null} array reference is considered lexicographically less
7400      * than a non-{@code null} array reference.  Two {@code null} array
7401      * references are considered equal.
7402      *
7403      * @apiNote
7404      * <p>This method behaves as if (for non-{@code null} array references):
7405      * <pre>{@code
7406      *     int i = Arrays.mismatch(a, b, cmp);
7407      *     if (i >= 0 && i < Math.min(a.length, b.length))
7408      *         return cmp.compare(a[i], b[i]);
7409      *     return a.length - b.length;
7410      * }</pre>
7411      *
7412      * @param a the first array to compare
7413      * @param b the second array to compare
7414      * @param cmp the comparator to compare array elements
7415      * @param <T> the type of array elements
7416      * @return the value {@code 0} if the first and second array are equal and
7417      *         contain the same elements in the same order;
7418      *         a value less than {@code 0} if the first array is
7419      *         lexicographically less than the second array; and
7420      *         a value greater than {@code 0} if the first array is
7421      *         lexicographically greater than the second array
7422      * @throws NullPointerException if the comparator is {@code null}
7423      * @since 9
7424      */
7425     public static <T> int compare(T[] a, T[] b,
7426                                   Comparator<? super T> cmp) {
7427         Objects.requireNonNull(cmp);
7428         if (a == b)
7429             return 0;
7430         if (a == null || b == null)
7431             return a == null ? -1 : 1;
7432 
7433         int length = Math.min(a.length, b.length);
7434         for (int i = 0; i < length; i++) {
7435             T oa = a[i];
7436             T ob = b[i];
7437             if (oa != ob) {
7438                 // Null-value comparison is deferred to the comparator
7439                 int v = cmp.compare(oa, ob);
7440                 if (v != 0) {
7441                     return v;
7442                 }
7443             }
7444         }
7445 
7446         return a.length - b.length;
7447     }
7448 
7449     /**
7450      * Compares two {@code Object} arrays lexicographically over the specified
7451      * ranges.
7452      *
7453      * <p>If the two arrays, over the specified ranges, share a common prefix
7454      * then the lexicographic comparison is the result of comparing with the
7455      * specified comparator two elements at a relative index within the
7456      * respective arrays that is the prefix length.
7457      * Otherwise, one array is a proper prefix of the other and, lexicographic
7458      * comparison is the result of comparing the two range lengths.
7459      * (See {@link #mismatch(Object[], int, int, Object[], int, int)} for the
7460      * definition of a common and proper prefix.)
7461      *
7462      * @apiNote
7463      * <p>This method behaves as if (for non-{@code null} array elements):
7464      * <pre>{@code
7465      *     int i = Arrays.mismatch(a, aFromIndex, aToIndex,
7466      *                             b, bFromIndex, bToIndex, cmp);
7467      *     if (i >= 0 && i < Math.min(aToIndex - aFromIndex, bToIndex - bFromIndex))
7468      *         return cmp.compare(a[aFromIndex + i], b[bFromIndex + i]);
7469      *     return (aToIndex - aFromIndex) - (bToIndex - bFromIndex);
7470      * }</pre>
7471      *
7472      * @param a the first array to compare
7473      * @param aFromIndex the index (inclusive) of the first element in the
7474      *                   first array to be compared
7475      * @param aToIndex the index (exclusive) of the last element in the
7476      *                 first array to be compared
7477      * @param b the second array to compare
7478      * @param bFromIndex the index (inclusive) of the first element in the
7479      *                   second array to be compared
7480      * @param bToIndex the index (exclusive) of the last element in the
7481      *                 second array to be compared
7482      * @param cmp the comparator to compare array elements
7483      * @param <T> the type of array elements
7484      * @return the value {@code 0} if, over the specified ranges, the first and
7485      *         second array are equal and contain the same elements in the same
7486      *         order;
7487      *         a value less than {@code 0} if, over the specified ranges, the
7488      *         first array is lexicographically less than the second array; and
7489      *         a value greater than {@code 0} if, over the specified ranges, the
7490      *         first array is lexicographically greater than the second array
7491      * @throws IllegalArgumentException
7492      *         if {@code aFromIndex > aToIndex} or
7493      *         if {@code bFromIndex > bToIndex}
7494      * @throws ArrayIndexOutOfBoundsException
7495      *         if {@code aFromIndex < 0 or aToIndex > a.length} or
7496      *         if {@code bFromIndex < 0 or bToIndex > b.length}
7497      * @throws NullPointerException
7498      *         if either array or the comparator is {@code null}
7499      * @since 9
7500      */
7501     public static <T> int compare(
7502             T[] a, int aFromIndex, int aToIndex,
7503             T[] b, int bFromIndex, int bToIndex,
7504             Comparator<? super T> cmp) {
7505         Objects.requireNonNull(cmp);
7506         rangeCheck(a.length, aFromIndex, aToIndex);
7507         rangeCheck(b.length, bFromIndex, bToIndex);
7508 
7509         int aLength = aToIndex - aFromIndex;
7510         int bLength = bToIndex - bFromIndex;
7511         int length = Math.min(aLength, bLength);
7512         for (int i = 0; i < length; i++) {
7513             T oa = a[aFromIndex++];
7514             T ob = b[bFromIndex++];
7515             if (oa != ob) {
7516                 // Null-value comparison is deferred to the comparator
7517                 int v = cmp.compare(oa, ob);
7518                 if (v != 0) {
7519                     return v;
7520                 }
7521             }
7522         }
7523 
7524         return aLength - bLength;
7525     }
7526 
7527 
7528     // Mismatch methods
7529 
7530     // Mismatch boolean
7531 
7532     /**
7533      * Finds and returns the index of the first mismatch between two
7534      * {@code boolean} arrays, otherwise return -1 if no mismatch is found.  The
7535      * index will be in the range of 0 (inclusive) up to the length (inclusive)
7536      * of the smaller array.
7537      *
7538      * <p>If the two arrays share a common prefix then the returned index is the
7539      * length of the common prefix and it follows that there is a mismatch
7540      * between the two elements at that index within the respective arrays.
7541      * If one array is a proper prefix of the other then the returned index is
7542      * the length of the smaller array and it follows that the index is only
7543      * valid for the larger array.
7544      * Otherwise, there is no mismatch.
7545      *
7546      * <p>Two non-{@code null} arrays, {@code a} and {@code b}, share a common
7547      * prefix of length {@code pl} if the following expression is true:
7548      * <pre>{@code
7549      *     pl >= 0 &&
7550      *     pl < Math.min(a.length, b.length) &&
7551      *     Arrays.equals(a, 0, pl, b, 0, pl) &&
7552      *     a[pl] != b[pl]
7553      * }</pre>
7554      * Note that a common prefix length of {@code 0} indicates that the first
7555      * elements from each array mismatch.
7556      *
7557      * <p>Two non-{@code null} arrays, {@code a} and {@code b}, share a proper
7558      * prefix if the following expression is true:
7559      * <pre>{@code
7560      *     a.length != b.length &&
7561      *     Arrays.equals(a, 0, Math.min(a.length, b.length),
7562      *                   b, 0, Math.min(a.length, b.length))
7563      * }</pre>
7564      *
7565      * @param a the first array to be tested for a mismatch
7566      * @param b the second array to be tested for a mismatch
7567      * @return the index of the first mismatch between the two arrays,
7568      *         otherwise {@code -1}.
7569      * @throws NullPointerException
7570      *         if either array is {@code null}
7571      * @since 9
7572      */
7573     public static int mismatch(boolean[] a, boolean[] b) {
7574         int length = Math.min(a.length, b.length); // Check null array refs
7575         if (a == b)
7576             return -1;
7577 
7578         for (int i = 0; i < length; i++) {
7579             if (a[i] != b[i]) return i;
7580         }
7581 
7582         return a.length != b.length ? length : -1;
7583     }
7584 
7585     /**
7586      * Finds and returns the relative index of the first mismatch between two
7587      * {@code boolean} arrays over the specified ranges, otherwise return -1 if
7588      * no mismatch is found.  The index will be in the range of 0 (inclusive) up
7589      * to the length (inclusive) of the smaller range.
7590      *
7591      * <p>If the two arrays, over the specified ranges, share a common prefix
7592      * then the returned relative index is the length of the common prefix and
7593      * it follows that there is a mismatch between the two elements at that
7594      * relative index within the respective arrays.
7595      * If one array is a proper prefix of the other, over the specified ranges,
7596      * then the returned relative index is the length of the smaller range and
7597      * it follows that the relative index is only valid for the array with the
7598      * larger range.
7599      * Otherwise, there is no mismatch.
7600      *
7601      * <p>Two non-{@code null} arrays, {@code a} and {@code b} with specified
7602      * ranges [{@code aFromIndex}, {@code atoIndex}) and
7603      * [{@code bFromIndex}, {@code btoIndex}) respectively, share a common
7604      * prefix of length {@code pl} if the following expression is true:
7605      * <pre>{@code
7606      *     pl >= 0 &&
7607      *     pl < Math.min(aToIndex - aFromIndex, bToIndex - bFromIndex) &&
7608      *     Arrays.equals(a, aFromIndex, aFromIndex + pl, b, bFromIndex, bFromIndex + pl) &&
7609      *     a[aFromIndex + pl] != b[bFromIndex + pl]
7610      * }</pre>
7611      * Note that a common prefix length of {@code 0} indicates that the first
7612      * elements from each array mismatch.
7613      *
7614      * <p>Two non-{@code null} arrays, {@code a} and {@code b} with specified
7615      * ranges [{@code aFromIndex}, {@code atoIndex}) and
7616      * [{@code bFromIndex}, {@code btoIndex}) respectively, share a proper
7617      * if the following expression is true:
7618      * <pre>{@code
7619      *     (aToIndex - aFromIndex) != (bToIndex - bFromIndex) &&
7620      *     Arrays.equals(a, 0, Math.min(aToIndex - aFromIndex, bToIndex - bFromIndex),
7621      *                   b, 0, Math.min(aToIndex - aFromIndex, bToIndex - bFromIndex))
7622      * }</pre>
7623      *
7624      * @param a the first array to be tested for a mismatch
7625      * @param aFromIndex the index (inclusive) of the first element in the
7626      *                   first array to be tested
7627      * @param aToIndex the index (exclusive) of the last element in the
7628      *                 first array to be tested
7629      * @param b the second array to be tested for a mismatch
7630      * @param bFromIndex the index (inclusive) of the first element in the
7631      *                   second array to be tested
7632      * @param bToIndex the index (exclusive) of the last element in the
7633      *                 second array to be tested
7634      * @return the relative index of the first mismatch between the two arrays
7635      *         over the specified ranges, otherwise {@code -1}.
7636      * @throws IllegalArgumentException
7637      *         if {@code aFromIndex > aToIndex} or
7638      *         if {@code bFromIndex > bToIndex}
7639      * @throws ArrayIndexOutOfBoundsException
7640      *         if {@code aFromIndex < 0 or aToIndex > a.length} or
7641      *         if {@code bFromIndex < 0 or bToIndex > b.length}
7642      * @throws NullPointerException
7643      *         if either array is {@code null}
7644      * @since 9
7645      */
7646     public static int mismatch(boolean[] a, int aFromIndex, int aToIndex,
7647                                boolean[] b, int bFromIndex, int bToIndex) {
7648         rangeCheck(a.length, aFromIndex, aToIndex);
7649         rangeCheck(b.length, bFromIndex, bToIndex);
7650 
7651         int aLength = aToIndex - aFromIndex;
7652         int bLength = bToIndex - bFromIndex;
7653         int length = Math.min(aLength, bLength);
7654         for (int i = 0; i < length; i++) {
7655             if (a[aFromIndex++] != b[bFromIndex++]) return i;
7656         }
7657 
7658         return aLength != bLength ? length : -1;
7659     }
7660 
7661     // Mismatch byte
7662 
7663     /**
7664      * Finds and returns the index of the first mismatch between two {@code byte}
7665      * arrays, otherwise return -1 if no mismatch is found.  The index will be
7666      * in the range of 0 (inclusive) up to the length (inclusive) of the smaller
7667      * array.
7668      *
7669      * <p>If the two arrays share a common prefix then the returned index is the
7670      * length of the common prefix and it follows that there is a mismatch
7671      * between the two elements at that index within the respective arrays.
7672      * If one array is a proper prefix of the other then the returned index is
7673      * the length of the smaller array and it follows that the index is only
7674      * valid for the larger array.
7675      * Otherwise, there is no mismatch.
7676      *
7677      * <p>Two non-{@code null} arrays, {@code a} and {@code b}, share a common
7678      * prefix of length {@code pl} if the following expression is true:
7679      * <pre>{@code
7680      *     pl >= 0 &&
7681      *     pl < Math.min(a.length, b.length) &&
7682      *     Arrays.equals(a, 0, pl, b, 0, pl) &&
7683      *     a[pl] != b[pl]
7684      * }</pre>
7685      * Note that a common prefix length of {@code 0} indicates that the first
7686      * elements from each array mismatch.
7687      *
7688      * <p>Two non-{@code null} arrays, {@code a} and {@code b}, share a proper
7689      * prefix if the following expression is true:
7690      * <pre>{@code
7691      *     a.length != b.length &&
7692      *     Arrays.equals(a, 0, Math.min(a.length, b.length),
7693      *                   b, 0, Math.min(a.length, b.length))
7694      * }</pre>
7695      *
7696      * @param a the first array to be tested for a mismatch
7697      * @param b the second array to be tested for a mismatch
7698      * @return the index of the first mismatch between the two arrays,
7699      *         otherwise {@code -1}.
7700      * @throws NullPointerException
7701      *         if either array is {@code null}
7702      * @since 9
7703      */
7704     public static int mismatch(byte[] a, byte[] b) {
7705         int length = Math.min(a.length, b.length); // Check null array refs
7706         if (a == b)
7707             return -1;
7708 
7709         for (int i = 0; i < length; i++) {
7710             if (a[i] != b[i]) return i;
7711         }
7712 
7713         return a.length != b.length ? length : -1;
7714     }
7715 
7716     /**
7717      * Finds and returns the relative index of the first mismatch between two
7718      * {@code byte} arrays over the specified ranges, otherwise return -1 if no
7719      * mismatch is found.  The index will be in the range of 0 (inclusive) up to
7720      * the length (inclusive) of the smaller range.
7721      *
7722      * <p>If the two arrays, over the specified ranges, share a common prefix
7723      * then the returned relative index is the length of the common prefix and
7724      * it follows that there is a mismatch between the two elements at that
7725      * relative index within the respective arrays.
7726      * If one array is a proper prefix of the other, over the specified ranges,
7727      * then the returned relative index is the length of the smaller range and
7728      * it follows that the relative index is only valid for the array with the
7729      * larger range.
7730      * Otherwise, there is no mismatch.
7731      *
7732      * <p>Two non-{@code null} arrays, {@code a} and {@code b} with specified
7733      * ranges [{@code aFromIndex}, {@code atoIndex}) and
7734      * [{@code bFromIndex}, {@code btoIndex}) respectively, share a common
7735      * prefix of length {@code pl} if the following expression is true:
7736      * <pre>{@code
7737      *     pl >= 0 &&
7738      *     pl < Math.min(aToIndex - aFromIndex, bToIndex - bFromIndex) &&
7739      *     Arrays.equals(a, aFromIndex, aFromIndex + pl, b, bFromIndex, bFromIndex + pl) &&
7740      *     a[aFromIndex + pl] != b[bFromIndex + pl]
7741      * }</pre>
7742      * Note that a common prefix length of {@code 0} indicates that the first
7743      * elements from each array mismatch.
7744      *
7745      * <p>Two non-{@code null} arrays, {@code a} and {@code b} with specified
7746      * ranges [{@code aFromIndex}, {@code atoIndex}) and
7747      * [{@code bFromIndex}, {@code btoIndex}) respectively, share a proper
7748      * if the following expression is true:
7749      * <pre>{@code
7750      *     (aToIndex - aFromIndex) != (bToIndex - bFromIndex) &&
7751      *     Arrays.equals(a, 0, Math.min(aToIndex - aFromIndex, bToIndex - bFromIndex),
7752      *                   b, 0, Math.min(aToIndex - aFromIndex, bToIndex - bFromIndex))
7753      * }</pre>
7754      *
7755      * @param a the first array to be tested for a mismatch
7756      * @param aFromIndex the index (inclusive) of the first element in the
7757      *                   first array to be tested
7758      * @param aToIndex the index (exclusive) of the last element in the
7759      *                 first array to be tested
7760      * @param b the second array to be tested for a mismatch
7761      * @param bFromIndex the index (inclusive) of the first element in the
7762      *                   second array to be tested
7763      * @param bToIndex the index (exclusive) of the last element in the
7764      *                 second array to be tested
7765      * @return the relative index of the first mismatch between the two arrays
7766      *         over the specified ranges, otherwise {@code -1}.
7767      * @throws IllegalArgumentException
7768      *         if {@code aFromIndex > aToIndex} or
7769      *         if {@code bFromIndex > bToIndex}
7770      * @throws ArrayIndexOutOfBoundsException
7771      *         if {@code aFromIndex < 0 or aToIndex > a.length} or
7772      *         if {@code bFromIndex < 0 or bToIndex > b.length}
7773      * @throws NullPointerException
7774      *         if either array is {@code null}
7775      * @since 9
7776      */
7777     public static int mismatch(byte[] a, int aFromIndex, int aToIndex,
7778                                byte[] b, int bFromIndex, int bToIndex) {
7779         rangeCheck(a.length, aFromIndex, aToIndex);
7780         rangeCheck(b.length, bFromIndex, bToIndex);
7781 
7782         int aLength = aToIndex - aFromIndex;
7783         int bLength = bToIndex - bFromIndex;
7784         int length = Math.min(aLength, bLength);
7785         for (int i = 0; i < length; i++) {
7786             if (a[aFromIndex++] != b[bFromIndex++]) return i;
7787         }
7788 
7789         return aLength != bLength ? length : -1;
7790     }
7791 
7792     // Mismatch char
7793 
7794     /**
7795      * Finds and returns the index of the first mismatch between two {@code char}
7796      * arrays, otherwise return -1 if no mismatch is found.  The index will be
7797      * in the range of 0 (inclusive) up to the length (inclusive) of the smaller
7798      * array.
7799      *
7800      * <p>If the two arrays share a common prefix then the returned index is the
7801      * length of the common prefix and it follows that there is a mismatch
7802      * between the two elements at that index within the respective arrays.
7803      * If one array is a proper prefix of the other then the returned index is
7804      * the length of the smaller array and it follows that the index is only
7805      * valid for the larger array.
7806      * Otherwise, there is no mismatch.
7807      *
7808      * <p>Two non-{@code null} arrays, {@code a} and {@code b}, share a common
7809      * prefix of length {@code pl} if the following expression is true:
7810      * <pre>{@code
7811      *     pl >= 0 &&
7812      *     pl < Math.min(a.length, b.length) &&
7813      *     Arrays.equals(a, 0, pl, b, 0, pl) &&
7814      *     a[pl] != b[pl]
7815      * }</pre>
7816      * Note that a common prefix length of {@code 0} indicates that the first
7817      * elements from each array mismatch.
7818      *
7819      * <p>Two non-{@code null} arrays, {@code a} and {@code b}, share a proper
7820      * prefix if the following expression is true:
7821      * <pre>{@code
7822      *     a.length != b.length &&
7823      *     Arrays.equals(a, 0, Math.min(a.length, b.length),
7824      *                   b, 0, Math.min(a.length, b.length))
7825      * }</pre>
7826      *
7827      * @param a the first array to be tested for a mismatch
7828      * @param b the second array to be tested for a mismatch
7829      * @return the index of the first mismatch between the two arrays,
7830      *         otherwise {@code -1}.
7831      * @throws NullPointerException
7832      *         if either array is {@code null}
7833      * @since 9
7834      */
7835     public static int mismatch(char[] a, char[] b) {
7836         int length = Math.min(a.length, b.length); // Check null array refs
7837         if (a == b)
7838             return -1;
7839 
7840         for (int i = 0; i < length; i++) {
7841             if (a[i] != b[i]) return i;
7842         }
7843 
7844         return a.length != b.length ? length : -1;
7845     }
7846 
7847     /**
7848      * Finds and returns the relative index of the first mismatch between two
7849      * {@code char} arrays over the specified ranges, otherwise return -1 if no
7850      * mismatch is found.  The index will be in the range of 0 (inclusive) up to
7851      * the length (inclusive) of the smaller range.
7852      *
7853      * <p>If the two arrays, over the specified ranges, share a common prefix
7854      * then the returned relative index is the length of the common prefix and
7855      * it follows that there is a mismatch between the two elements at that
7856      * relative index within the respective arrays.
7857      * If one array is a proper prefix of the other, over the specified ranges,
7858      * then the returned relative index is the length of the smaller range and
7859      * it follows that the relative index is only valid for the array with the
7860      * larger range.
7861      * Otherwise, there is no mismatch.
7862      *
7863      * <p>Two non-{@code null} arrays, {@code a} and {@code b} with specified
7864      * ranges [{@code aFromIndex}, {@code atoIndex}) and
7865      * [{@code bFromIndex}, {@code btoIndex}) respectively, 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(aToIndex - aFromIndex, bToIndex - bFromIndex) &&
7870      *     Arrays.equals(a, aFromIndex, aFromIndex + pl, b, bFromIndex, bFromIndex + pl) &&
7871      *     a[aFromIndex + pl] != b[bFromIndex + 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} with specified
7877      * ranges [{@code aFromIndex}, {@code atoIndex}) and
7878      * [{@code bFromIndex}, {@code btoIndex}) respectively, share a proper
7879      * if the following expression is true:
7880      * <pre>{@code
7881      *     (aToIndex - aFromIndex) != (bToIndex - bFromIndex) &&
7882      *     Arrays.equals(a, 0, Math.min(aToIndex - aFromIndex, bToIndex - bFromIndex),
7883      *                   b, 0, Math.min(aToIndex - aFromIndex, bToIndex - bFromIndex))
7884      * }</pre>
7885      *
7886      * @param a the first array to be tested for a mismatch
7887      * @param aFromIndex the index (inclusive) of the first element in the
7888      *                   first array to be tested
7889      * @param aToIndex the index (exclusive) of the last element in the
7890      *                 first array to be tested
7891      * @param b the second array to be tested for a mismatch
7892      * @param bFromIndex the index (inclusive) of the first element in the
7893      *                   second array to be tested
7894      * @param bToIndex the index (exclusive) of the last element in the
7895      *                 second array to be tested
7896      * @return the relative index of the first mismatch between the two arrays
7897      *         over the specified ranges, otherwise {@code -1}.
7898      * @throws IllegalArgumentException
7899      *         if {@code aFromIndex > aToIndex} or
7900      *         if {@code bFromIndex > bToIndex}
7901      * @throws ArrayIndexOutOfBoundsException
7902      *         if {@code aFromIndex < 0 or aToIndex > a.length} or
7903      *         if {@code bFromIndex < 0 or bToIndex > b.length}
7904      * @throws NullPointerException
7905      *         if either array is {@code null}
7906      * @since 9
7907      */
7908     public static int mismatch(char[] a, int aFromIndex, int aToIndex,
7909                                char[] b, int bFromIndex, int bToIndex) {
7910         rangeCheck(a.length, aFromIndex, aToIndex);
7911         rangeCheck(b.length, bFromIndex, bToIndex);
7912 
7913         int aLength = aToIndex - aFromIndex;
7914         int bLength = bToIndex - bFromIndex;
7915         int length = Math.min(aLength, bLength);
7916         for (int i = 0; i < length; i++) {
7917             if (a[aFromIndex++] != b[bFromIndex++]) return i;
7918         }
7919 
7920         return aLength != bLength ? length : -1;
7921     }
7922 
7923     // Mismatch short
7924 
7925     /**
7926      * Finds and returns the index of the first mismatch between two {@code short}
7927      * arrays, otherwise return -1 if no mismatch is found.  The index will be
7928      * in the range of 0 (inclusive) up to the length (inclusive) of the smaller
7929      * array.
7930      *
7931      * <p>If the two arrays share a common prefix then the returned index is the
7932      * length of the common prefix and it follows that there is a mismatch
7933      * between the two elements at that index within the respective arrays.
7934      * If one array is a proper prefix of the other then the returned index is
7935      * the length of the smaller array and it follows that the index is only
7936      * valid for the larger array.
7937      * Otherwise, there is no mismatch.
7938      *
7939      * <p>Two non-{@code null} arrays, {@code a} and {@code b}, share a common
7940      * prefix of length {@code pl} if the following expression is true:
7941      * <pre>{@code
7942      *     pl >= 0 &&
7943      *     pl < Math.min(a.length, b.length) &&
7944      *     Arrays.equals(a, 0, pl, b, 0, pl) &&
7945      *     a[pl] != b[pl]
7946      * }</pre>
7947      * Note that a common prefix length of {@code 0} indicates that the first
7948      * elements from each array mismatch.
7949      *
7950      * <p>Two non-{@code null} arrays, {@code a} and {@code b}, share a proper
7951      * prefix if the following expression is true:
7952      * <pre>{@code
7953      *     a.length != b.length &&
7954      *     Arrays.equals(a, 0, Math.min(a.length, b.length),
7955      *                   b, 0, Math.min(a.length, b.length))
7956      * }</pre>
7957      *
7958      * @param a the first array to be tested for a mismatch
7959      * @param b the second array to be tested for a mismatch
7960      * @return the index of the first mismatch between the two arrays,
7961      *         otherwise {@code -1}.
7962      * @throws NullPointerException
7963      *         if either array is {@code null}
7964      * @since 9
7965      */
7966     public static int mismatch(short[] a, short[] b) {
7967         int length = Math.min(a.length, b.length); // Check null array refs
7968         if (a == b)
7969             return -1;
7970 
7971         for (int i = 0; i < length; i++) {
7972             if (a[i] != b[i]) return i;
7973         }
7974 
7975         return a.length != b.length ? length : -1;
7976     }
7977 
7978     /**
7979      * Finds and returns the relative index of the first mismatch between two
7980      * {@code short} arrays over the specified ranges, otherwise return -1 if no
7981      * mismatch is found.  The index will be in the range of 0 (inclusive) up to
7982      * the length (inclusive) of the smaller range.
7983      *
7984      * <p>If the two arrays, over the specified ranges, share a common prefix
7985      * then the returned relative index is the length of the common prefix and
7986      * it follows that there is a mismatch between the two elements at that
7987      * relative index within the respective arrays.
7988      * If one array is a proper prefix of the other, over the specified ranges,
7989      * then the returned relative index is the length of the smaller range and
7990      * it follows that the relative index is only valid for the array with the
7991      * larger range.
7992      * Otherwise, there is no mismatch.
7993      *
7994      * <p>Two non-{@code null} arrays, {@code a} and {@code b} with specified
7995      * ranges [{@code aFromIndex}, {@code atoIndex}) and
7996      * [{@code bFromIndex}, {@code btoIndex}) respectively, share a common
7997      * prefix of length {@code pl} if the following expression is true:
7998      * <pre>{@code
7999      *     pl >= 0 &&
8000      *     pl < Math.min(aToIndex - aFromIndex, bToIndex - bFromIndex) &&
8001      *     Arrays.equals(a, aFromIndex, aFromIndex + pl, b, bFromIndex, bFromIndex + pl) &&
8002      *     a[aFromIndex + pl] != b[bFromIndex + pl]
8003      * }</pre>
8004      * Note that a common prefix length of {@code 0} indicates that the first
8005      * elements from each array mismatch.
8006      *
8007      * <p>Two non-{@code null} arrays, {@code a} and {@code b} with specified
8008      * ranges [{@code aFromIndex}, {@code atoIndex}) and
8009      * [{@code bFromIndex}, {@code btoIndex}) respectively, share a proper
8010      * if the following expression is true:
8011      * <pre>{@code
8012      *     (aToIndex - aFromIndex) != (bToIndex - bFromIndex) &&
8013      *     Arrays.equals(a, 0, Math.min(aToIndex - aFromIndex, bToIndex - bFromIndex),
8014      *                   b, 0, Math.min(aToIndex - aFromIndex, bToIndex - bFromIndex))
8015      * }</pre>
8016      *
8017      * @param a the first array to be tested for a mismatch
8018      * @param aFromIndex the index (inclusive) of the first element in the
8019      *                   first array to be tested
8020      * @param aToIndex the index (exclusive) of the last element in the
8021      *                 first array to be tested
8022      * @param b the second array to be tested for a mismatch
8023      * @param bFromIndex the index (inclusive) of the first element in the
8024      *                   second array to be tested
8025      * @param bToIndex the index (exclusive) of the last element in the
8026      *                 second array to be tested
8027      * @return the relative index of the first mismatch between the two arrays
8028      *         over the specified ranges, otherwise {@code -1}.
8029      * @throws IllegalArgumentException
8030      *         if {@code aFromIndex > aToIndex} or
8031      *         if {@code bFromIndex > bToIndex}
8032      * @throws ArrayIndexOutOfBoundsException
8033      *         if {@code aFromIndex < 0 or aToIndex > a.length} or
8034      *         if {@code bFromIndex < 0 or bToIndex > b.length}
8035      * @throws NullPointerException
8036      *         if either array is {@code null}
8037      * @since 9
8038      */
8039     public static int mismatch(short[] a, int aFromIndex, int aToIndex,
8040                                short[] b, int bFromIndex, int bToIndex) {
8041         rangeCheck(a.length, aFromIndex, aToIndex);
8042         rangeCheck(b.length, bFromIndex, bToIndex);
8043 
8044         int aLength = aToIndex - aFromIndex;
8045         int bLength = bToIndex - bFromIndex;
8046         int length = Math.min(aLength, bLength);
8047         for (int i = 0; i < length; i++) {
8048             if (a[aFromIndex++] != b[bFromIndex++]) return i;
8049         }
8050 
8051         return aLength != bLength ? length : -1;
8052     }
8053 
8054     // Mismatch int
8055 
8056     /**
8057      * Finds and returns the index of the first mismatch between two {@code int}
8058      * arrays, otherwise return -1 if no mismatch is found.  The index will be
8059      * in the range of 0 (inclusive) up to the length (inclusive) of the smaller
8060      * array.
8061      *
8062      * <p>If the two arrays share a common prefix then the returned index is the
8063      * length of the common prefix and it follows that there is a mismatch
8064      * between the two elements at that index within the respective arrays.
8065      * If one array is a proper prefix of the other then the returned index is
8066      * the length of the smaller array and it follows that the index is only
8067      * valid for the larger array.
8068      * Otherwise, there is no mismatch.
8069      *
8070      * <p>Two non-{@code null} arrays, {@code a} and {@code b}, share a common
8071      * prefix of length {@code pl} if the following expression is true:
8072      * <pre>{@code
8073      *     pl >= 0 &&
8074      *     pl < Math.min(a.length, b.length) &&
8075      *     Arrays.equals(a, 0, pl, b, 0, pl) &&
8076      *     a[pl] != b[pl]
8077      * }</pre>
8078      * Note that a common prefix length of {@code 0} indicates that the first
8079      * elements from each array mismatch.
8080      *
8081      * <p>Two non-{@code null} arrays, {@code a} and {@code b}, share a proper
8082      * prefix if the following expression is true:
8083      * <pre>{@code
8084      *     a.length != b.length &&
8085      *     Arrays.equals(a, 0, Math.min(a.length, b.length),
8086      *                   b, 0, Math.min(a.length, b.length))
8087      * }</pre>
8088      *
8089      * @param a the first array to be tested for a mismatch
8090      * @param b the second array to be tested for a mismatch
8091      * @return the index of the first mismatch between the two arrays,
8092      *         otherwise {@code -1}.
8093      * @throws NullPointerException
8094      *         if either array is {@code null}
8095      * @since 9
8096      */
8097     public static int mismatch(int[] a, int[] b) {
8098         int length = Math.min(a.length, b.length); // Check null array refs
8099         if (a == b)
8100             return -1;
8101 
8102         for (int i = 0; i < length; i++) {
8103             if (a[i] != b[i]) return i;
8104         }
8105 
8106         return a.length != b.length ? length : -1;
8107     }
8108 
8109     /**
8110      * Finds and returns the relative index of the first mismatch between two
8111      * {@code int} arrays over the specified ranges, otherwise return -1 if no
8112      * mismatch is found.  The index will be in the range of 0 (inclusive) up to
8113      * the length (inclusive) of the smaller range.
8114      *
8115      * <p>If the two arrays, over the specified ranges, share a common prefix
8116      * then the returned relative index is the length of the common prefix and
8117      * it follows that there is a mismatch between the two elements at that
8118      * relative index within the respective arrays.
8119      * If one array is a proper prefix of the other, over the specified ranges,
8120      * then the returned relative index is the length of the smaller range and
8121      * it follows that the relative index is only valid for the array with the
8122      * larger range.
8123      * Otherwise, there is no mismatch.
8124      *
8125      * <p>Two non-{@code null} arrays, {@code a} and {@code b} with specified
8126      * ranges [{@code aFromIndex}, {@code atoIndex}) and
8127      * [{@code bFromIndex}, {@code btoIndex}) respectively, share a common
8128      * prefix of length {@code pl} if the following expression is true:
8129      * <pre>{@code
8130      *     pl >= 0 &&
8131      *     pl < Math.min(aToIndex - aFromIndex, bToIndex - bFromIndex) &&
8132      *     Arrays.equals(a, aFromIndex, aFromIndex + pl, b, bFromIndex, bFromIndex + pl) &&
8133      *     a[aFromIndex + pl] != b[bFromIndex + pl]
8134      * }</pre>
8135      * Note that a common prefix length of {@code 0} indicates that the first
8136      * elements from each array mismatch.
8137      *
8138      * <p>Two non-{@code null} arrays, {@code a} and {@code b} with specified
8139      * ranges [{@code aFromIndex}, {@code atoIndex}) and
8140      * [{@code bFromIndex}, {@code btoIndex}) respectively, share a proper
8141      * if the following expression is true:
8142      * <pre>{@code
8143      *     (aToIndex - aFromIndex) != (bToIndex - bFromIndex) &&
8144      *     Arrays.equals(a, 0, Math.min(aToIndex - aFromIndex, bToIndex - bFromIndex),
8145      *                   b, 0, Math.min(aToIndex - aFromIndex, bToIndex - bFromIndex))
8146      * }</pre>
8147      *
8148      * @param a the first array to be tested for a mismatch
8149      * @param aFromIndex the index (inclusive) of the first element in the
8150      *                   first array to be tested
8151      * @param aToIndex the index (exclusive) of the last element in the
8152      *                 first array to be tested
8153      * @param b the second array to be tested for a mismatch
8154      * @param bFromIndex the index (inclusive) of the first element in the
8155      *                   second array to be tested
8156      * @param bToIndex the index (exclusive) of the last element in the
8157      *                 second array to be tested
8158      * @return the relative index of the first mismatch between the two arrays
8159      *         over the specified ranges, otherwise {@code -1}.
8160      * @throws IllegalArgumentException
8161      *         if {@code aFromIndex > aToIndex} or
8162      *         if {@code bFromIndex > bToIndex}
8163      * @throws ArrayIndexOutOfBoundsException
8164      *         if {@code aFromIndex < 0 or aToIndex > a.length} or
8165      *         if {@code bFromIndex < 0 or bToIndex > b.length}
8166      * @throws NullPointerException
8167      *         if either array is {@code null}
8168      * @since 9
8169      */
8170     public static int mismatch(int[] a, int aFromIndex, int aToIndex,
8171                                int[] b, int bFromIndex, int bToIndex) {
8172         rangeCheck(a.length, aFromIndex, aToIndex);
8173         rangeCheck(b.length, bFromIndex, bToIndex);
8174 
8175         int aLength = aToIndex - aFromIndex;
8176         int bLength = bToIndex - bFromIndex;
8177         int length = Math.min(aLength, bLength);
8178         for (int i = 0; i < length; i++) {
8179             if (a[aFromIndex++] != b[bFromIndex++]) return i;
8180         }
8181 
8182         return aLength != bLength ? length : -1;
8183     }
8184 
8185     // Mismatch long
8186 
8187     /**
8188      * Finds and returns the index of the first mismatch between two {@code long}
8189      * arrays, otherwise return -1 if no mismatch is found.  The index will be
8190      * in the range of 0 (inclusive) up to the length (inclusive) of the smaller
8191      * array.
8192      *
8193      * <p>If the two arrays share a common prefix then the returned index is the
8194      * length of the common prefix and it follows that there is a mismatch
8195      * between the two elements at that index within the respective arrays.
8196      * If one array is a proper prefix of the other then the returned index is
8197      * the length of the smaller array and it follows that the index is only
8198      * valid for the larger array.
8199      * Otherwise, there is no mismatch.
8200      *
8201      * <p>Two non-{@code null} arrays, {@code a} and {@code b}, share a common
8202      * prefix of length {@code pl} if the following expression is true:
8203      * <pre>{@code
8204      *     pl >= 0 &&
8205      *     pl < Math.min(a.length, b.length) &&
8206      *     Arrays.equals(a, 0, pl, b, 0, pl) &&
8207      *     a[pl] != b[pl]
8208      * }</pre>
8209      * Note that a common prefix length of {@code 0} indicates that the first
8210      * elements from each array mismatch.
8211      *
8212      * <p>Two non-{@code null} arrays, {@code a} and {@code b}, share a proper
8213      * prefix if the following expression is true:
8214      * <pre>{@code
8215      *     a.length != b.length &&
8216      *     Arrays.equals(a, 0, Math.min(a.length, b.length),
8217      *                   b, 0, Math.min(a.length, b.length))
8218      * }</pre>
8219      *
8220      * @param a the first array to be tested for a mismatch
8221      * @param b the second array to be tested for a mismatch
8222      * @return the index of the first mismatch between the two arrays,
8223      *         otherwise {@code -1}.
8224      * @throws NullPointerException
8225      *         if either array is {@code null}
8226      * @since 9
8227      */
8228     public static int mismatch(long[] a, long[] b) {
8229         int length = Math.min(a.length, b.length); // Check null array refs
8230         if (a == b)
8231             return -1;
8232 
8233         for (int i = 0; i < length; i++) {
8234             if (a[i] != b[i]) return i;
8235         }
8236 
8237         return a.length != b.length ? length : -1;
8238     }
8239 
8240     /**
8241      * Finds and returns the relative index of the first mismatch between two
8242      * {@code long} arrays over the specified ranges, otherwise return -1 if no
8243      * mismatch is found.  The index will be in the range of 0 (inclusive) up to
8244      * the length (inclusive) of the smaller range.
8245      *
8246      * <p>If the two arrays, over the specified ranges, share a common prefix
8247      * then the returned relative index is the length of the common prefix and
8248      * it follows that there is a mismatch between the two elements at that
8249      * relative index within the respective arrays.
8250      * If one array is a proper prefix of the other, over the specified ranges,
8251      * then the returned relative index is the length of the smaller range and
8252      * it follows that the relative index is only valid for the array with the
8253      * larger range.
8254      * Otherwise, there is no mismatch.
8255      *
8256      * <p>Two non-{@code null} arrays, {@code a} and {@code b} with specified
8257      * ranges [{@code aFromIndex}, {@code atoIndex}) and
8258      * [{@code bFromIndex}, {@code btoIndex}) respectively, share a common
8259      * prefix of length {@code pl} if the following expression is true:
8260      * <pre>{@code
8261      *     pl >= 0 &&
8262      *     pl < Math.min(aToIndex - aFromIndex, bToIndex - bFromIndex) &&
8263      *     Arrays.equals(a, aFromIndex, aFromIndex + pl, b, bFromIndex, bFromIndex + pl) &&
8264      *     a[aFromIndex + pl] != b[bFromIndex + pl]
8265      * }</pre>
8266      * Note that a common prefix length of {@code 0} indicates that the first
8267      * elements from each array mismatch.
8268      *
8269      * <p>Two non-{@code null} arrays, {@code a} and {@code b} with specified
8270      * ranges [{@code aFromIndex}, {@code atoIndex}) and
8271      * [{@code bFromIndex}, {@code btoIndex}) respectively, share a proper
8272      * if the following expression is true:
8273      * <pre>{@code
8274      *     (aToIndex - aFromIndex) != (bToIndex - bFromIndex) &&
8275      *     Arrays.equals(a, 0, Math.min(aToIndex - aFromIndex, bToIndex - bFromIndex),
8276      *                   b, 0, Math.min(aToIndex - aFromIndex, bToIndex - bFromIndex))
8277      * }</pre>
8278      *
8279      * @param a the first array to be tested for a mismatch
8280      * @param aFromIndex the index (inclusive) of the first element in the
8281      *                   first array to be tested
8282      * @param aToIndex the index (exclusive) of the last element in the
8283      *                 first array to be tested
8284      * @param b the second array to be tested for a mismatch
8285      * @param bFromIndex the index (inclusive) of the first element in the
8286      *                   second array to be tested
8287      * @param bToIndex the index (exclusive) of the last element in the
8288      *                 second array to be tested
8289      * @return the relative index of the first mismatch between the two arrays
8290      *         over the specified ranges, otherwise {@code -1}.
8291      * @throws IllegalArgumentException
8292      *         if {@code aFromIndex > aToIndex} or
8293      *         if {@code bFromIndex > bToIndex}
8294      * @throws ArrayIndexOutOfBoundsException
8295      *         if {@code aFromIndex < 0 or aToIndex > a.length} or
8296      *         if {@code bFromIndex < 0 or bToIndex > b.length}
8297      * @throws NullPointerException
8298      *         if either array is {@code null}
8299      * @since 9
8300      */
8301     public static int mismatch(long[] a, int aFromIndex, int aToIndex,
8302                                long[] b, int bFromIndex, int bToIndex) {
8303         rangeCheck(a.length, aFromIndex, aToIndex);
8304         rangeCheck(b.length, bFromIndex, bToIndex);
8305 
8306         int aLength = aToIndex - aFromIndex;
8307         int bLength = bToIndex - bFromIndex;
8308         int length = Math.min(aLength, bLength);
8309         for (int i = 0; i < length; i++) {
8310             if (a[aFromIndex++] != b[bFromIndex++]) return i;
8311         }
8312 
8313         return aLength != bLength ? length : -1;
8314     }
8315 
8316     // Mismatch float
8317 
8318     /**
8319      * Finds and returns the index of the first mismatch between two {@code float}
8320      * arrays, otherwise return -1 if no mismatch is found.  The index will be
8321      * in the range of 0 (inclusive) up to the length (inclusive) of the smaller
8322      * array.
8323      *
8324      * <p>If the two arrays share a common prefix then the returned index is the
8325      * length of the common prefix and it follows that there is a mismatch
8326      * between the two elements at that index within the respective arrays.
8327      * If one array is a proper prefix of the other then the returned index is
8328      * the length of the smaller array and it follows that the index is only
8329      * valid for the larger array.
8330      * Otherwise, there is no mismatch.
8331      *
8332      * <p>Two non-{@code null} arrays, {@code a} and {@code b}, share a common
8333      * prefix of length {@code pl} if the following expression is true:
8334      * <pre>{@code
8335      *     pl >= 0 &&
8336      *     pl < Math.min(a.length, b.length) &&
8337      *     Arrays.equals(a, 0, pl, b, 0, pl) &&
8338      *     Float.compare(a[pl], b[pl]) != 0
8339      * }</pre>
8340      * Note that a common prefix length of {@code 0} indicates that the first
8341      * elements from each array mismatch.
8342      *
8343      * <p>Two non-{@code null} arrays, {@code a} and {@code b}, share a proper
8344      * prefix if the following expression is true:
8345      * <pre>{@code
8346      *     a.length != b.length &&
8347      *     Arrays.equals(a, 0, Math.min(a.length, b.length),
8348      *                   b, 0, Math.min(a.length, b.length))
8349      * }</pre>
8350      *
8351      * @param a the first array to be tested for a mismatch
8352      * @param b the second array to be tested for a mismatch
8353      * @return the index of the first mismatch between the two arrays,
8354      *         otherwise {@code -1}.
8355      * @throws NullPointerException
8356      *         if either array is {@code null}
8357      * @since 9
8358      */
8359     public static int mismatch(float[] a, float[] b) {
8360         int length = Math.min(a.length, b.length); // Check null array refs
8361         if (a == b)
8362             return -1;
8363 
8364         for (int i = 0; i < length; i++) {
8365             float va = a[i], vb = b[i];
8366             if (Float.floatToRawIntBits(va) != Float.floatToRawIntBits(vb))
8367                 if (!Float.isNaN(va) || !Float.isNaN(vb))
8368                     return i;
8369         }
8370 
8371         return a.length != b.length ? length : -1;
8372     }
8373 
8374     /**
8375      * Finds and returns the relative index of the first mismatch between two
8376      * {@code float} arrays over the specified ranges, otherwise return -1 if no
8377      * mismatch is found.  The index will be in the range of 0 (inclusive) up to
8378      * the length (inclusive) of the smaller range.
8379      *
8380      * <p>If the two arrays, over the specified ranges, share a common prefix
8381      * then the returned relative index is the length of the common prefix and
8382      * it follows that there is a mismatch between the two elements at that
8383      * relative index within the respective arrays.
8384      * If one array is a proper prefix of the other, over the specified ranges,
8385      * then the returned relative index is the length of the smaller range and
8386      * it follows that the relative index is only valid for the array with the
8387      * larger range.
8388      * Otherwise, there is no mismatch.
8389      *
8390      * <p>Two non-{@code null} arrays, {@code a} and {@code b} with specified
8391      * ranges [{@code aFromIndex}, {@code atoIndex}) and
8392      * [{@code bFromIndex}, {@code btoIndex}) respectively, share a common
8393      * prefix of length {@code pl} if the following expression is true:
8394      * <pre>{@code
8395      *     pl >= 0 &&
8396      *     pl < Math.min(aToIndex - aFromIndex, bToIndex - bFromIndex) &&
8397      *     Arrays.equals(a, aFromIndex, aFromIndex + pl, b, bFromIndex, bFromIndex + pl) &&
8398      *     Float.compare(a[aFromIndex + pl], b[bFromIndex + pl]) != 0
8399      * }</pre>
8400      * Note that a common prefix length of {@code 0} indicates that the first
8401      * elements from each array mismatch.
8402      *
8403      * <p>Two non-{@code null} arrays, {@code a} and {@code b} with specified
8404      * ranges [{@code aFromIndex}, {@code atoIndex}) and
8405      * [{@code bFromIndex}, {@code btoIndex}) respectively, share a proper
8406      * if the following expression is true:
8407      * <pre>{@code
8408      *     (aToIndex - aFromIndex) != (bToIndex - bFromIndex) &&
8409      *     Arrays.equals(a, 0, Math.min(aToIndex - aFromIndex, bToIndex - bFromIndex),
8410      *                   b, 0, Math.min(aToIndex - aFromIndex, bToIndex - bFromIndex))
8411      * }</pre>
8412      *
8413      * @param a the first array to be tested for a mismatch
8414      * @param aFromIndex the index (inclusive) of the first element in the
8415      *                   first array to be tested
8416      * @param aToIndex the index (exclusive) of the last element in the
8417      *                 first array to be tested
8418      * @param b the second array to be tested for a mismatch
8419      * @param bFromIndex the index (inclusive) of the first element in the
8420      *                   second array to be tested
8421      * @param bToIndex the index (exclusive) of the last element in the
8422      *                 second array to be tested
8423      * @return the relative index of the first mismatch between the two arrays
8424      *         over the specified ranges, otherwise {@code -1}.
8425      * @throws IllegalArgumentException
8426      *         if {@code aFromIndex > aToIndex} or
8427      *         if {@code bFromIndex > bToIndex}
8428      * @throws ArrayIndexOutOfBoundsException
8429      *         if {@code aFromIndex < 0 or aToIndex > a.length} or
8430      *         if {@code bFromIndex < 0 or bToIndex > b.length}
8431      * @throws NullPointerException
8432      *         if either array is {@code null}
8433      * @since 9
8434      */
8435     public static int mismatch(float[] a, int aFromIndex, int aToIndex,
8436                                float[] b, int bFromIndex, int bToIndex) {
8437         rangeCheck(a.length, aFromIndex, aToIndex);
8438         rangeCheck(b.length, bFromIndex, bToIndex);
8439 
8440         int aLength = aToIndex - aFromIndex;
8441         int bLength = bToIndex - bFromIndex;
8442         int length = Math.min(aLength, bLength);
8443         for (int i = 0; i < length; i++) {
8444             float va = a[aFromIndex++], vb = b[bFromIndex++];
8445             if (Float.floatToRawIntBits(va) != Float.floatToRawIntBits(vb))
8446                 if (!Float.isNaN(va) || !Float.isNaN(vb))
8447                     return i;
8448         }
8449 
8450         return aLength != bLength ? length : -1;
8451     }
8452 
8453     // Mismatch double
8454 
8455     /**
8456      * Finds and returns the index of the first mismatch between two
8457      * {@code double} arrays, otherwise return -1 if no mismatch is found.  The
8458      * index will be in the range of 0 (inclusive) up to the length (inclusive)
8459      * of the smaller array.
8460      *
8461      * <p>If the two arrays share a common prefix then the returned index is the
8462      * length of the common prefix and it follows that there is a mismatch
8463      * between the two elements at that index within the respective arrays.
8464      * If one array is a proper prefix of the other then the returned index is
8465      * the length of the smaller array and it follows that the index is only
8466      * valid for the larger array.
8467      * Otherwise, there is no mismatch.
8468      *
8469      * <p>Two non-{@code null} arrays, {@code a} and {@code b}, share a common
8470      * prefix of length {@code pl} if the following expression is true:
8471      * <pre>{@code
8472      *     pl >= 0 &&
8473      *     pl < Math.min(a.length, b.length) &&
8474      *     Arrays.equals(a, 0, pl, b, 0, pl) &&
8475      *     Double.compare(a[pl], b[pl]) != 0
8476      * }</pre>
8477      * Note that a common prefix length of {@code 0} indicates that the first
8478      * elements from each array mismatch.
8479      *
8480      * <p>Two non-{@code null} arrays, {@code a} and {@code b}, share a proper
8481      * prefix if the following expression is true:
8482      * <pre>{@code
8483      *     a.length != b.length &&
8484      *     Arrays.equals(a, 0, Math.min(a.length, b.length),
8485      *                   b, 0, Math.min(a.length, b.length))
8486      * }</pre>
8487      *
8488      * @param a the first array to be tested for a mismatch
8489      * @param b the second array to be tested for a mismatch
8490      * @return the index of the first mismatch between the two arrays,
8491      *         otherwise {@code -1}.
8492      * @throws NullPointerException
8493      *         if either array is {@code null}
8494      * @since 9
8495      */
8496     public static int mismatch(double[] a, double[] b) {
8497         int length = Math.min(a.length, b.length); // Check null array refs
8498         if (a == b)
8499             return -1;
8500 
8501         for (int i = 0; i < length; i++) {
8502             double va = a[i], vb = b[i];
8503             if (Double.doubleToRawLongBits(va) != Double.doubleToRawLongBits(vb))
8504                 if (!Double.isNaN(va) || !Double.isNaN(vb))
8505                     return i;
8506         }
8507 
8508         return a.length != b.length ? length : -1;
8509     }
8510 
8511     /**
8512      * Finds and returns the relative index of the first mismatch between two
8513      * {@code double} arrays over the specified ranges, otherwise return -1 if
8514      * no mismatch is found.  The index will be in the range of 0 (inclusive) up
8515      * to the length (inclusive) of the smaller range.
8516      *
8517      * <p>If the two arrays, over the specified ranges, share a common prefix
8518      * then the returned relative index is the length of the common prefix and
8519      * it follows that there is a mismatch between the two elements at that
8520      * relative index within the respective arrays.
8521      * If one array is a proper prefix of the other, over the specified ranges,
8522      * then the returned relative index is the length of the smaller range and
8523      * it follows that the relative index is only valid for the array with the
8524      * larger range.
8525      * Otherwise, there is no mismatch.
8526      *
8527      * <p>Two non-{@code null} arrays, {@code a} and {@code b} with specified
8528      * ranges [{@code aFromIndex}, {@code atoIndex}) and
8529      * [{@code bFromIndex}, {@code btoIndex}) respectively, share a common
8530      * prefix of length {@code pl} if the following expression is true:
8531      * <pre>{@code
8532      *     pl >= 0 &&
8533      *     pl < Math.min(aToIndex - aFromIndex, bToIndex - bFromIndex) &&
8534      *     Arrays.equals(a, aFromIndex, aFromIndex + pl, b, bFromIndex, bFromIndex + pl) &&
8535      *     Double.compare(a[aFromIndex + pl], b[bFromIndex + pl]) != 0
8536      * }</pre>
8537      * Note that a common prefix length of {@code 0} indicates that the first
8538      * elements from each array mismatch.
8539      *
8540      * <p>Two non-{@code null} arrays, {@code a} and {@code b} with specified
8541      * ranges [{@code aFromIndex}, {@code atoIndex}) and
8542      * [{@code bFromIndex}, {@code btoIndex}) respectively, share a proper
8543      * if the following expression is true:
8544      * <pre>{@code
8545      *     (aToIndex - aFromIndex) != (bToIndex - bFromIndex) &&
8546      *     Arrays.equals(a, 0, Math.min(aToIndex - aFromIndex, bToIndex - bFromIndex),
8547      *                   b, 0, Math.min(aToIndex - aFromIndex, bToIndex - bFromIndex))
8548      * }</pre>
8549      *
8550      * @param a the first array to be tested for a mismatch
8551      * @param aFromIndex the index (inclusive) of the first element in the
8552      *                   first array to be tested
8553      * @param aToIndex the index (exclusive) of the last element in the
8554      *                 first array to be tested
8555      * @param b the second array to be tested for a mismatch
8556      * @param bFromIndex the index (inclusive) of the first element in the
8557      *                   second array to be tested
8558      * @param bToIndex the index (exclusive) of the last element in the
8559      *                 second array to be tested
8560      * @return the relative index of the first mismatch between the two arrays
8561      *         over the specified ranges, otherwise {@code -1}.
8562      * @throws IllegalArgumentException
8563      *         if {@code aFromIndex > aToIndex} or
8564      *         if {@code bFromIndex > bToIndex}
8565      * @throws ArrayIndexOutOfBoundsException
8566      *         if {@code aFromIndex < 0 or aToIndex > a.length} or
8567      *         if {@code bFromIndex < 0 or bToIndex > b.length}
8568      * @throws NullPointerException
8569      *         if either array is {@code null}
8570      * @since 9
8571      */
8572     public static int mismatch(double[] a, int aFromIndex, int aToIndex,
8573                                double[] b, int bFromIndex, int bToIndex) {
8574         rangeCheck(a.length, aFromIndex, aToIndex);
8575         rangeCheck(b.length, bFromIndex, bToIndex);
8576 
8577         int aLength = aToIndex - aFromIndex;
8578         int bLength = bToIndex - bFromIndex;
8579         int length = Math.min(aLength, bLength);
8580         for (int i = 0; i < length; i++) {
8581             double va = a[aFromIndex++], vb = b[bFromIndex++];
8582             if (Double.doubleToRawLongBits(va) != Double.doubleToRawLongBits(vb))
8583                 if (!Double.isNaN(va) || !Double.isNaN(vb))
8584                     return i;
8585         }
8586 
8587         return aLength != bLength ? length : -1;
8588     }
8589 
8590     // Mismatch objects
8591 
8592     /**
8593      * Finds and returns the index of the first mismatch between two
8594      * {@code Object} arrays, otherwise return -1 if no mismatch is found.  The
8595      * index will be in the range of 0 (inclusive) up to the length (inclusive)
8596      * of the smaller array.
8597      *
8598      * <p>If the two arrays share a common prefix then the returned index is the
8599      * length of the common prefix and it follows that there is a mismatch
8600      * between the two elements at that index within the respective arrays.
8601      * If one array is a proper prefix of the other then the returned index is
8602      * the length of the smaller array and it follows that the index is only
8603      * valid for the larger array.
8604      * Otherwise, there is no mismatch.
8605      *
8606      * <p>Two non-{@code null} arrays, {@code a} and {@code b}, share a common
8607      * prefix of length {@code pl} if the following expression is true:
8608      * <pre>{@code
8609      *     pl >= 0 &&
8610      *     pl < Math.min(a.length, b.length) &&
8611      *     Arrays.equals(a, 0, pl, b, 0, pl) &&
8612      *     !Objects.equals(a[pl], b[pl])
8613      * }</pre>
8614      * Note that a common prefix length of {@code 0} indicates that the first
8615      * elements from each array mismatch.
8616      *
8617      * <p>Two non-{@code null} arrays, {@code a} and {@code b}, share a proper
8618      * prefix if the following expression is true:
8619      * <pre>{@code
8620      *     a.length != b.length &&
8621      *     Arrays.equals(a, 0, Math.min(a.length, b.length),
8622      *                   b, 0, Math.min(a.length, b.length))
8623      * }</pre>
8624      *
8625      * @param a the first array to be tested for a mismatch
8626      * @param b the second array to be tested for a mismatch
8627      * @return the index of the first mismatch between the two arrays,
8628      *         otherwise {@code -1}.
8629      * @throws NullPointerException
8630      *         if either array is {@code null}
8631      * @since 9
8632      */
8633     public static int mismatch(Object[] a, Object[] b) {
8634         int length = Math.min(a.length, b.length); // Check null array refs
8635         if (a == b)
8636             return -1;
8637 
8638         for (int i = 0; i < length; i++) {
8639             if (!Objects.equals(a[i], b[i]))
8640                 return i;
8641         }
8642 
8643         return a.length != b.length ? length : -1;
8644     }
8645 
8646     /**
8647      * Finds and returns the relative index of the first mismatch between two
8648      * {@code Object} arrays over the specified ranges, otherwise return -1 if
8649      * no mismatch is found.  The index will be in the range of 0 (inclusive) up
8650      * to the length (inclusive) of the smaller range.
8651      *
8652      * <p>If the two arrays, over the specified ranges, share a common prefix
8653      * then the returned relative index is the length of the common prefix and
8654      * it follows that there is a mismatch between the two elements at that
8655      * relative index within the respective arrays.
8656      * If one array is a proper prefix of the other, over the specified ranges,
8657      * then the returned relative index is the length of the smaller range and
8658      * it follows that the relative index is only valid for the array with the
8659      * larger range.
8660      * Otherwise, there is no mismatch.
8661      *
8662      * <p>Two non-{@code null} arrays, {@code a} and {@code b} with specified
8663      * ranges [{@code aFromIndex}, {@code atoIndex}) and
8664      * [{@code bFromIndex}, {@code btoIndex}) respectively, share a common
8665      * prefix of length {@code pl} if the following expression is true:
8666      * <pre>{@code
8667      *     pl >= 0 &&
8668      *     pl < Math.min(aToIndex - aFromIndex, bToIndex - bFromIndex) &&
8669      *     Arrays.equals(a, aFromIndex, aFromIndex + pl, b, bFromIndex, bFromIndex + pl) &&
8670      *     !Objects.equals(a[aFromIndex + pl], b[bFromIndex + pl])
8671      * }</pre>
8672      * Note that a common prefix length of {@code 0} indicates that the first
8673      * elements from each array mismatch.
8674      *
8675      * <p>Two non-{@code null} arrays, {@code a} and {@code b} with specified
8676      * ranges [{@code aFromIndex}, {@code atoIndex}) and
8677      * [{@code bFromIndex}, {@code btoIndex}) respectively, share a proper
8678      * if the following expression is true:
8679      * <pre>{@code
8680      *     (aToIndex - aFromIndex) != (bToIndex - bFromIndex) &&
8681      *     Arrays.equals(a, 0, Math.min(aToIndex - aFromIndex, bToIndex - bFromIndex),
8682      *                   b, 0, Math.min(aToIndex - aFromIndex, bToIndex - bFromIndex))
8683      * }</pre>
8684      *
8685      * @param a the first array to be tested for a mismatch
8686      * @param aFromIndex the index (inclusive) of the first element in the
8687      *                   first array to be tested
8688      * @param aToIndex the index (exclusive) of the last element in the
8689      *                 first array to be tested
8690      * @param b the second array to be tested for a mismatch
8691      * @param bFromIndex the index (inclusive) of the first element in the
8692      *                   second array to be tested
8693      * @param bToIndex the index (exclusive) of the last element in the
8694      *                 second array to be tested
8695      * @return the relative index of the first mismatch between the two arrays
8696      *         over the specified ranges, otherwise {@code -1}.
8697      * @throws IllegalArgumentException
8698      *         if {@code aFromIndex > aToIndex} or
8699      *         if {@code bFromIndex > bToIndex}
8700      * @throws ArrayIndexOutOfBoundsException
8701      *         if {@code aFromIndex < 0 or aToIndex > a.length} or
8702      *         if {@code bFromIndex < 0 or bToIndex > b.length}
8703      * @throws NullPointerException
8704      *         if either array is {@code null}
8705      * @since 9
8706      */
8707     public static int mismatch(
8708             Object[] a, int aFromIndex, int aToIndex,
8709             Object[] b, int bFromIndex, int bToIndex) {
8710         rangeCheck(a.length, aFromIndex, aToIndex);
8711         rangeCheck(b.length, bFromIndex, bToIndex);
8712 
8713         int aLength = aToIndex - aFromIndex;
8714         int bLength = bToIndex - bFromIndex;
8715         int length = Math.min(aLength, bLength);
8716         for (int i = 0; i < length; i++) {
8717             if (!Objects.equals(a[aFromIndex++], b[bFromIndex++]))
8718                 return i;
8719         }
8720 
8721         return aLength != bLength ? length : -1;
8722     }
8723 
8724     /**
8725      * Finds and returns the index of the first mismatch between two
8726      * {@code Object} arrays, otherwise return -1 if no mismatch is found.
8727      * The index will be in the range of 0 (inclusive) up to the length
8728      * (inclusive) of the smaller array.
8729      *
8730      * <p>The specified comparator is used to determine if two array elements
8731      * from the each array are not equal.
8732      *
8733      * <p>If the two arrays share a common prefix then the returned index is the
8734      * length of the common prefix and it follows that there is a mismatch
8735      * between the two elements at that index within the respective arrays.
8736      * If one array is a proper prefix of the other then the returned index is
8737      * the length of the smaller array and it follows that the index is only
8738      * valid for the larger array.
8739      * Otherwise, there is no mismatch.
8740      *
8741      * <p>Two non-{@code null} arrays, {@code a} and {@code b}, share a common
8742      * prefix of length {@code pl} if the following expression is true:
8743      * <pre>{@code
8744      *     pl >= 0 &&
8745      *     pl < Math.min(a.length, b.length) &&
8746      *     IntStream.range(0, pl).
8747      *         map(i -> cmp.compare(a[i], b[i])).
8748      *         allMatch(c -> c == 0) &&
8749      *     cmp.compare(a[pl], b[pl]) != 0
8750      * }</pre>
8751      * Note that a common prefix length of {@code 0} indicates that the first
8752      * elements from each array mismatch.
8753      *
8754      * <p>Two non-{@code null} arrays, {@code a} and {@code b}, share a proper
8755      * prefix if the following expression is true:
8756      * <pre>{@code
8757      *     a.length != b.length &&
8758      *     IntStream.range(0, Math.min(a.length, b.length)).
8759      *         map(i -> cmp.compare(a[i], b[i])).
8760      *         allMatch(c -> c == 0) &&
8761      * }</pre>
8762      *
8763      * @param a the first array to be tested for a mismatch
8764      * @param b the second array to be tested for a mismatch
8765      * @param cmp the comparator to compare array elements
8766      * @param <T> the type of array elements
8767      * @return the index of the first mismatch between the two arrays,
8768      *         otherwise {@code -1}.
8769      * @throws NullPointerException
8770      *         if either array or the comparator is {@code null}
8771      * @since 9
8772      */
8773     public static <T> int mismatch(T[] a, T[] b, Comparator<? super T> cmp) {
8774         Objects.requireNonNull(cmp);
8775         int length = Math.min(a.length, b.length); // Check null array refs
8776         if (a == b)
8777             return -1;
8778 
8779         for (int i = 0; i < length; i++) {
8780             T oa = a[i];
8781             T ob = b[i];
8782             if (oa != ob) {
8783                 // Null-value comparison is deferred to the comparator
8784                 int v = cmp.compare(oa, ob);
8785                 if (v != 0) {
8786                     return i;
8787                 }
8788             }
8789         }
8790 
8791         return a.length != b.length ? length : -1;
8792     }
8793 
8794     /**
8795      * Finds and returns the relative index of the first mismatch between two
8796      * {@code Object} arrays over the specified ranges, otherwise return -1 if
8797      * no mismatch is found.  The index will be in the range of 0 (inclusive) up
8798      * to the length (inclusive) of the smaller range.
8799      *
8800      * <p>If the two arrays, over the specified ranges, share a common prefix
8801      * then the returned relative index is the length of the common prefix and
8802      * it follows that there is a mismatch between the two elements at that
8803      * relative index within the respective arrays.
8804      * If one array is a proper prefix of the other, over the specified ranges,
8805      * then the returned relative index is the length of the smaller range and
8806      * it follows that the relative index is only valid for the array with the
8807      * larger range.
8808      * Otherwise, there is no mismatch.
8809      *
8810      * <p>Two non-{@code null} arrays, {@code a} and {@code b} with specified
8811      * ranges [{@code aFromIndex}, {@code atoIndex}) and
8812      * [{@code bFromIndex}, {@code btoIndex}) respectively, share a common
8813      * prefix of length {@code pl} if the following expression is true:
8814      * <pre>{@code
8815      *     pl >= 0 &&
8816      *     pl < Math.min(aToIndex - aFromIndex, bToIndex - bFromIndex) &&
8817      *     IntStream.range(0, pl).
8818      *         map(i -> cmp.compare(a[aFromIndex + i], b[bFromIndex + i])).
8819      *         allMatch(c -> c == 0) &&
8820      *     cmp.compare(a[aFromIndex + pl], b[bFromIndex + pl]) != 0
8821      * }</pre>
8822      * Note that a common prefix length of {@code 0} indicates that the first
8823      * elements from each array mismatch.
8824      *
8825      * <p>Two non-{@code null} arrays, {@code a} and {@code b} with specified
8826      * ranges [{@code aFromIndex}, {@code atoIndex}) and
8827      * [{@code bFromIndex}, {@code btoIndex}) respectively, share a proper
8828      * if the following expression is true:
8829      * <pre>{@code
8830      *     (aToIndex - aFromIndex) != (bToIndex - bFromIndex) &&
8831      *     IntStream.range(0, Math.min(aToIndex - aFromIndex, bToIndex - bFromIndex)).
8832      *         map(i -> cmp.compare(a[aFromIndex + i], b[bFromIndex + i])).
8833      *         allMatch(c -> c == 0)
8834      * }</pre>
8835      *
8836      * @param a the first array to be tested for a mismatch
8837      * @param aFromIndex the index (inclusive) of the first element in the
8838      *                   first array to be tested
8839      * @param aToIndex the index (exclusive) of the last element in the
8840      *                 first array to be tested
8841      * @param b the second array to be tested for a mismatch
8842      * @param bFromIndex the index (inclusive) of the first element in the
8843      *                   second array to be tested
8844      * @param bToIndex the index (exclusive) of the last element in the
8845      *                 second array to be tested
8846      * @param cmp the comparator to compare array elements
8847      * @param <T> the type of array elements
8848      * @return the relative index of the first mismatch between the two arrays
8849      *         over the specified ranges, otherwise {@code -1}.
8850      * @throws IllegalArgumentException
8851      *         if {@code aFromIndex > aToIndex} or
8852      *         if {@code bFromIndex > bToIndex}
8853      * @throws ArrayIndexOutOfBoundsException
8854      *         if {@code aFromIndex < 0 or aToIndex > a.length} or
8855      *         if {@code bFromIndex < 0 or bToIndex > b.length}
8856      * @throws NullPointerException
8857      *         if either array or the comparator is {@code null}
8858      * @since 9
8859      */
8860     public static <T> int mismatch(
8861             T[] a, int aFromIndex, int aToIndex,
8862             T[] b, int bFromIndex, int bToIndex,
8863             Comparator<? super T> cmp) {
8864         Objects.requireNonNull(cmp);
8865         rangeCheck(a.length, aFromIndex, aToIndex);
8866         rangeCheck(b.length, bFromIndex, bToIndex);
8867 
8868         int aLength = aToIndex - aFromIndex;
8869         int bLength = bToIndex - bFromIndex;
8870         int length = Math.min(aLength, bLength);
8871         for (int i = 0; i < length; i++) {
8872             T oa = a[aFromIndex++];
8873             T ob = b[bFromIndex++];
8874             if (oa != ob) {
8875                 // Null-value comparison is deferred to the comparator
8876                 int v = cmp.compare(oa, ob);
8877                 if (v != 0) {
8878                     return i;
8879                 }
8880             }
8881         }
8882 
8883         return aLength != bLength ? length : -1;
8884     }
8885 }