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