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