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