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